テンプレートタグ/wp list pages

この項目「テンプレートタグ/wp list pages」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

説明

テンプレートタグ wp_list_pages() は固定ページへのリンクのリスト (以下ページリストとする) を表示します。しばしばサイドバー/en やヘッダー/en をカスタマイズするのに使われますが、他のテンプレートにも同様に使えるかもしれません。

使い方

<?php wp_list_pages( $args ); ?>

用例

初期設定での使用

<?php $args = array(
	'authors'      => '',
	'child_of'     => 0,
	'date_format'  => get_option( 'date_format' ),
	'depth'        => 0,
	'echo'         => 1,
	'exclude'      => '',
	'include'      => '',
	'link_after'   => '',
	'link_before'  => '',
	'post_type'    => 'page',
	'post_status'  => 'publish',
	'show_date'    => '',
	'sort_column'  => 'menu_order, post_title',
	'sort_order'   => '',
	'title_li'     => __('Pages'), 
	'walker'       => new Walker_Page
); ?>

デフォルトでは以下のように動作します。

すべてのページとサブページを表示します (階層制限はありません)
ページの作成日は表示しません
すべてのページの子ページに関する制限はありません
除外されるページはありません
リストの見出しが「ページ」となります
結果は echo されます (表示されます)
ページの作成者による制限はありません
ページのタイトル順にソートされます
昇順にソートされます (上述の例には載っていません)

ページの親子関係をインデントして表示します (上述の例には載っていません)
すべてのページが含まれます (上述の例には載っていません)
特定のメタキーやメタ情報による制限はありません (上述の例には載っていません)
親子関係のないツリーを除く

パラメータ

参考: ほとんどの引数は get_pages() から引き継いでいます。

sort_column

(文字列) ページのリストをいろいろな順序で並び替えます。デフォルトでは'ページタイトルのアルファベット順に並び替えます

'post_title' - (タイトルを) アルファベット順に並び替えます - デフォルト
'menu_order' - ページ順序によって並び替えます。要注意: ページ順序とページ ID に注意してください。ページ ID はそれぞれの記事やページにつけられた唯一の番号です。ページ順序はページ > ページ編集画面でユーザーがつける番号のことです。上述の例をお読みください
'post_date' - 作成日順に並び替えます
'post_modified' - 最終更新日順に並び替えます
'ID' - ページ ID 順に並び替えます
'post_author' - ページ作成者の ID 順に並び替えます
'post_name' - ページスラッグ (パーマリンク) のアルファベット順に並び替えます

注意: sort_column パラメータは WordPress のデータベースの wp_post テーブル内のあらゆるフィールドの記述子を使ってページのリストを並び替えることができます。

sort_order

(文字列) ページリストの並び順を変更します (昇順または降順)。デフォルトは昇順です

'ASC' - 低いほうから高いほうへ並び替えます（デフォルト）
'DESC' - 高いほうから低いほうへ並び替えます

exclude: (文字列) リストから除外したいページの ID をコンマで区切ったリストで定義します (例: 'exclude=3,7,31')。デフォルト値はありません。特定のページを除外する例をお読みください。

exclude_tree: （文字列）除外したい親ページの ID をカンマ区切りで指定します。指定した親ページとその子ページ全てを除外するには、このパラメータを使います。'exclude_tree=5' とすれば、ページ ID 5と、ページ ID 5を親とする子ページ全て（子も孫も全て）が除外されます。; (なお、このパラメータはバージョン 2.7 で追加されましたが、バージョン 2.8.1 の説明通りには動作しません - バグ報告を見てください。)

include: (文字列) wp_list_pages で生成されるリストに特定のページだけを含めます。exclude と同様に、このパラメータもコンマで ID を区切ったリストで定義します。特定のページだけを含める例をお読みください

depth

(整数) このパラメータは wp_list_pages で生成されるリストに含めるページの階層レベルを設定します。デフォルト値は 0 です (すべてのページとサブページを表示します)。

0 - ページとサブページを親子関係を維持して (インデントして) 表示します (デフォルト)
-1 - ページとサブページを同列に (インデントなし) 表示します
1 - トップレベルのページのみ表示します
2, 3 - 2 (または3以上) の深さ (レベル) のページを表示します

child_of: (整数) ページ ID を値としてそのページのサブページのみを表示します。デフォルト値は 0 です (すべてのページを表示)。

show_date

(文字列) それぞれのページの作成日または最終更新日を表示します。デフォルト値は空です (日付を表示しません)。

'' - 日付を表示しません (デフォルト)
'modified' - 最終更新日を表示します
上記以外 - modified 以外の値は作成日 (post_date) を表示します。上述の例をお読みください

date_format: (文字列) show_date パラメータで使うページの日付の書式を設定します (例: "l, F j, Y")。このパラメータは WordPress の管理画面で設定した日付フォーマットをデフォルトとします。日付と時刻の書式と PHPマニュアルの日時の書式化のページをお読みください

title_li: (文字列) ページリストの見出しのテキストとスタイルを設定します。デフォルトは __('Pages') です。ブログ上では「ページ」と表示されます (__('') はローカライゼーションのためのものです)。空の値のとき ('') は見出しを表示しません。また、リストは <ul>, </ul> タグで包まれていません。見出しの例をお読みください

echo

(論理値) ページリストを表示するか、PHP で使うために HTML テキストとして返すかを設定します。デフォルト値は 1 (リストを表示) です。

1 (True) - デフォルト
0 (False)

hierarchical

(論理値) サブページを親ページの下にインデントして表示するかインラインで表示するかを設定します。デフォルトは true です (サブページを親ページの下にインデントして表示)

1 (True) - デフォルト
0 (False)

meta_key: (文字列) ここに記述したカスタムフィールドキーを持つページだけを表示します (meta_value フィールドと同時に使います)。

meta_value: (文字列) ここに記述したカスタムフィールド値を持つページだけを表示します (meta_key フィールドと同時に使います)。

link_before: (文字列) <a> タグリンクの前に表示されるテキストまたは HTML (バージョン2.7.0で追加されたパラメータ )
link_after: (文字列) <a> タグリンクの後に表示されるテキストまたは HTML (バージョン2.7.0で追加されたパラメータ )
authors: (文字列) 指定した著者 ID (複数の場合はカンマで区切る) のページのみを表示します。指定しない場合は全著者が対象になります。
number: (文字列) 表示するページの数を指定します。SQL LIMIT 値を指定します。デフォルト値は「制限無し」です。バージョン2.8で追加されました。注意: これは現在動作しません。Trac ticket #10230をお読みください。
offset: (文字列) ページの取得開始位置を飛ばす数です。デフォルト値は、オフセット無しです。(バージョン2.8で追加されたパラメータ )

post_type

(文字列) 階層を持つ種類の、指定された投稿タイプの投稿をリストします。デフォルトは 'page' です。有効な値は:

'page' - 固定ページ。
'revision' - リビジョン。
階層を持つカスタム投稿タイプ。

post_status: (文字列) 返したい投稿のステータスのタイプをコンマ区切りでリストにします。例えば: 'publish,private,draft'

用例

リストの見出しを隠す、変える

wp_list_pages() が表示するページリストのデフォルトの見出し (「ページ」) は title_li パラメータに空の値を入れると非表示にできます。以下の例はページリストの上に見出しのテキストを表示しません。

<ul>
<?php wp_list_pages( array( 'title_li' => '' ) ); ?>
</ul>

下記の例では ID が 9, 5, 23 のページだけを表示し、見出しのテキストを「Poetry」に置き換え、タグを <h2> に変更しています。

<ul>
<?php wp_list_pages( array(
    'include'  => array( 5, 9, 23 ),
    'title_li' => '<h2>' . __('Poetry') . '</h2>'
) ); ?>
</ul>

リストの順序を変える

下の例ではページ > 新規追加で設定されたページ順序に従ってページリストを表示します。

<ul>
    <?php wp_list_pages( array( 'sort_column' => 'menu_order' ) ); ?>
</ul>

もしページ順序に従ってページリストを表示し、サイドバーに表示される見出しを「Prose」 (h2 タグスタイルで) と表示したい場合は、下のコードを sidebar.php ファイルに追加してください (サイドバーウィジェットを使用している場合は管理画面から)。

<ul>
    <?php wp_list_pages(
        'sort_column=menu_order&title_li=<h2>' . __('Prose') . '</h2>'
    ); ?>
</ul>

以下のコードを使うと、見出しなしでページ順序に従い表示します。

<ul>
    <?php wp_list_pages( 'sort_column=menu_order&title_li=' ); ?>
</ul>

作成日順に並び替える

この例はページの作成日でソートし、その日付をページごとに表示します。

<ul>
    <?php wp_list_pages( 'sort_column=post_date&show_date=created' ); ?>
</ul>

特定のページを除外する

exclude パラメータを使うと、wp_list_pages() が表示するページリストから特定のページを除外することができます。

<ul>
    <?php wp_list_pages( 'exclude=17,38' ); ?>
</ul>

特定のページだけを含める

特定のページだけをリストに含めたい場合 (例えば ID が 35, 7 ,26, 13 のページ) は、include パラメータを使用します。

<ul>
    <?php wp_list_pages(
        'include=7,13,26,35&title_li=<h2>' . __('Pages') . '</h2>'
    ); ?>
</ul>

サブページの表示 (WordPress 2.0.1 以前)

使用中の WordPress のテーマの page.php テンプレートの the_post() セクション内の the_content() の後にこれを追加するか、サブページがあるページの page.php テンプレートのコピーに追加します。

<ul>
    <?php
    global $id;
    wp_list_pages(
        "title_li=&child_of=$id&show_date=modified&date_format=$date_format"
    ); ?>
</ul>

注意: この例は WordPress 2.0.1 以降ではページテンプレートに追加しても $id というグローバル変数がセットされていないので機能しません。替わりに以下のコードを使用してください。

サブページの表示 (WordPress 2.0.1 以降)

注意: サブページがない場合でも、HTML タグ (<ul> や <ol>) が表示されます。スタイルシートを使ってリストのデザインをしている場合はこのことを覚えておいてください。

<ul>
    <?php
    wp_list_pages(
        'title_li=&child_of='.$post->ID.'&show_date=modified&date_format=$date_format'
    ); ?>
</ul>

以下の例は表示中のページに子ページ (表示中のページを親ページと設定しているページ) が存在する場合のみリストを表示します。

<?php
$children = wp_list_pages( 'title_li=&child_of='.$post->ID.'&echo=0' );
if ( $children ) { ?>
    <ul>
        <?php echo $children; ?>
    </ul>
<?php } ?>

サブページの中でもサブページのリストを表示する

上述の例では親ページでは子ページを表示しますが、子ページでは表示しません。次のコードは親ページでも子ページでも、子ページのリストを表示します。

注: このコードは、サイドバーのウィジェットブロックの後ろに置くと動作しません。

<?php
if ( $post->post_parent )
    $children = wp_list_pages( "title_li=&child_of=".$post->post_parent."&echo=0" );
else
    $children = wp_list_pages( "title_li=&child_of=".$post->ID."&echo=0" );
if ($children) { ?>
    <ul>
        <?php echo $children; ?>
    </ul>
<?php } ?>

次の例は別の方法です。このコードは sidebar.php の中にあり、トップ階層のページにのみ表示されます。しかし子ページを持つ（もしくはそのページ自身が子ページである）ページを参照するとき、その親ページの子ページのみを表示します。

メインページを参照するとき、全てのトップ階層のページはサイドバーの中にリスト化されます。
子ページを持たないトップ階層のページを参照するとき、全てのトップ階層のページがリスト化されます。
子ページを持つトップ階層のページを参照するとき、子ページとそれよりも下層のページがリスト化されます。
親ページの子ページとそれよりも下層ページを参照するとき、リスト化されます。

<?php
$output = wp_list_pages( 'echo=0&depth=1&title_li=<h2>Top Level Pages </h2>' );
if ( is_page() ) {
    $page = $post->ID;
    if ( $post->post_parent ) {
        $page = $post->post_parent;
    }
    $children　=　wp_list_pages( 'echo=0&child_of=' . $page . '&title_li=' );
    if ( $children ) {
        $output = wp_list_pages ( 'echo=0&child_of=' . $page . '&title_li=<h2>Child Pages</h2>' );
    }
}
echo $output;
?>

指定した親のすべての子孫ページをリストする

次の例はすべてのトップレベルページと下記のページをリストします。

トップレベルページを指定すると - そのページの子ページ
サブページを指定すると - その兄弟ページ、ただし他のトップページの子ではないもの

<?php
$ancestor_id = 1843;	//このコードは仮のもの。
$descendants = get_pages( array( 'child_of' => $ancestor_id ) );
$incl = "";

foreach ( $descendants as $page ) {
	if ( ( $page->post_parent == $ancestor_id ) ||
		 ( $page->post_parent == $post->post_parent ) ||
		 ( $page->post_parent == $post->ID ) )
	{
		 $incl .= $page->ID . ",";
	}
}?>

<ul>
	<?php wp_list_pages( array(
		"child_of" => $ancestor_id, 
		"include" => $incl, 
		"link_before" => "", 
		"title_li" => "", 
		"sort_column" => "menu_order" ) ); ?>
</ul>

全てのサブページをリスト表示

次の例はすべてのサブページをリスト表示します。

<?php
if( ! $post->post_parent ) {
    // Will display the subpages of this top level page.
    $children = wp_list_pages( array(
        'title_li' => '',
        'child_of' => $post->ID,
        'echo'     => 0
    ) );
} else {
    if ( $post->ancestors ) {
        /*
         * Now you can get the the top ID of this page. WordPress is putting the ids DESC,
         * thats why the top level ID is the last one.
         */
        $ancestors = get_post_ancestors( $this_page );
        $children  = wp_list_pages( array(
            'title_li' => '',
            'child_of' => $ancestors,
            'echo'     => 0
        ) );
    }
}
 
if ( $children ) : ?>
    <ul>
        <?php echo $children; ?>
    </ul>
<?php endif; ?>

親ページとすべての子孫ページを表示

特定の親ページから始まるツリー (親と全世代の子孫ページ) を表示する指定方法は wp_list_pages() にありません。そこで次の例は、ある親ページのすべての子ページを get_pages() を使って取得した後、wp_list_pages() を使って「家系図」を表示します。

<?php 
// wp_list_pages を使ってある親ページとすべての世代の子ページをツリー表示する。
$parent = 93;
$args   = array( 'child_of' => $parent );
$pages  = get_pages( $args );
 
if ( $pages ) {
    $pageids = array();
    foreach ( $pages as $page ) {
        $pageids[] = $page->ID;
    }
 
    $args = array(
        'title_li' => sprintf( __( 'Tree of Parent Page %s', 'textdomain' ), $parent ),
        'include'  =>  $parent . ',' . implode( ",", $pageids )
    );
    wp_list_pages( $args );
}
?>

現在のページと先祖ページと子ページをリスト表示

次の例は現在の固定ページと、そのページの先祖ページおよび子ページをリスト表示します。 child_of はすべての子孫ページを表示するので、代わりに wpdb を使って直接の子ページだけを取得します。

<?php
// 親ページがある場合。
if( $post->post_parent ) {
    // 先祖ページを取得。
    $relations = get_post_ancestors( $post->ID );
 
    // 直接の子ページを取得。
    $result = $wpdb->get_results( $wpdb->prepare( "SELECT ID FROM wp_posts WHERE post_parent = %s AND post_type = %s", $post->ID, 'page' ) );
    if ( $result ) {
        foreach ( $result as $page ) {
            array_push( $relations, $page->ID );
        }
    }
 
    // 現在のページをリストへ追加。
    array_push( $relations, $post->ID );
 
    // 子と先祖と自ページをコンマ区切りリストにする。
    $relations_string = implode( ",",$relations );
 
    // include を使って集めたページだけをリスト表示する。
    $sidelinks = wp_list_pages( array(
        'title_li' => '',
        'echo'     => 0,
        'include'  => $relations_string
    ) );
} else {
    // ルートレベルのページと直接の子ページだけを表示。
    $sidelinks = wp_list_pages( array(
        'title_li' => '',
        'echo'     => 0,
        'depth'    => 1,
        'child_of' => $post->ID
    ) );
}
 
if ( $sidelinks ) : ?>
    <h2><?php the_title(); ?></h2>
    <ul>
        <?php
        // リンクは <li> タグで囲まれている。
        echo $sidelinks;
        ?>
    </ul>         
<?php endif; ?>

最上位の祖先ページとその直接の子ページをリスト表示

次の例は現在のページに関して、最上位の先祖ページとその直接の子ページを表示します。これはすっきりした二次サブナビゲーションに役立ちます。

まず、下記の関数を作成します (テーマで使うなら functions.php に記述するのが良いでしょう):

if ( ! function_exists( 'wpdocs_get_post_top_ancestor_id' ) ) {
/**
 * Gets the id of the topmost ancestor of the current page.
 *
 * Returns the current page's id if there is no parent.
 * 
 * @return int ID of the top ancestor page.
 */
function wpdocs_get_post_top_ancestor_id() {
    if ( ! $post = get_post() ) {
        return;
    }
     
    $top_ancestor = $post->ID;
    if ( $post->post_parent ) {
        $ancestors = array_reverse( get_post_ancestors( $post->ID ) );
        $top_ancestor = $ancestors[0];
    }
     
    return $top_ancestor;
}
} // Exists.

次に、テーマへ下記のコードを追加します (メニューを表示したいところへ):

<ul class="clearfix">
    <?php
    wp_list_pages( array(
        'title_li' => '',
        'include'  => wdocs_get_post_top_ancestor_id()
    ) );
     
    wp_list_pages( array(
        'title_li' => '',
        'depth'    => 1,
        'child_of' => wpdocs_get_post_top_ancestor_id()
    ) );
    ?>
</ul>

ホームページのリスト

ブログページへのリンクを同様に表示したい場合は wp_page_menu() を使ってください。

カスタム投稿タイプのリストのメンバー

階層を持つカスタム投稿タイプであれば、wp_list_pages() を使ってそのリストを表示できます。次の例はカスタム投稿タイプ Portfolio を表示します:

<?php 
$args = array(
    'post_type' => 'portfolio',
    'title_li'  => __( 'Portfolio', 'textdomain' )
);
wp_list_pages( $args );
?>

ページアイテムのマークアップとデザイン

デフォルトでは、wp_list_pages() はページ > 新規追加で作成した WordPress ページを入れ子で順不同のリストに表示します。あなたは最外部のアイテム (li.pagenav) をなくすことも、title_li パラメータを空の値にすることもできます。

wp_list_pages() が表示するすべてのリストアイテム (li) には page_item というクラスが付けられています。wp_list_pages() をページ表示時に呼び出すと、そのページを指すリストアイテムには current_page_item というクラスが追加されます。

<li class="pagenav">
Pages [title_li]
  <ul>
    <!-- Output starts here if 'title_li' parameter is empty -->
    <li class="page-item-2 page_item current_page_ancestor current_page_parent">
      [parent of the current Page]
      <ul>
        <li class="page-item-21 page_item current_page_item">
          [the current Page]
        </li>
      </ul>
    </li>
    <li class="page-item-3 page_item">
      [another Page]
    </li>
  </ul>
</li>

これらは CSS セレクタでデザインできます。

.pagenav { … } /* the outermost list item; contains whole list */
.page-item-2 { … } /* item for Page ID 2 */
.page_item { … } /* any Page item */
.current_page_item { … } /* the current Page */
.current_page_parent { … } /* parent of the current Page */
.current_page_ancestor { … } /* any ancestor of the current Page */

参考

合わせて読む: wp_page_menu(), get_pages()

変更履歴

2.8 : パラメータ 'number', 'offset' が追加されました。
2.7 : パラメータ 'link_before', 'link_after', 'exclude_tree' が追加されました。
1.5 : 新規テンプレートタグ

ソースファイル

wp_list_pages() は wp-includes/post-template.php にあります。

リスト・ドロップダウン関数： wp_list_authors(), wp_list_categories(), wp_list_pages(), wp_list_bookmarks(), wp_list_comments(), wp_get_archives(), wp_page_menu(), wp_dropdown_pages(), wp_dropdown_categories(), wp_dropdown_users()

記事

記事: ループ - WordPress ループ内でのクエリの使い方に関する基本的概要。
記事: クエリ概要 - どのクエリが WordPress で生成されているかを判断するための説明。
記事: フックを使ったクエリのカスタマイズ
記事: MYSQL カスタムセレクトクエリ /en
記事: 高度なタクソノミークエリ /en
記事: オフセット・ペジネーションを使ったカスタムクエリ /en

コードドキュメンテーション

クラス: WP_Query - WP_Query クエリの詳細概要
オブジェクト: $wpdb - $wpdb オブジェクトの使い方概要
関数: get_query_var()
関数: query_posts() - 追加カスタムクエリの作成
関数: get_post() - 項目の ID を使ってその投稿のレコードをデータベースから取得する
関数: get_posts() - 項目の配列を返す特別な関数。
関数: get_pages() - ページの配列を返す特別な関数。
関数: have posts() - クエリが記事を返すかどうか判断する条件分岐。
関数: the_post() - クエリの後に自動的にループを設定するのに使われる。
関数: rewind_posts() - 現在のループをクリアする。
関数: setup_postdata() - ループ内で単一クエリ結果のデータを設定する。
関数: wp_reset_postdata() - 以前のクエリを復元する（通常、ループ内のもう一つのループで使われる）。
関数: wp_reset_query()
関数: is_main_query() - 変更するのがメインクエリであるよう保証する。
アクションフック: pre_get_posts - 実行される前に WordPress クエリを変更する。
アクションフック: the_post - 投稿オブジェクトをクエリの後に変更する。
フィルターフック: found_posts - found_posts WP_Query オブジェクトの値を変更する