ワードプレスのpaginate_links関数の使用方法・解説

概要

paginate_links関数は、ページネートリンクを取得するための便利な関数であり、主に以下のような機能を実装する際によく使われます。

1. 投稿一覧のページネーション
2. カスタムクエリのページネーション
3. アーカイブページのページネートリンク生成
4. カテゴリーページやタグページでのページネート表現
5. 固定ページのコンテンツ分割
6. ページネーションが必要なカスタム投稿タイプの処理
7. サイト内検索結果のページネーション
8. WooCommerceなどのeコマースサイトでの製品一覧のページネーション

構文

paginate_links( $args );

パラメータ

• total (int) – 総ページ数 (必須)
• current (int) – 現在のページ番号 (必須)
• format (string) – ページ番号のフォーマット (オプション)
• show_all (bool) – すべてのページリンクを表示するか (オプション)
• end_size (int) – 最初と最後のページで表示するリンク数 (オプション)
• mid_size (int) – 現在のページの前後で表示するリンク数 (オプション)
• prev_text (string) – 「前へ」リンクのテキスト (オプション)
• next_text (string) – 「次へ」リンクのテキスト (オプション)
• type (string) – 戻り値のタイプ (オプション。例: ‘plain’、’array’、’string’)
• add_args (array) – 追加のクエリ引数 (オプション)

戻り値

• stringまたはarray – 指定された条件に基づくページネートリンクのHTML。

関連する関数

• get_query_var
• paginate_links
• the_posts_pagination
• wp_parse_args

使用可能なバージョン

• WordPress 2.5.0以降

コアファイルのパス

• wp-includes/general-template.php

この関数のアクションでの使用可能性

アクション名	使用可能性
mu_plugin_loaded
registered_post_type	〇
plugins_loaded
wp_roles_init
setup_theme
after_setup_theme
set_current_user
init
register_sidebar
wp_loaded
send_headers
parse_query
pre_get_posts	〇
wp	〇
template_redirect
get_header
wp_head

paginate_links関数は特定のワードプレスバージョンで非推奨又は削除されたことはありません。

サンプルコード

1. 基本的なページネートリンクの生成

   $args = array(
      'total' => 10,
      'current' => 1
   );
   
   echo paginate_links( $args );
   

   このコードは、全10ページの中で現在のページが1である場合の基本的なページネーションリンクを生成します。

2. カスタムフォーマットによるページネートリンクの生成

   $args = array(
      'total' => 5,
      'current' => 2,
      'format' => '?paged=%#%',
      'prev_text' => __('« Prev'),
      'next_text' => __('Next »')
   );
   
   echo paginate_links( $args );
   

   カスタムフォーマットを用いてページネーションリンクを生成し、前後にテキストを追加しています。

3. 非表示リンクの設定

   $args = array(
      'total' => 20,
      'current' => 10,
      'show_all' => false,
      'end_size' => 1,
      'mid_size' => 2
   );
   
   echo paginate_links( $args );
   

   このコードでは、表示するページリンクを制限し、特定の範囲のみを表示します。

4. 追加クエリ引数を使ったページネートリンク

   $args = array(
      'total' => 5,
      'current' => 3,
      'add_args' => array( 'foo' => 'bar' )
   );
   
   echo paginate_links( $args );
   

   追加のクエリ引数を指定して、リンクにオプションを付与したページネーションリンクを生成します。

5. 配列で戻り値を取得

   $args = array(
      'total' => 15,
      'current' => 5,
      'type' => 'array'
   );
   
   $links = paginate_links( $args );
   if ( is_array( $links ) ) {
      foreach ( $links as $link ) {
          echo $link;
      }
   }
   

   ページネーションリンクを配列形式で取得し、各リンクをループして出力しています。