• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/paginate links

提供: WordPress Codex 日本語版
移動先: 案内検索

説明

アーカイブされた投稿ページのページ番号付きのリンクを取得します。この関数は(技術的には)任意のページへ飛ぶためのページ番号付きリンクを生成できます。(例: « Prev 1 … 3 4 5 6 7 … 9 Next » )

使い方

<?php echo paginate_links( $args ); ?>

引数の初期値

<?php $args = array(
	'base'               => '%_%',
	'format'             => '?page=%#%',
	'total'              => 1,
	'current'            => 0,
	'show_all'           => False,
	'end_size'           => 1,
	'mid_size'           => 2,
	'prev_next'          => True,
	'prev_text'          => __('&laquo; Previous'),
	'next_text'          => __('Next &raquo;'),
	'type'               => 'plain',
	'add_args'           => False,
	'add_fragment'       => '',
	'before_page_number' => '',
	'after_page_number'  => ''
); ?>

パラメータ

この関数の引数の配列はすべてオプションの指定になっていますが、必要な引数を指定しなければ何も出力されません。

base
文字列) (オプション) ページ番号付きのリンクを生成するために使われるベースの URL を指定します。例えば 'http://example.com/all_posts.php%_%' を指定すると、それに含まれる '%_%' は 'format' 引数(下記参照)により置き換えられます。
初期値: '%_%'
format
文字列) (オプション) ページネーションの構造を指定するのに使います。初期値は '?page=%#%' で、カスタムパーマリンク(「?」などの記号を含まない URL)を使いたい場合は、'/page/%#%' のように書けば '%#%' の部分がページ番号に置き換わります。
初期値: '?page=%#%'
total
整数) (オプション) 全体のページ数
初期値: 1
current
整数) (オプション) 現在のページ番号
初期値: 0
show_all
真偽値) (オプション) true の場合、現在のページ付近のページ番号の短いリストではなくすべてのページ番号が表示されます。デフォルトでは 'show_all' は false になっていますので、'end_size' と 'mid_size' 引数でコントロールされます。
初期値: false
end_size
整数) (オプション) ページ番号のリストの両端(最初と最後)にいくつの数字を表示するか。
初期値: 1
mid_size
整数) (オプション) 現在のページの両側にいくつの数字を表示するか。ただし現在のページは含みません。
初期値: 2
prev_next
真偽値) (オプション) リストの中に「前へ」「次へ」のリンクを含むかどうか。
初期値: true
prev_text
文字列) (オプション) 前のページへのリンクとして表示する文言。'prev_next' 引数が true のときだけ働きます。
初期値: __('&laquo; Previous')
next_text
文字列) (オプション) 次ページへのリンクとして表示する文言。'prev_next' 引数が true のときだけ働きます。
初期値: __('Next &raquo;')
type
文字列) (オプション) 戻り値の形式をコントロールします。可能な値は:
  • 'plain' – 改行文字によって区切られたリンクの文字列を返します。
  • 'array' – 表示を完全にコントロールできるようにページ送りのリンクを配列に入れて返します。
  • 'list' – HTMLの ul タグを使ったリストを返します。
初期値: 'plain'
add_args
配列) (オプション) 追加のクエリ引数の配列。
初期値: false
add_fragment
文字列) (オプション) それぞれのリンクに付け加える文字列。
初期値: なし
before_page_number
文字列) (オプション) ページ番号の直前に付け加える文字列。
初期値: なし
after_page_number
文字列) (オプション) ページ番号の直後に付け加える文字列。
初期値: なし

戻り値

mixed (配列|文字列) 
リンクの文字列または配列。

用例

基本的な例

検索結果とアーカイブのページにページ送りを追加したい時は次の例のように使います。

<?php
global $wp_query;

$big = 999999999; // need an unlikely integer

echo paginate_links( array(
	'base' => str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
	'format' => '?paged=%#%',
	'current' => max( 1, get_query_var('paged') ),
	'total' => $wp_query->max_num_pages
) );
?>

カスタムクエリを使用した例

new WP_Query でループのクエリを作成している場合、'total' パラメーターにWP_Queryオブジェクトの max_num_pages プロパティを設定してください。

カスタムクエリの例:

<?php
//Protect against arbitrary paged values
$paged = ( get_query_var( 'paged' ) ) ? absint( get_query_var( 'paged' ) ) : 1;

$args = array(
	'posts_per_page' => 5,
	'category_name' => 'gallery',
	'paged' => $paged,
);

$the_query = new WP_Query( $args );
?>
<!-- the loop etc.. -->

上のカスタムクエリに合わせて paginate_links のパラメータを設定した例:

<?php
$big = 999999999; // need an unlikely integer

echo paginate_links( array(
	'base' => str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
	'format' => '?paged=%#%',
	'current' => max( 1, get_query_var('paged') ),
	'total' => $the_query->max_num_pages
) );
?>

アクセシビリティー改良

スクリーン読み上げ機能の利用者がリンクの用途を理解できるように、番号付きリンクへコンテキストを追加するには:

<?php
global $wp_query;

$big = 999999999; // need an unlikely integer
$translated = __( 'Page', 'mytextdomain' ); // Supply translatable string

echo paginate_links( array(
	'base' => str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
	'format' => '?paged=%#%',
	'current' => max( 1, get_query_var('paged') ),
	'total' => $wp_query->max_num_pages,
	'before_page_number' => '<span class="screen-reader-text">' . $translated . ' </span>'
) );
?>

参考

変更履歴

ソースファイル

paginate_links()wp-includes/general-template.php にあります。

Related

ページネーション: posts_nav_link(), next_posts_link(), previous_posts_link(), get_next_posts_link(), get_previous_posts_link(), paginate_links(), wp_link_pages(), next_post_link(), previous_post_link(), next_image_link(), previous_image_link(), the_posts_pagination(), get_the_posts_pagination()


関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/paginate_links最新版との差分