当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「関数リファレンス/paginate links」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(関連: {{Tag Footer}})
(残りを和訳。誤記訂正。)
 
(他の1人の利用者による、間の2版が非表示)
1行目: 1行目:
 
== 説明 ==
 
== 説明 ==
  
アーカイブされた投稿ページのページ番号付きのリンクを取得します。この関数は任意のページに飛ぶためのページ番号付きリンクを生成します。 (例 : « Prev 1 3 4 5 6 7 9 Next » )
+
アーカイブされた投稿ページのページ番号付きのリンクを取得します。この関数は(技術的には)任意のページへ飛ぶためのページ番号付きリンクを生成できます。(例: &laquo; Prev 1 &#133; 3 4 5 6 7 &#133; 9 Next &raquo; )
  
 
== 使い方 ==
 
== 使い方 ==
7行目: 7行目:
 
<pre><?php echo paginate_links( $args ); ?></pre>
 
<pre><?php echo paginate_links( $args ); ?></pre>
  
===パラメータの初期値===
+
=== 引数の初期値 ===
  
 
<pre>
 
<pre>
 
<?php $args = array(
 
<?php $args = array(
'base'         => '%_%',
+
'base'               => '%_%',
'format'       => '?page=%#%',
+
'format'             => '?page=%#%',
'total'       => 1,
+
'total'             => 1,
'current'     => 0,
+
'current'           => 0,
'show_all'     => False,
+
'show_all'           => False,
'end_size'     => 1,
+
'end_size'           => 1,
'mid_size'     => 2,
+
'mid_size'           => 2,
'prev_next'   => True,
+
'prev_next'         => True,
'prev_text'   => __('&laquo; Previous'),
+
'prev_text'         => __('&amp;laquo; Previous'),
'next_text'   => __('Next &raquo;'),
+
'next_text'         => __('Next &amp;raquo;'),
'type'         => 'plain',
+
'type'               => 'plain',
'add_args'     => False,
+
'add_args'           => False,
'add_fragment' => ''
+
'add_fragment'       => '',
 +
'before_page_number' => '',
 +
'after_page_number'  => ''
 
); ?>
 
); ?>
 
</pre>
 
</pre>
29行目: 31行目:
 
== パラメータ ==
 
== パラメータ ==
  
この関数のパラメータの配列はすべて'''任意'''の指定になっていますが、必要な引数を指定していなければ何も出力されません。
+
この関数の引数の配列はすべて'''オプション'''の指定になっていますが、必要な引数を指定しなければ何も出力されません。
  
{{Parameter|base|string|URLを参照し、ページ番号付きのリンクを生成するために使われます。 '<tt>http://example.com/all_posts.php%_%</tt>'における初期値 '<tt>%_%</tt>'は'<tt>format</tt>' という引数 (下記参照)によって置き換えられます。|任意|'%_%'}}
+
{{Parameter|base|文字列|ページ番号付きのリンクを生成するために使われるベースの URL を指定します。例えば '<tt><nowiki>http://example.com/all_posts.php%_%</nowiki></tt>' を指定すると、それに含まれる '<tt>%_%</tt>' は '<tt>format</tt>' 引数(下記参照)により置き換えられます。|オプション|<tt>'%_%'</tt>}}
  
{{Parameter|format|string|<nowiki>ページネーションの構造を指定するのに使います。 初期値は'?page=%#%'で、プリティパーマリンク(「?」などの記号を含まないURL)を使いたい場合は、'/page/%#%'のように書けば、'%#%'の部分がページ番号に置き換わります。</nowiki>|任意|<nowiki>'?page=%#%'</nowiki>}}
+
{{Parameter|format|文字列|ページネーションの構造を指定するのに使います。初期値は <tt><nowiki>'?page=%#%'</nowiki></tt> で、カスタムパーマリンク(「?」などの記号を含まない URL)を使いたい場合は、<tt><nowiki>'/page/%#%'</nowiki></tt> のように書けば <tt><nowiki>'%#%'</nowiki></tt> の部分がページ番号に置き換わります。|オプション|<tt><nowiki>'?page=%#%'</nowiki></tt>}}
  
{{Parameter|total|integer|全体のページ数|任意|1}}
+
{{Parameter|total|整数|全体のページ数|オプション|1}}
  
{{Parameter|current|integer|現在のページ番号|任意|0}}
+
{{Parameter|current|整数|現在のページ番号|オプション|0}}
  
{{Parameter|show_all|boolean|Trueの場合、現在ページ付近のページ番号の短いリストではなくすべてのページ番号が表示されます。初期値では'<tt>show_all</tt>'はfalseになっていますので、'<tt>end_size</tt>'と'<tt>mid_size</tt>'の引数でコントロールします。|任意|False}}
+
{{Parameter|show_all|真偽値|true の場合、現在のページ付近のページ番号の短いリストではなくすべてのページ番号が表示されます。デフォルトでは '<tt>show_all</tt>' は false になっていますので、'<tt>end_size</tt>' と '<tt>mid_size</tt>' 引数でコントロールされます。|オプション|false}}
  
{{Parameter|end_size|integer|ページ番号のリストの両端(最初と最後)にいくつの数字を表示するか。|任意|1}}
+
{{Parameter|end_size|整数|ページ番号のリストの両端(最初と最後)にいくつの数字を表示するか。|オプション|1}}
  
{{Parameter|mid_size|integer|現在のページの両側にいくつの数字を表示するか。ただし現在のページは含みません。|任意|2}}
+
{{Parameter|mid_size|整数|現在のページの両側にいくつの数字を表示するか。ただし現在のページは含みません。|オプション|2}}
  
{{Parameter|prev_next|boolean|リストの中に「前へ」「次へ」のリンクを含むかどうか。|任意|True}}
+
{{Parameter|prev_next|真偽値|リストの中に「前へ」「次へ」のリンクを含むかどうか。|オプション|true}}
  
{{Parameter|prev_text|string|前のページへ送る時のリンクの文言。'<tt>prev_next</tt>' という引数を正しく設定しなければ動きません。|任意|__('&laquo; Previous')}}
+
{{Parameter|prev_text|文字列|前のページへのリンクとして表示する文言。'<tt>prev_next</tt>' 引数が true のときだけ働きます。|オプション|<tt>__('&amp;laquo; Previous')</tt>}}
  
{{Parameter|next_text|string|次のページへ送る時のリンクの文言。'<tt>prev_next</tt>'という引数を正しく設定しなければ動きません。|任意|__('Next &raquo;')}}
+
{{Parameter|next_text|文字列|次ページへのリンクとして表示する文言。'<tt>prev_next</tt>' 引数が true のときだけ働きます。|オプション|<tt>__('Next &amp;raquo;')</tt>}}
  
{{Parameter|type|string|戻り値をコントロールします。可能な値は:
+
{{Parameter|type|文字列|戻り値の形式をコントロールします。可能な値は:
 
<ul>
 
<ul>
<li>'<tt>plain</tt>' - 改行文字によって区切られたリンクの文字列を返します。</li>
+
<li>'<tt>plain</tt>' &ndash; 改行文字によって区切られたリンクの文字列を返します。</li>
<li>'<tt>array</tt>' - 表示を完全にコントロールできるようにページ送りのリンクを配列に入れて返します。</li>
+
<li>'<tt>array</tt>' &ndash; 表示を完全にコントロールできるようにページ送りのリンクを配列に入れて返します。</li>
<li>'<tt>list</tt>' - ulの[[wikipedia:HTML|HTML]]のリストを返します。 </li>
+
<li>'<tt>list</tt>' &ndash; [[wikipedia:ja:HTML|HTML]]の ul タグを使ったリストを返します。 </li>
 
</ul>
 
</ul>
|任意|'plain'}}
+
|オプション|<tt>'plain'</tt>}}
  
{{Parameter|add_args|array|追加のクエリ引数の配列。|任意|false}}
+
{{Parameter|add_args|配列|追加のクエリ引数の配列。|オプション|false}}
  
{{Parameter|add_fragment|string|それぞれのリンクに付け加える文字列。|任意}}
+
{{Parameter|add_fragment|文字列|それぞれのリンクに付け加える文字列。|オプション}}
 +
 
 +
{{Parameter|before_page_number|文字列|ページ番号の直前に付け加える文字列。|オプション}}
 +
 
 +
{{Parameter|after_page_number|文字列|ページ番号の直後に付け加える文字列。|オプション}}
  
 
== 戻り値 ==
 
== 戻り値 ==
{{Return|mixed|array&#124;string|リンクの文字列または配列。}}
+
 
 +
{{Return|mixed|配列&#124;文字列|リンクの文字列または配列。}}
  
 
== 用例 ==
 
== 用例 ==
  
* このページの用例を見てください。 [[Function_Reference/paginate_comments_links|<tt>paginate_comments_links()</tt>]].
+
* [[関数リファレンス/paginate_comments_links|<tt>paginate_comments_links()</tt>]] の用例も見てください。
 +
 
 +
=== 基本的な例 ===
 +
 
 +
検索結果とアーカイブのページにページ送りを追加したい時は次の例のように使います。
  
=== 基本的な用例 ===
 
検索結果のページにページ送りを追加したい時は次の例のように使います。:
 
 
<pre>
 
<pre>
 
<?php
 
<?php
87行目: 96行目:
 
</pre>
 
</pre>
  
=== カスタムクエリを使用した場合の用例 ===
+
=== カスタムクエリを使用した例 ===
  
[[Function_Reference/WP_Query|new WP_Query]] でループのクエリを作成している場合、'<tt>total</tt>'パラメーターにWP_Queryオブジェクトの<tt>max_num_pages</tt>プロパティを設定してください。
+
[[関数リファレンス/WP_Query|new WP_Query]] でループのクエリを作成している場合、'<tt>total</tt>' パラメーターにWP_Queryオブジェクトの <tt>max_num_pages</tt> プロパティを設定してください。
  
カスタムクエリの例は:
+
カスタムクエリの例:
 
<pre>
 
<pre>
 
<?php
 
<?php
$paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1;
+
//Protect against arbitrary paged values
 +
$paged = ( get_query_var( 'paged' ) ) ? absint( get_query_var( 'paged' ) ) : 1;
  
 
$args = array(
 
$args = array(
107行目: 117行目:
 
</pre>
 
</pre>
  
ページ送りリンクの引数を上のカスタムクエリに適用した例:
+
上のカスタムクエリに合わせて paginate_links のパラメータを設定した例:
 
<pre><?php
 
<pre><?php
 
$big = 999999999; // need an unlikely integer
 
$big = 999999999; // need an unlikely integer
120行目: 130行目:
 
</pre>
 
</pre>
  
== 注釈 ==
+
<div id="Improving_Accessibility">
 +
=== アクセシビリティー改良 ===
 +
</div>
  
* [[Migrating Plugins and Themes to 2.7/Enhanced Comment Display | Enhanced Comment Display]]も参照してください。
+
スクリーン読み上げ機能の利用者がリンクの用途を理解できるように、番号付きリンクへコンテキストを追加するには:
 +
<pre>
 +
<?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>'
 +
) );
 +
?>
 +
</pre>
 +
 
 +
<div id="Notes">
 +
== 参考 ==
 +
</div>
 +
 
 +
* [[Migrating Plugins and Themes to 2.7/Enhanced Comment Display | Enhanced Comment Display]] もご覧ください。
  
 
== 変更履歴 ==
 
== 変更履歴 ==
  
* Since: [[Version 2.1|2.1.0]]
+
* [[Version 2.1|2.1.0]] : 新規導入
  
 
== ソースファイル ==
 
== ソースファイル ==
  
<tt>paginate_links()</tt>は{{Trac|wp-includes/general-template.php}}の中にあります。
+
<tt>paginate_links()</tt> は {{Trac|wp-includes/general-template.php}} にあります。
  
== 関連 ==
+
== Related ==
 
{{Pagination}}
 
{{Pagination}}
  
 
{{Tag Footer}}
 
{{Tag Footer}}
  
{{原文|Function Reference/paginate links|141916}}<!-- March 2014 F J Kaiser  -->
+
{{原文|Function Reference/paginate_links|151763}} <!-- 14:58, 22 May 2015 Miccweb 版 -->
 +
 
 +
{{DEFAULTSORT:Paginate_links}}
 +
[[Category:関数]]
 +
 
 +
[[en:Function_Reference/paginate_links]]

2015年6月27日 (土) 14:58時点における最新版

説明

アーカイブされた投稿ページのページ番号付きのリンクを取得します。この関数は(技術的には)任意のページへ飛ぶためのページ番号付きリンクを生成できます。(例: « Prev 1 &#133; 3 4 5 6 7 &#133; 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最新版との差分