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

説明

リンク付きカテゴリーリストを表示します。カテゴリーリンクをクリックすると、テンプレート階層ルールに基づく適切なカテゴリーテンプレートを用いたカテゴリーページに、そのカテゴリーに属する全ての投稿が表示されます。

参考: wp_list_categories() は、WordPress 2.1 で非推奨となった list_cats() および wp_list_cats() の後継で、この二つとほぼ同じように動作します。

フォーマットしていない結果が必要な場合は、get_categories() をお試しください。

使い方

<?php wp_list_categories( $args ); ?>

デフォルトの使い方

<?php 
    $args = array(
	'show_option_all'    => '',
	'orderby'            => 'name',
	'order'              => 'ASC',
	'style'              => 'list',
	'show_count'         => 0,
	'hide_empty'         => 1,
	'use_desc_for_title' => 1,
	'child_of'           => 0,
	'feed'               => '',
	'feed_type'          => '',
	'feed_image'         => '',
	'exclude'            => '',
	'exclude_tree'       => '',
	'include'            => '',
	'hierarchical'       => 1,
	'title_li'           => __( 'Categories' ),
	'show_option_none'   => __( '' ),
	'number'             => null,
	'echo'               => 1,
	'depth'              => 0,
	'current_category'   => 0,
	'pad_counts'         => 0,
	'taxonomy'           => 'category',
	'walker'             => null
    );
    wp_list_categories( $args ); 
?>

デフォルトでは次のように表示します：

全カテゴリーページへのリンクなし
リストはカテゴリー名の昇順
番号なし箇条書きリスト形式で表示
投稿数は非表示
投稿のあるカテゴリーのみ表示
カテゴリーの「説明」を title 属性にセット
子カテゴリーの制限なし
フィードへのリンクなし／リンク画像なし
表示カテゴリーの指定／除外なし
現在のカテゴリーを CSS クラスサフィックス 'current-cat' とともに表示
カテゴリーレベルをインデント表示（ネスト表示、ツリー表示）
リストの前に、見出しとして「Category」（日本語化ファイルで定義されていればその文字列）を表示
SQL LIMIT なし
リストを表示（バージョン 2.3 以降では、表示／値の取得を選べる）
表示する階層の深さ制限なし
全カテゴリー
Walker_Category クラスでリストをレンダリング

パラメータ

show_option_all: （文字列）ブランク以外の文字列を設定すると、全カテゴリーの記事を表示するページ（ブログのトップページ）へのリンクを、カテゴリーリストの先頭に表示します。リンクテキストはこのパラメータで指定した文字列です。デフォルト値は "NULL" (すべてのカテゴリーリンクは表示されません）。

orderby

（文字列）カテゴリーのソート項目。初期値はカテゴリー名でソート。有効な値は：

ID - カテゴリーID
name - カテゴリー名のアルファベット順（初期値）
slug
count - カテゴリーの投稿数
term_group

order

（文字列）カテゴリーのソート順。初期値は昇順。有効な値は：

ASC - 昇順（初期値）
DESC - 降順

style

（文字列）カテゴリーリストの表示形式。マークアップの節を参照。有効な値は：

list - 箇条書き（<ul>）（初期値）
none - 表示形式なし（各カテゴリーは <br>（改行）で区切られる）

show_count

（真偽値）各カテゴリーに投稿数を表示するか。初期値は false（非表示）。有効な値は：

1 (true) - 表示
0 (false) - 非表示（初期値）

hide_empty

（真偽値）投稿のないカテゴリーを非表示にするか。有効値：

1 (true) - 空カテゴリーを隠す（初期値）
0 (false) - 全て表示

use_desc_for_title

（真偽値）カテゴリーの説明をリンク（アンカータグ）の title 属性に挿入（<a title="カテゴリーの説明" href="...> のように）するか。初期値は true（カテゴリーの説明を挿入）。有効な値は：

1 (true) - カテゴリーの説明を挿入（初期値）
0 (false) - 挿入しない

child_of: （整数）このパラメータで指定したカテゴリー ID の子カテゴリーのみ表示。初期値なし。このパラメータを使うと、hide_empty パラメータに false がセットされる。

feed: （文字列）各カテゴリーの rss-2 フィードへのリンクを表示、そのリンク文字列を設定する。初期値は フィードへのリンク・リンク文字列なし。

feed_type: （文字列）

feed_image: （文字列）各カテゴリーの rss-2 フィードへのリンクを画像（通常は RSS フィードアイコン）で表示したいときに、その画像の URI を設定。このパラメータは feed パラメータより優先（リンク文字列の代わりに画像）。初期値なし。

exclude: （文字列）指定したカテゴリー（複数可）をリストから除外。除外するカテゴリーの ID をコンマ区切りで指定。用例を参照。child_of パラメータは自動的に無効となる。

exclude_tree: （文字列）結果から除外するカテゴリーツリー。除外するカテゴリー（ツリーの最上位）の ID をコンマ区切りで指定。include パラメータは空にすること。hierarchical パラメータが true の場合、exclude_tree の代わりに exclude が使われる。バージョン 2.7.1 以降のみ。

include: （文字列）指定したカテゴリー ID のみリストに表示。コンマ区切りで指定。用例を参照。

hierarchical

（真偽値）サブカテゴリーを箇条書き項目の内側（親カテゴリーより下位レベル）に表示するか、親と同レベルで表示するか。（つまり、箇条書きを入れ子・ツリー表示にするか否か。）初期値は true（サブカテゴリーを親より下位レベルに表示）。有効な値は：

1 (true) - 入れ子表示（初期値）
0 (false) - 親子同レベル

title_li: （文字列）箇条書きの外側に表示するタイトルと表示形式。デフォルトは "Categories" （日本語化ファイルで定義されていればその文字列）。このパラメータを中味を空で指定すると、箇条書きの外側には何も表示しません。用例を参照。

show_option_none: (文字列) 表示するカテゴリーが一つも無いときに代わりに表示する文字列。デフォルトは "No categories" （日本語化ファイルで定義されていればその文字列）。

number: （整数）表示するカテゴリーの個数を設定。SQL の LIMIT 値となります。初期値は無制限。

echo

（真偽値）結果を表示するか、変数等へ値を返すか。初期値は true（整形されたカテゴリーリストを表示）。バージョン 2.3 以降のみ。有効な値は：

1 (true) - 表示（初期値）
0 (false) - 値を返す

depth

（整数）カテゴリー階層のどのレベルまでをカテゴリーリストに出力するかを指定。初期値は

0<code>（全ての親子カテゴリーを出力）。バージョン 2.5 以降のみ。

<code>0 - 全ての親子カテゴリーを出力（初期値）
-1 - 全てのカテゴリーをフラット（インデントなし）形式で出力（hierarchical パラメータより優先）
1 - 最上位カテゴリーのみ出力
n - n（数値）階層目までを出力。'2' と指定すれば、最上位とすぐ下の子カテゴリーまでを出力。

参考 - #L289 より：hierarchical は（デフォルトで無効化されている）、true （有効）でなければ depth パラメータより優先する。hierarchical が false （無効）なら、全てのカテゴリーを表示する。有効な場合は depth パラメータの値を使用する。

current_category: (整数) カテゴリーアーカイブページ以外で "current-cat" を表示させる。普通はカテゴリーアーカイブページのみで current-cat がセットされるが、それとは別の使い方をしたり、他のカテゴリーをハイライトしたい場合、このパラメータ（カテゴリー ID を指定）で関数による「現在」のカテゴリーの判断を上書きできる。バージョン 2.6 以降のみ。

pad_counts

(真偽値) 子カテゴリーからの値を含めてリンク数または投稿数を計算する。show_counts と hierarchical が両方とも true の場合、自動的に true に設定される。バージョン 2.9 以降のみ。有効な値は:

1 (true)
0 (false) - 初期値

taxonomy

(文字列) カテゴリーを取得するタクソノミーの名前。バージョン 3.0 以降のみ。有効な値は:

category - デフォルト（参考：投稿のカテゴリーは category タクソノミーのターム。）
タクソノミー名 - または登録済みタクソノミー（カスタム分類）の名前

walker

(オブジェクト) リストをレンダリングする Walker クラス。有効な値は:

オブジェクト - Walker_Category または Walker を拡張するクラスのインスタンス

用例

カテゴリーの指定・除外

カテゴリーをアルファベット順にソートし、カテゴリー ID の 16, 3, 9, 5 のみを表示したいときは、次のようにコードを書きます。

<ul>
<?php wp_list_categories('orderby=name&include=3,5,9,16'); ?>
</ul>

次の例は、カテゴリー名順にソート、各カテゴリーの投稿数を表示、リストから ID が 10 のカテゴリーを除外：

<ul>
<?php wp_list_categories('orderby=name&show_count=1&exclude=10'); ?>
</ul>

リストの見出しの表示／非表示

title_li パラメータは、生成されるカテゴリーリストの見出しを設定したり隠したりします。初期値は '__('Categories')'で、見出しとして "Categories" という語句（日本語版では「カテゴリー」）を表示します。

訳注： __('Categories') や __('Poetry') は、ローカライズ対応の書き方です。括弧内の文字列とその訳語が日本語化ファイルで定義されていれば、訳語に置換されて表示されます。

見出しの非表示

このパラメータに null や空の値をセットすると、見出しを表示しません。次のコードは、ID が 4, 7 以外のカテゴリーを表示し、見出しを非表示とする例です。

<ul>
<?php wp_list_categories('exclude=4,7&title_li='); ?>
</ul>

見出し文字列の変更

次の例は、ID が 9, 5, 23 のカテゴリーのみを表示、見出しを <h2> タグ付きの "Poetry" という文字列に変更：

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

子カテゴリーのみの表示

次のコードは、ID でソート、ID が 8 であるカテゴリーの子孫カテゴリーのみのカテゴリーリンクを生成する例です。各カテゴリーの投稿数を表示し、リンクの title 属性のカテゴリー概要は非表示です。 参考： ある親カテゴリーに投稿がないときは、親カテゴリーは表示されません。ただし child_of で指定したカテゴリー自身は投稿があっても表示されません。

<ul>
<?php wp_list_categories('orderby=id&show_count=1&use_desc_for_title=0&child_of=8'); ?>
</ul>

カテゴリー数表示からカッコ記号を削除

show_count=1　を指定すると、カッコで囲んでカテゴリー数を表示します。コアの WordPress ファイルを変更せずにカッコ記号を削除するには、次のコードを使います。

<?php
$variable = wp_list_categories('echo=0&show_count=1&title_li=<h2>Categories</h2>');
$variable = str_replace(array('(',')'), '', $variable);
echo $variable;
?>

フィードリンク付きカテゴリー表示

次の例は、カテゴリー名でソート、各カテゴリーの投稿数を表示、各カテゴリーの RSS フィードへのリンクを表示します。

<ul>
<?php wp_list_categories('orderby=name&show_count=1&feed=RSS'); ?>
</ul>

RSS リンク部分をフィードアイコンで表示するには：

<ul>
<?php wp_list_categories('orderby=name&show_count=1&feed_image=/images/rss.gif'); ?>
</ul>

カスタム分類内の項目を表示

バージョン 3.0 で taxonomy パラメータが追加され、カスタム分類（カスタムタクソノミー）をリストできるようになりました。次の例は genre というタクソノミーに含まれるターム（分類の項目）をリストします：

<?php 
// 指定されたタクソノミーに含まれるタームを wp_list_categories を使ってリストする。
// （PHP コードを有効にするプラグインを併用すると、ウィジェットの中でも使える。）

$taxonomy     = 'genre';
$orderby      = 'name'; 
$show_count   = 0;      // 表示するなら 1、しないなら 0
$pad_counts   = 0;      // 子孫のカウントも合計するなら 1、しないなら 0
$hierarchical = 1;      // 階層表示するなら 1、しないなら 0
$title        = '';

$args = array(
  'taxonomy'     => $taxonomy,
  'orderby'      => $orderby,
  'show_count'   => $show_count,
  'pad_counts'   => $pad_counts,
  'hierarchical' => $hierarchical,
  'title_li'     => $title
);
?>

<ul>
<?php wp_list_categories( $args ); ?>
</ul>

投稿に付けられたカテゴリーを表示

ある投稿に付けられたカテゴリー（または他のタクソノミーのターム）を、カテゴリーの親子関係によってソートして表示します。カテゴリー名でソートする get_the_category_list() 関数と似ています。この例はループの中で使用しなければなりません。

<?php
$taxonomy = 'category';

// 投稿に付けられたターム（カテゴリー）の ID を取得する。
$post_terms = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) );
// リンクの区切り文字
$separator = ', ';

if ( !empty( $post_terms ) && !is_wp_error( $post_terms ) ) {

	$term_ids = implode( ',' , $post_terms );
	$terms = wp_list_categories( 'title_li=&style=none&echo=0&taxonomy=' . $taxonomy . '&include=' . $term_ids );
	$terms = rtrim( trim( str_replace( '<br />',  $separator, $terms ) ), $separator );

	// 投稿のカテゴリーを表示
	echo  $terms;
}
?>

カテゴリーリストのマークアップと装飾

デフォルトでは、wp_list_categories() は入れ子になった番号なし箇条書きリスト（ul）を生成します。さらに、そのリストを囲む形で、"Categories" という見出しを付けた単一のリスト項目（li）も一緒に生成します。

例えば <?php wp_list_categories(); ?> とだけ書くと、生成される XHTML コードは次のようになります。

<li class="categories">カテゴリー
<ul>
<li class="cat-item cat-item-ID"><a href="http://～/" title="カテゴリー概要">カテゴリー名</a></li>
<li class="cat-item cat-item-ID"><a href="http://～/" title="カテゴリー概要">カテゴリー名</a>
    <ul class="children">
    <li class="cat-item cat-item-ID"><a href="http://～/" title="カテゴリー概要">子カテゴリー名</a></li>
    <li class="cat-item cat-item-ID"><a href="http://～/" title="カテゴリー概要">子カテゴリー名</a></li>
    </ul></li>
<li class="cat-item cat-item-ID"><a href="http://～/" title="カテゴリー概要">カテゴリー名</a></li>
</ul>
</li>

（注： cat-item-ID はカテゴリー ID の番号です。）

カテゴリーリストの外側がさらに li で括られるのは、デフォルトテーマやウィジェットでは、サイドバー全体が ul の入れ子構造となっている/en ためです。カテゴリーリストや月別アーカイブのようなサイドバーの各メニューは、その中の li 要素です。

一番外側のリスト項目を外すには、title_li パラメータに空を指定します。すると、上記コード例の先頭と末尾の各 2 行（<li><ul>, </ul></li>）が除かれ、中の li 要素のみが出力されます。そのため、リストの見出しの表示／非表示の用例のように、自分で箇条書き要素（ul または ol）で括る必要があります。箇条書きにしたくないときは、style パラメータに none を設定します。

カテゴリーアーカイブページでこのカテゴリーリストが生成されたときは、そのページのカテゴリー項目にのみ current-cat という HTML クラスが付きます。（注： cat-item-ID は、カテゴリー ID の番号です。）

...
<li class="cat-item cat-item-ID">（その他のカテゴリー）</li>
<li class="cat-item cat-item-ID current-cat">（現在表示しているカテゴリーアーカイブのカテゴリー）</li>
<li class="cat-item cat-item-ID">（その他のカテゴリー）</li>
...

CSS を使って、現在のカテゴリーをハイライト表示させるなどの装飾ができます。

 li.categories { ... }  /* 一番外側のリスト項目 */
 li.cat-item { ... }
 li.cat-item-7 { ... }  /* ID が 7 のカテゴリー（ID を指定） */
 li.current-cat { ... }
 li.current-cat-parent { ... }
 ul.children { ... }

変更履歴

ソースファイル

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

カテゴリータグ： the_category(), the_category_rss(), single_cat_title(), category_description(), wp_dropdown_categories(), wp_list_categories(), get_the_category(), get_the_category_by_ID(), get_category_by_slug(), get_the_category_list(), get_category_parents(), get_category_link(), is_category(), in_category() , get_categories()

リスト・ドロップダウン関数： 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()

テンプレートタグへのクエリ文字列型パラメータの渡し方、関数リファレンス、テンプレートタグ目次もご覧ください。

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

目次

説明

使い方

デフォルトの使い方

パラメータ

用例

カテゴリーの指定・除外

リストの見出しの表示／非表示

見出しの非表示

見出し文字列の変更

子カテゴリーのみの表示

カテゴリー数表示からカッコ記号を削除

フィードリンク付きカテゴリー表示

カスタム分類内の項目を表示

投稿に付けられたカテゴリーを表示

カテゴリーリストのマークアップと装飾

変更履歴

ソースファイル

案内メニュー

個人用ツール

名前空間

変種

表示

その他

検索

このサイトについて

特集

リファレンス

サーバー別情報

ドキュメント整備

協力・貢献

WordPress関連リンク

ツール

他言語版

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

目次

説明

使い方

デフォルトの使い方

パラメータ

用例

カテゴリーの指定・除外

リストの見出しの表示／非表示

見出しの非表示

見出し文字列の変更

子カテゴリーのみの表示

カテゴリー数表示からカッコ記号を削除

フィードリンク付きカテゴリー表示

カスタム分類内の項目を表示

投稿に付けられたカテゴリーを表示

カテゴリーリストのマークアップと装飾

変更履歴

ソースファイル

関連項目

案内メニュー

検索