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

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

テンプレートタグ/wp tag cloud

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

wp_tag_cloud() テンプレートタグは、「タグクラウド」と呼ばれるタグの一覧を表示します。 これは、各タグが投稿に付けられた回数によってタグの文字サイズが決まる一覧です。

バージョン 2.8 以降、タクソノミー（カスタム分類）をもとにクラウドを作成できるよう、taxonomy パラメータが追加されています。 これにより（投稿タグだけではなく）投稿カテゴリーや、カスタム分類のクラウドを表示することもできます。

使い方

<?php wp_tag_cloud( $args ); ?>

デフォルトの使い方

<?php wp_tag_cloud( $args ); ?>

初期値： 

<?php $args = array(
	'smallest'                  => 8, 
	'largest'                   => 22,
	'unit'                      => 'pt', 
	'number'                    => 45,  
	'format'                    => 'flat',
	'separator'                 => "\n",
	'orderby'                   => 'name', 
	'order'                     => 'ASC',
	'exclude'                   => null, 
	'include'                   => null, 
	'topic_count_text_callback' => default_topic_count_text,
	'link'                      => 'view', 
	'taxonomy'                  => 'post_tag', 
	'echo'                      => true,
	'child_of'                  => null, // 注を参照
); ?>


注：child_of キーは wp_tag_cloud() の直接の引数（パラメータ配列の一部）ではありません。しかし、このテンプレートタグは内部で wp_parse_args() と get_terms() を使用するので、get_terms() が受け入れる引数（パラメータ配列のキー）はどれでも使うことができます！

デフォルトでは次のように表示します。 各タグの文字サイズは、付けられた投稿の数に応じて smallest〜largest の間で段階的に変化します。

  • smallest - 一番小さいタグを 8(pt) で表示（件数が少ないタグ）
  • largest - 一番大きいタグを 22(pt) で表示（件数が多いタグ）
  • unit - smallest と largest のフォントサイズの単位として 'pt' (point) を使用
  • number - 最大 45 タグを表示
  • format - flat（ホワイトスペース区切り）形式でタグを表示
  • separator - タグの間にホワイトスペースを表示
  • orderby - タグ名順に表示
  • order - 昇順でソート（前項でタグ名を指定しているので「タグ名の昇順」となる）
  • exclude - 除外タグなし
  • include - 全てのタグを含める
  • topic_count_text_callback - タグ数の表示形式を default_topic_count_text 関数で指定
  • link - リンクをクリックしてもタグを編集させない
  • taxonomy - 投稿タグを使ってクラウドを作る
  • echo - 結果を表示する

パラメータ

smallest
（整数） （オプション） 最少使用数のタグの表示に使うフォントサイズ（単位は unit パラメータで指定）。
初期値： 8
largest
（整数） （オプション） 最多使用数のタグの表示に使うフォントサイズ（単位は unit パラメータで指定）。
初期値： 22
unit
（文字列） （オプション） smallest と largest の値の単位。pt, px, em, % 等、CSS でフォントサイズに用いる単位を指定可能。
初期値： 'pt'
number
（整数） （オプション） クラウドに表示するタグ数（'0' を指定すると全てのタグを表示）。
初期値： 45
format
（文字列） （オプション） クラウド表示のフォーマット。
初期値： flat
  • 'flat' - タグをホワイトスペース（separator パラメータで定義）で区切る。
  • 'list' - タグを class='wp-tag-cloud' 付きの ul（番号なし箇条書き）内に表示。
  • 'array' - タグを配列に格納し、タグクラウドデータを PHP で扱えるように配列のまま返す。注：配列の取得（表示ではなく）は WordPress 2.5 以上で使えます。
separator
（文字列） （オプション） タグの間に表示するテキストまたはスペース。
初期値： "\n"（空白）
orderby
（文字列） （オプション） タグの表示順とする項目。
初期値： name
  • 'name' - タグ名
  • 'count' - 使用数
order
（文字列） （オプション） ソート順。
初期値： ASC
  • 'ASC' - 昇順（初期値）
  • 'DESC' - 降順
  • 'RAND' - ランダム（WordPress 2.5 以上で指定可能）
exclude
（文字列） （オプション） 除外するタグの term_id をコンマ区切りで指定。例えば、'exclude=5,27' とすれば term_id が 5 と 27 のタグは表示されない。デフォルトでは除外なし。
初期値： null
include
（string） （オプション） 表示対象とするタグの term_id をコンマ区切りで指定。例えば、'include=5,27' とすれば term_id が 5 または 27 のタグのみを表示。デフォルトでは全てのタグが対象。
初期値： null
topic_count_text_callback
（文字列） （オプション） タグリンクの title 属性に設定される「タグの件数」の文字列を返す関数（投稿の数とタグを与えられて「ツールチップ」文字列を返す）の関数名。
初期値： default_topic_count_text
link
（文字列） （オプション） 特定のタグを編集できるようリンクを設定。
初期値： view
  • 'view' - 閲覧（初期値）
  • 'edit' - 編集
taxonomy
（文字列|配列） （オプション） クラウドの生成に使うタクソノミー、またはタクソノミーの配列。注：このパラメータは WordPress 2.8 にて導入された。
初期値： post_tag
  • 'post_tag' - 投稿タグ
  • 'category' - 投稿カテゴリー
  • 'link_category' - リンクのカテゴリー
  • 登録済みのカスタム分類（タクソノミー）
  • または、タクソノミーの配列 - 注：これはバージョン 3.1 以降で使えます。
echo
（真偽値） （オプション） 結果を表示するか、変数に入れるか。デフォルトは true （タグクラウドを表示）。
初期値： true
  • 1 (true) - 表示
  • 0 (false) - 値を返す（表示しない）

用例

タイトル「人気のタグ」の下にタグクラウドを表示

<?php if ( function_exists( 'wp_tag_cloud' ) ) : ?>

<h2>人気のタグ</h2>
<li><?php wp_tag_cloud( 'smallest=8&largest=22' ); ?></li>

<?php endif; ?>

注：全体が <li>〜</li> で括られているのは、デフォルトテーマなどのサイドバー用の形式です。サイドバー全体が順不同リスト（<ul>）の入れ子になっています（サイドバーのカスタマイズ/en 参照）。

サイズ指定、タグ名ではなく使用数順のタグクラウド

<?php wp_tag_cloud( 'smallest=15&largest=40&number=50&orderby=count' ); ?>

タグクラウドを表示せずに配列として取得

タグクラウドのデータを他の PHP コードで使うために、変数 $tag に格納します。 

<?php $tag = wp_tag_cloud( 'format=array' ); ?>

カテゴリークラウドを表示

taxonomy 引数を使ってカテゴリーのクラウドを表示します。 

<?php wp_tag_cloud( array( 'taxonomy' => 'category' ) ); ?>

カテゴリーとタグの両方を含むクラウドを表示

taxonomy 引数に配列を与えることにより、カテゴリーとタグの両方を含むクラウドを表示します。 

<?php 
	$args = array(
		'taxonomy' => array( 'post_tag', 'category' ), 
	); 

	wp_tag_cloud( $args );
?>

クラウドからのリンクのタイトル文字列を変更

topic_count_text_callback 引数を使って、新しいコールバック関数を与えます。 オリジナルの関数 default_topic_count_text() は /wp-includes/category-template.php にあります。 この例はタイトル文字列のデフォルト "topics" を "pictures" に変えます。 （訳注：WordPress 日本語版のデフォルトは「〜件のトピック」。） 

<?php 
	wp_tag_cloud( array( 'topic_count_text_callback' => 'my_tag_text_callback' ) ); 

	function my_tag_text_callback( $count ) {
		return sprintf( _n( '%s picture', '%s pictures', $count ), number_format_i18n( $count ) );
	}
?>


タグアーカイブの作成

素晴らしいタグ機能がバージョン 2.3 で追加された一方で、wp_tag_cloud テンプレートタグはタグアーカイブを表示するのにも使えます。 つまり、読者があるタグをクリックすると、そのタグが付いている全ての投稿を表示することができます。 テンプレート階層に示すとおり、tag.php テンプレートが存在しない場合は archives.php テンプレートが使われます。 この tag.php テンプレートを作ることによって、タグアーカイブの表示をカスタマイズできます。 例えばタグクラウドをページの最上部に表示させて、より便利なナビゲーションを付けることができます。

これを実際に行うには、あなたのテーマに新しくテンプレートを追加する必要があります。 以下はテンプレートやテンプレート階層に関係した良い見本です。

基本的な手順は次のとおりです：

  1. コンテンツを作成し、tag.php という名前のファイルに保存する。
  2. ファイルをあなたが使用しているテーマのディレクトリにアップロードする。
  3. これは任意です。ページナビゲーションにタグアーカイブへのリンクを入れたい場合は行ってください。行わない場合は、タグをクリックしたときにこのテンプレートが使用されます。
    • 新しくページを作成し、このテンプレートを適用し、ページ名を タグアーカイブ とする。

3 番目のステップを詳しく説明します：

WordPress は異なるページテンプレートを各ページごとに使用することができます。 管理パネルの 固定ページ > 新規追加 で表示されるページの中に (使用中の WordPress バージョンによってはサイドバーにあります) 「テンプレート」という名前のドロップダウンがあります。 そこでどのテンプレートを使ってページを表示するかを選択できます。 

<?php /*
Template Name: タグアーカイブ
*/ ?>
<div>
<?php get_header(); ?>
<h2>タグアーカイブ</h2>
<?php wp_tag_cloud( '' ); ?>
<div class="navigation">
	<div class="alignleft"><?php next_posts_link( '« 古い投稿' ); ?></div>
	<div class="alignright"><?php previous_posts_link( '新しい投稿 »' ); ?></div>
</div>
<?php if ( have_posts() ) : ?>
	<?php while ( have_posts() ) : the_post(); ?>
		<h2><a href="<?php the_permalink(); ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>へのパーマリンク"><?php the_title(); ?></a></h2>
		<div class="entry">
			<?php the_content( '続きを読む »' ); ?>
		</div>
	<?php endwhile; ?>
<?php endif; ?>
</div>
<?php get_footer(); ?>


このテンプレートはスタイリングされていないことに注意してください。 使用中のテーマの single.php ファイルを見て構造を決めると良いでしょう。

変更履歴

  • 3.1 : taxonomy パラメータに配列を与えることができるようになりました。
  • 2.9 : separator パラメータが追加されました。
  • 2.8 : taxonomy および echo パラメータが追加されました。
  • 2.7 : link パラメータが追加されました。
  • 2.5 :
    • パラメータ order（ソート順）の値として 'RAND' を指定できるようになりました。
    • パラメータ format（表示形式）で 'array' を指定したとき、表示せずに値を返すようになりました。
  • 2.3 : 新規テンプレートタグ

ソースファイル

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


タグ: get_tag(), get_tag_link(), get_tags(), get_the_tag_list(), get_the_tags(), is_tag(), the_tags(), single_tag_title(), tag_description(), wp_generate_tag_cloud(), wp_tag_cloud()


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


最新英語版： WordPress Codex » Function Reference/wp_tag_cloud （最新版との差分）

「https://wpdocs.osdn.jp/wiki/index.php?title=テンプレートタグ/wp_tag_cloud&oldid=10797」から取得