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

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

提供: WordPress Codex 日本語版
< テンプレートタグ
2014年8月3日 (日) 02:01時点におけるGblsm (トーク | 投稿記録)による版

移動先: 案内検索

このページ「テンプレートタグ/wp list categories」は情報が古くなっている可能性があります。最新版英語)も合わせてご覧ください。翻訳にご協力くださる方はぜひご相談ください

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


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

使い方

<?php wp_list_categories( $args ); ?> 

デフォルトでの使い方

<?php $args = array(
	'show_option_all'    => '',
	'orderby'            => 'name',
	'order'              => 'ASC',
	'show_last_update'   => 0,
	'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'       => true,
	'title_li'           => __( 'Categories' ),
	'number'             => NULL,
	'echo'               => 1,
	'depth'              => 0,
	'current_category'   => 0,
	'pad_counts'         => 0,
	'taxonomy'           => 'category',
	'walker'             => 'Walker_Category' ); ?>

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

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

パラメータ

show_option_all
文字列) ブランク以外の文字列を設定すると、全カテゴリーの記事を表示するページ(ブログのトップページ)へのリンクを、カテゴリーリストの先頭に表示します。リンクテキストはこのパラメータで指定した文字列です。デフォルトでは表示しません。
orderby
文字列) カテゴリーのソート項目。初期値はカテゴリー名でソート。有効値:
  • ID - カテゴリーID
  • name - カテゴリー名のアルファベット順(初期値)
  • slug
  • count - カテゴリーの投稿数
  • term_group
order
文字列) カテゴリーのソート順。初期値は 昇順。有効値:
  • ASC - 昇順(初期値)
  • DESC - 降順
show_last_updated
(真偽値) (各カテゴリーに属する)投稿の最終更新日を表示するか。初期値は非表示(FALSE)。
  • 1 (true) - 表示
  • 0 (false) - 非表示(初期値)
style
文字列) カテゴリーリストの表示形式。マークアップの節 を参照。有効値:
  • list - 箇条書き(<li>)(初期値)
  • none - 表示形式なし(各カテゴリーは <br>(改行)で区切られる)
show_count
真偽値) 各カテゴリーに投稿数を表示するか。初期値は false(非表示)。有効値:
  • 1 (true) - 表示
  • 0 (false) - 非表示(初期値)
hide_empty
真偽値) 投稿のないカテゴリーを非表示にするか。有効値:
  • 1 (true) - 空カテゴリーを隠す(初期値)
  • 0 (false) - 全て表示
use_desc_for_title
真偽値カテゴリーの概要をリンク(アンカータグ)の title 属性に挿入(<a title="<em>カテゴリー概要</em>" 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
文字列) 結果から除外するカテゴリーツリー。バージョン 2.7.1 以降のみ。
include
文字列) 指定したカテゴリーID のみリストに表示。カンマ区切りで昇順に指定。用例を参照。
hierarchical
真偽値) サブカテゴリーを箇条書き項目の内側(親カテゴリーより下位レベル)に表示するか、親と同レベルで表示するか。(つまり、箇条書きを入れ子・ツリー表示にするか否か。)初期値は true(サブカテゴリーを親より下位レベルに表示)。有効値:
  • 1 (true) - 入れ子表示(初期値)
  • 0 (false) - 親子同レベル
title_li
文字列) 箇条書きの外側に表示するタイトルと表示形式。デフォルトは "_Categories"。このパラメータを中味を空で指定すると、箇条書きの外側には何も表示しません。用例を参照。
number
整数) 表示するカテゴリー数を設定。SQL の LIMIT 値となります。初期値は無制限。
echo
真偽値) 結果を表示するか、変数等へ値を返すか。初期値は true(整形されたカテゴリーリストを表示)。バージョン 2.3 以降のみ。有効値:
  • 1 (true) - 表示(初期値)
  • 0 (false) - 値を返す
depth
整数) カテゴリー階層のどのレベルまでをカテゴリーリストに出力するかを指定。初期値は 0(全親子カテゴリーを出力)。バージョン 2.5 以降のみ。
  • 0 - 全ての親子カテゴリーを出力 (初期値)
  • -1 - 全てのカテゴリーをフラット(インデントなし)形式で出力(hierarchical パラメータより優先)
  • 1 - 最上位カテゴリーのみ出力
  • n - n(数値)階層目までを出力。'2' と指定すれば、最上位とすぐ下の子カテゴリーまでを出力。
current_category 
(整数) カテゴリーアーカイブページ以外で "current-cat" を表示させる。通常とは別の使い方をしたり、他のカテゴリーをハイライトしたい場合、このパラメータで関数による「現在」のカテゴリーの判断を上書きできる。2.6 以降のみ。
pad_counts 
(真偽値) 子カテゴリーの項目を含めてリンクまたは投稿数を計算する。show_counts または hierarchical が true の場合、自動的に true に設定される。2.9 以降のみ。有効値:
  • 1 (true)
  • 0 (false) - 初期値
taxonomy 
(文字列) 返す分類名。3.0 以降のみ。有効値:
  • category - デフォルト
  • taxonomy - または登録されたタクソノミーのいずれか
walker 
(オブジェクト) リストをレンダリングする Walker クラス。有効値:
  • object - Walker_Category または Walker を拡張する Class インスタンス

カテゴリーの指定・除外

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

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

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

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

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

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

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

見出しの非表示

このパラメータに null や空の値をセットすると、見出しを表示しません。次のコードは、カテゴリーID 4、7 以外を表示し、見出しを非表示とする例です。上述したように、'title_li=' 指定時は外側の ul も出力されないため、自分で ul または ol を補います。

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

見出し文字列の変更

次の例は、カテゴリーID 9、5、23 のみを表示、見出しを <h2> タグ付きの "Poetry" 語句に変更:

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

子カテゴリーのみの表示

次のコードは、ID でソート、カテゴリーID 8 の子カテゴリーのみのカテゴリーリンクを生成する例です。各カテゴリーの投稿数は表示、リンクの title 属性のカテゴリー概要は非表示です。注: 親カテゴリーに投稿がないときは、親カテゴリーは表示されません。

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

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

When show_count=1, each category count is surrounded by parentheses. In order to remove the parentheses without modifying core WordPress files, use the following code.

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

カテゴリー名でソート、各カテゴリーの投稿数を表示、各カテゴリーの RSS フィードへのリンクを表示する例:

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

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

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

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

With Version 3.0 the taxonomy parameter was added to enable wp list categories to list custom taxonomies. This example list the terms in the taxonomy genre:

<?php 
//list terms in a given taxonomy using wp_list_categories  (also useful as a widget if using a PHP Code plugin)
$orderby = 'name'; 
$show_count = 0; // 1 for yes, 0 for no
$pad_counts = 0; // 1 for yes, 0 for no
$hierarchical = 1; // 1 for yes, 0 for no
$taxonomy = 'genre';
$title = '';

$args = array(
  'orderby' => $orderby,
  'show_count' => $show_count,
  'pad_counts' => $pad_counts,
  'hierarchical' => $hierarchical,
  'taxonomy' => $taxonomy,
  'title_li' => $title
);
?>
<ul>
<?php 
wp_list_categories($args);
?>
</ul>

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

デフォルトでは、wp_list_categories() は、"Categories" という見出し付きで、入れ子になった番号なし箇条書きリスト(ul)を生成します。

例えば <?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 を使って、現在のカテゴリーをハイライト表示させるなどの装飾ができます。

 .current-cat { ... }

変更履歴

  • 3.0 : パラメータに taxonomy が追加されました。
  • 2.9 : パラメータに pad_counts が追加されました。
  • 2.7.1 : パラメータに exclude_tree が追加されました。
  • 2.6 : パラメータに current_category が追加されました。
  • 2.5 : パラメータに depth が追加されました。
  • 2.3 : パラメータに echo が追加されました。
  • 2.1 : 新規テンプレートタグ

ソースファイル

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()


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


最新英語版: WordPress Codex » Template Tags/wp_list_categories最新版との差分