WordPress标签云函数wp_tag_cloud

说明

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() 使用所有的数组键。

默认情况下的输出内容：

1.     smallest —— 最小的标签（使用次数最少）显示大小为8
2.     largest ——最大的标签（使用次数最多）显示大小为22
3.     unit —— 最大值最小值的单位为‘pt’
4.     number —— 至多显示45个标签
5.     format —— 以平面形式显示所有标签（标签之间用空格隔开）
6.     separator —— 显示标签之间的空格
7.     orderby —— 按名称为标签排序
8.     order —— 以升序排列
9.     exclude —— 不排除任何标签
10.     include —— 包括所有标签
11.     topic_count_text_callback —— 使用函数 default_topic_count_text
12.     link —— 可视
13.     taxonomy —— 用文章的标签作为云基础
14.     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主题文件可以了解你的主题所用的结构。

源文件

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