WordPress函數：wp_tag_cloud（標簽云）

來源于：

https://www.wpdaxue.com/wp_tag_cloud.html

函數官方文檔：

說明

wp_tag_cloud() 函數的作用是用來標簽云的，可以根據每個標簽所關聯的文章次數來定義字體大小、標簽排序等屬性。從 2.8 版本開始，添加了 分類法（taxonomy）參數，這就意味著，除了 標簽（tags）以外，還可以將 分類（Categories） 或其他 自定義分類法（Custom Taxonomies）作為“云”顯示。

用法

<?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(see Note!)
); ?>

注： child_of 不是一個直接的 wp_tag_cloud 數組的鍵（Key），但由于這個函數使用 wp_parse_args() 和 get_terms() ，你可以通過 get_terms() 使用所有的數組鍵。

默認情況下的輸出內容：

• smallest?—— 最小的標簽（使用次數最少）顯示大小為8
• largest?——最大的標簽（使用次數最多）顯示大小為22
• unit?—— 最大值最小值的單位為’pt’
• number?—— 至多顯示45個標簽
• format?—— 以平面形式顯示所有標簽（標簽之間用空格隔開）
• 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的值的測量單位。可以是任何CSS長度單位，如pt, px, em, %。

默認值：’pt’

number

（整數）（可選）顯示在云中的實際標簽數。（值為’0’時顯示所有標簽）

默認值：45

format

（字符串）（可選）所顯示的云的格式。

• ‘flat’ （默認值）標簽被“separator”參數所定義的空格分隔
• ‘list’ 標簽與class=’wp-tag-cloud’ 共同在UL中
• ‘array’ 標簽在數組中，函數以數組方式返回標簽云，以用在PHP中。注意：數組被返回，而非顯示。

separator

（字符串）（可選）標簽之間的文本/空格。

默認值：’\n’ （空格）

orderby

（字符串）（可選）標簽的排列依據。有效值包括：

• ‘name’ （默認值）
• ‘count’

order

（字符串）（可選）排列順序（升序或降序）。有效值包括（必須大寫）：

• ‘ASC’ ——升序（默認值）
• ‘DESC’ ——降序
• ‘RAND’ —— 隨機

exclude

（字符串）（可選）將要被排除的標簽（term_id）的ID，各ID用逗號隔開。如 ‘exclude=5,27’表示不顯示term_id為5或27的標簽。默認值為不排除任何標簽。

include

（字符串）（可選）要包含的標簽（term_id）列表，各ID用逗號隔開。例如， ‘include=5,27’ 表示只顯示term_id為5或27的標簽。默認為包含所有鏈接。

topic_count_text_callback

（字符串）（可選）給出標簽所關聯的文章數，返回標簽鏈接的用于 tooltip 的文本。

默認值： default_topic_count_text

link

（字符串）（可選）設置鏈接，允許編輯某個指定標簽。有效值包括：

• ‘view’ （默認值）
• ‘edit’

taxonomy

（字符串）（可選）用以生成云的分類法。

• ‘post_tag’ —— （默認值）將文章標簽當作云的來源
• ‘category’ —— 用文章分類生成云
• ‘link_category’ —— 用鏈接分類目錄生成云
• 任何其他已注冊的分類法
• 或者一組 分類法 （注：此參數引入于 3.1 版本）

echo

（布爾型）（可選）顯示結果，或將結果保留在變量中。默認值為true（顯示標簽云）。有效值包括：

• 1 (true) —— 默認值
• 0 (false)

例子

顯示標題為Popular Tags的云

<?php if ( function_exists('wp_tag_cloud') ) : ?>
?
<h2>Popular Tags</h2>
<ul>
<li><?php wp_tag_cloud('smallest=8&largest=22'); ?></li>
</ul>
?
<?php endif; ?>

限制標簽大小且以使用次數而非名稱排列標簽的云

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

以數組形式返回云，但不顯示

在變量$tag中包含標簽云，以用在其它PHP代碼中

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

顯示分類云

使用分類法（taxonomy）參數定義顯示分類云

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

顯示 分類 和 標簽 云

使用分類法數組將分類和標簽顯示為云

<?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 。這個例子使用“pictures”替換默認的“topics”：

<?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 版本開始，標簽云可以制作成一個標簽存檔頁面。這就意味著，用戶可以點擊某個標簽，然后查看到該使用該標簽的所有文章。根據 模板層級（Template_Hierarchy），如果tag.php模板不存在，那么就使用archives.php模板。通過tag,php模板你可以自定義標簽存檔索引的樣式，為方便導航，模板會在最上方包含標簽云。

要將標簽云顯示在模板上方，你需要將一個新模板添加到主題文件中。模板、模板層級 中有相關介紹。基礎步驟包括：

1. 用下面的內容創建一個文件，命名為tag.php

2. 將新文件上傳到主題目錄下

3. 如果你希望在頁面導航中加入一個指向標簽索引的鏈接，可進行第三步驟，否則點擊某個標簽時會使用新模板。

• 用新模板新建一個空白頁面，將頁面命名為標簽存檔索引。

對第三步的進一步闡述：

WordPress可為不同頁面使用不同頁面模板。在?頁面>添加新頁面?界面的最下方（或是側邊欄，取決于你安裝的WordPress版本）有一個名為“頁面模板”的下拉式菜單。你可以在這里選擇顯示某個頁面所用的模板。

<?php /*
Template Name: Tag Archive
*/ ?>
<div>
<?php get_header(); ?>
<h2>Tag Archive</h2>
<?php wp_tag_cloud(''); ?>
	<div class="navigation">
<div class="alignleft"><?php next_posts_link('? Older Entries') ?></div>
<div class="alignright"><?php previous_posts_link('Newer Entries ?') ?></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(); ?>"><?php the_title(); ?></a></h2>
	<div class="entry">
	<?php the_content('Read the rest of this entry ?'); ?>
	</div>
?
	<?php endwhile; ?>
	<?php endif; ?>
</div>
<?php get_footer(); ?>

注意：模板還沒有添加樣式。通過查看single.php主題文件可以了解你的主題所用的結構。

函數歷史

• 3.1 添加傳遞分類法數組的功能參數
• 2.9 添加 separator 參數
• 2.8 添加 taxonomy 和 echo 參數
• 2.7 添加 link 參數
• 2.5 在order參數下新增’RAND’順序 ；format=array 返回數組
• 該標簽始見于WordPress 2.3

源文件

wp_tag_cloud() 位于 wp-includes/category-template.php