WordPress 4.1のthe_posts_pagination()は投稿一覧へ番号リンクを出す

WordPress 4.1で投稿一覧に番号付きのページ移動を出すなら、Loopのあとでthe_posts_pagination()を呼びます。この関数は、現在ページの周囲に番号を出し、前と次へのlinkを一つのnavigationとしてまとめます。

一件の投稿を前後へ移動する関数ではありません。また、投稿の取得条件や一ページの表示件数を決める関数でもありません。まずメインクエリで一覧を作り、その結果を別ページへ移動する出口として使います。

the_posts_pagination()はLoopのあとへ置く

WordPress Coreのtemplate tagに関する説明では、the_posts_pagination()を、投稿一覧のpage間を番号付きで移動するtemplate tagとして案内しています。

home.php、archive.php、search.phpなど、複数の投稿を表示するtemplateで、Loopを閉じたあとへ置きます。

<?php if ( have_posts() ) : ?>

	<?php while ( have_posts() ) : ?>
		<?php the_post(); ?>
		<article>
			<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
		</article>
	<?php endwhile; ?>

	<?php
	the_posts_pagination( array(
		'mid_size' => 1,
		'prev_text' => '前へ',
		'next_text' => '次へ',
	) );
	?>

<?php endif; ?>

template名とHTMLは説明用です。実際のthemeでは、既存のLoop、見出し階層、classに合わせてください。

番号付きと前後だけのnavigationを分ける

WordPress 4.1には、一覧用として二種類のtemplate tagがあります。

番号を出せるからという理由だけでthe_posts_pagination()を選ぶ必要はありません。読者が途中のpageへ直接移る必要があるか、前後へ順に読めればよいかで選びます。

単一投稿で使うthe_post_navigation()は別の関数です。名前が似ていますが、postsは投稿一覧、postは一件の投稿を指します。templateへ追加する前に、対象画面が一覧か単一投稿かを確認してください。

引数は必要な文字と番号幅だけ変える

WordPress 4.1のsourceでは、the_posts_pagination()がget_the_posts_pagination()の結果を表示します。内部ではpaginate_links()を使い、既定値として現在ページの左右へ一つの番号を出すmid_size、前後のlink text、読み上げ用の見出しを持ちます。

たとえば、現在ページの左右へ二つずつ番号を出したい場合は、次のように指定します。

the_posts_pagination( array(
	'mid_size'  => 2,
	'prev_text' => '前のページ',
	'next_text' => '次のページ',
) );

引数はpaginate_links()と共通ですが、typeは指定せず、既定のplainにします。navigation全体をHTML文字列として組み立てるため、WordPress Coreの説明でもtypeを例外としています。

番号を増やすほど親切になるわけでもありません。小さな画面で折り返すなら、mid_sizeを減らすか、前後だけのnavigationを選びます。文字列、番号数、CSSを別々に増やさず、利用者が現在位置と移動先を識別できる最小の構成にします。

出力済みのnavigation構造をthemeへ合わせる

WordPress Coreは、linkをnav要素、読み上げ用の見出し、nav-linksのcontainerで包みます。paginationにはnavigationとpaginationのclassが付きます。独自のwrapperを重ねる前に、実際のHTMLを確認してください。

themeのCSSでは、次を分けて指定します。

• navigation全体の余白
• 番号linkと現在ページの見分け方
• 前と次のlink
• keyboard focus
• 小さな画面での折り返し

読み上げ用見出しを画面から隠す場合も、display: noneで情報自体を消さず、themeで使っているscreen reader向けclassへ合わせます。WordPressが用意した構造を、見た目だけを理由に削らないでください。

メインクエリの総page数を使う

WordPress 4.1のget_the_posts_pagination()は、globalなwp_queryのmax_num_pagesを調べます。総page数が一以下なら、空のnavigationを出しません。

したがって、メインクエリの一覧へ使う場合は、表示件数と現在pageをWordPressが計算したあとで呼びます。別に作ったWP_Queryの直後へ関数を置いても、そのquery objectを引数として渡せるわけではありません。独自queryのページ移動は、総page数と現在pageをどの関数へ渡すかを別に設計します。

一覧の表示件数を変えたい場合も、paginationの引数ではなくquery側で設定します。取得条件とnavigationを同じ修正へ詰め込むと、page 2で同じ条件を再現できない原因を切り分けにくくなります。

page 2と最終pageまで確認する

実装後は、一page目だけを見て終えません。

1. 投稿数が一pageに収まる一覧ではnavigationが出ないことを確認する
2. 二page以上ある一覧で、現在pageの番号が区別できることを確認する
3. page 2でURL、一覧内容、前後linkを確認する
4. 最終pageで次へのlinkが不要になることを確認する
5. 検索結果、category、日付archiveなど、使うtemplateごとに確認する

制作会社へtheme修正を頼む場合は、変更したtemplate、対象としたWordPressの版、確認した一覧種別とpage番号を受け取ります。実装を委託しても、一pageの表示件数と一覧の並び順を決める責任は、サイト運営側に残してください。

最初の一手は、theme内で一覧のLoopを持つtemplateを探し、その直後に既存のnavigationがあるかを確認することです。古いlinkを残したまま新しいpaginationを追加せず、一画面に一つの一覧navigationへそろえてください。