WordPressのページネーションを出力する関数の「paginate_links()」と「the_posts_pagination()」の違いについて解説！

はじめに

WordPressで記事ページを作成するときに、ページネーションを作成します。ページネーションを作る方法はプラグインを使用する方法もありますが、「paginate_links()」と「the_posts_pagination()」を使用すれば、プラグインなしでもページネーションを作成することができるので、これらは便利な関数だと思っています。

ところで、「paginate_links()」と「the_posts_pagination()」の違いについて、気になったことはありませんか？

今回は2つの関数の違いについて解説しようと思います。

paginate_links()

paginate_links()に指定できる引数

base (string)

ページへのリンクの基本となるURL。%_% を含むと、WordPressが自動的にページ番号を挿入します。デフォルトは http://example.com/%_%。

format (string)

ページへのリンクのフォーマット。デフォルトは ?page=%#%。%#% はページ番号が挿入される部分です。

total (int)

ページの総数。通常は max_num_pages で指定します。

current (int)

現在のページ番号。

aria_current (string)

aria-current属性の値。可能な値は ‘page’、’step’、’location’、’date’、’time’、’true’、’false’ です。デフォルトは ‘page’。

show_all (bool)

すべてのページを表示するかどうか。デフォルトは false。

end_size (int)

ページリンクの先頭と末尾に表示される数字の数。デフォルトは 1。

mid_size (int)

現在のページの両側に表示される数字の数。デフォルトは 2。

prev_next (bool)

リストに前と次のリンクを含めるかどうか。デフォルトは true。

prev_text (string)

前のページのテキスト。デフォルトは ‘« Previous’。

next_text (string)

次のページのテキスト。デフォルトは ‘Next »’。

type (string)

返される値のフォーマットを制御します。可能な値は ‘plain’、’array’、’list’ です。デフォルトは ‘plain’。

add_args (array)

追加するクエリ引数の配列。デフォルトは false。

add_fragment (string)

各リンクに追加するフラグメント。

before_page_number (string)

ページ番号の前に挿入されるテキスト。

after_page_number (string)

ページ番号の後に挿入されるテキスト

paginate_links()の使用例

archive.phpやcategory.phpなどの記事一覧ページのファイルのページネーションを表示させたい場所に、下記を追加します。

<?php 
    $args = array(
        'mid_size' => 1,
        'prev_text' => '<span class="prev-arrow"></span>',
        'next_text' => '<span class="next-arrow"></span>',
    );
    echo paginate_links($args);
?>

「mid_size」のデフォルトは2ですが、ページ数が増えたときにスマホの方で、横幅いっぱいに収まらなくなることがあるので、ここでは1に変更しています。「prev_text」「next_text」には下記ページで紹介しているようなcssの矢印を指定しています。

矢印アイコン

サイトコーディングで頻出！HTML・CSSで作成した矢印アイコン（背景なし）のソースコードを紹介！

サイトコーディングで頻出のHTML・CSSで作成した矢印アイコン（背景なし）のソースコードを紹介しています。

paginate_links()の出力ソースコード

<!-- 前のページへ -->
<a class="prev page-numbers" href="#">
    <span class="prev-arrow"></span>
</a>
<!-- 1ページ目へ -->
<a class="page-numbers" href="#">1</a>
<!-- 2ページ目が現在のページ -->
<span aria-current="page" class="page-numbers current">2</span>
<!-- 3ページ目へ -->
<a class="page-numbers" href="#page/3">3</a>
<!-- 途中ページを省略するドットが表示 -->
<span class="page-numbers dots">…</span>
<!-- 17ページ目へ -->
<a class="page-numbers" href="#page/17">17</a>
<!-- 次のページへ -->
<a class="next page-numbers" href="#page/3">
    <span class="next-arrow"></span>
</a>

paginate_links()を使用した場合の表示

paginate_links()のみではページネーションのボタン部分しか出力されないため、上記の表示を見ればわかるようにスタイルを整えるのが難しいです。<div>タグなどのwrapper要素で包んであげればスタイルを整えることができます。

the_posts_pagination()

the_posts_pagination()に指定できる引数

screen_reader_text (string)

ナビゲーション要素のスクリーンリーダーテキスト。デフォルトは ‘投稿ナビゲーション‘。

aria_label (string)

ナビゲーション要素のARIAラベルテキスト。デフォルトは ‘投稿’。

class (string)

ナビゲーション要素に適用されるカスタムクラス。デフォルトは ‘pagination’。

後の引数はpaginate_linksのパラメータと同じです。

the_posts_pagination()の使用例

<?php
    the_posts_pagination(
        array(
            'mid_size' => 1,
            'prev_text' => '<span class="prev-arrow"></span>',
            'next_text' => '<span class="next-arrow"></span>',
        )
    );
?>

the_posts_pagination()の出力ソースコード

<nav class="navigation pagination" aria-label="投稿">
	<h2 class="screen-reader-text">投稿ナビゲーション</h2>
	<div class="nav-links">
        <a class="prev page-numbers" href="#">
            <span class="prev-arrow"></span>
        </a>
        <a class="page-numbers" href="#">1</a>
        <span aria-current="page" class="page-numbers current">2</span>
        <a class="page-numbers" href="#page/3">3</a>
        <span class="page-numbers dots">…</span>
        <a class="page-numbers" href="#page/17">17</a>
        <a class="next page-numbers" href="#page/3">
            <span class="next-arrow"></span>
        </a>
    </div>
</nav>

「paginate_links()」と「the_posts_pagination()」の出力ソースコードを比較すると、「the_posts_pagination()」の出力ソースコード内に、「paginate_links()」の出力ソースコードが含まれていることがわかります。

the_posts_pagination()を使用した場合の表示

「paginate_links()」と「the_posts_pagination()」の違い

出力されるソースコードが少ない方が良くて親要素のhtmlを自作がしたい方は「paginate_links()」を使用した方が良く、出力されたソースコードにcssを追加するだけが良いという方は「the_posts_pagination()」を使用した方が良いかもしれません。