The wp_tag_cloud() function displays a list of tags in what is called a 'tag cloud', where the size of each tag is determined by how many times that particular tag has been assigned to posts.

Beginning with Version 2.8, the taxonomy parameter was added so that any taxonomy could be used as the basis of generating the cloud. That means that a cloud for Categories or any other Custom Taxonomies can be presented to visitors.

wp_tag_cloud() 描述


<?php wp_tag_cloud$args ); ?>

Default Usage

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
<?php $args = array(	'smallest'                  => 8, 	'largest'                   => 22,	'unit'                      => 'pt', 	'number'                    => 45,  	'format'                    => 'flat',	'separator'                 => "",	'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!); ?>

The child_of Key is not a direct part of the Array in wp_tag_cloud, but because this function uses wp_parse_args() and get_terms(), you can use all Array Keys used by get_terms()!

By default, the usage shows:

  • smallest - The smallest tag (lowest count) is shown at size 8
  • largest - The largest tag (highest count) is shown at size 22
  • unit - Describes 'pt' (point) as the font-size unit for the smallest and largest values
  • number - Displays at most 45 tags
  • format - Displays the tags in flat (separated by whitespace) style
  • separator - Displays whitespace between tags
  • orderby - Order the tags by name
  • order - Sort the tags in ASCENDING fashion
  • exclude - Exclude no tags
  • include - Include all tags
  • topic_count_text_callback - Uses function default_topic_count_text
  • link - view
  • taxonomy - Use post tags for basis of cloud
  • echo - echo the results

wp_tag_cloud() 用法



(integer) (可选) The text size of the tag with the smallest count value (units given by unit parameter).

默认值: 8


(integer) (可选) The text size of the tag with the highest count value (units given by the unit parameter).

默认值: 22


(string) (可选) Unit of measure as pertains to the smallest and largest values. This can be any CSS length value, e.g. pt, px, em, %.

默认值: 'pt'


(integer) (可选) The number of actual tags to display in the cloud. (Use '0' to display all tags.)

默认值: 45


(string) (可选) Format of the cloud display.

  • 'flat' separated by whitespace defined by 'separator' parameter.
  • 'list' UL with a class of 'wp-tag-cloud'
  • 'array' returns the tag cloud as an array for use in PHP

默认值: flat


(string) (可选) The text/space between tags.

默认值: '
' (whitespace)


(string) (可选) Order of the tags.

  • 'name'
  • 'count'

默认值: name


(string) (可选) Sort order.

  • 'ASC'
  • 'DESC'
  • 'RAND' tags are in a random order.

默认值: ASC


(string) (可选) Comma separated list of tags (term_id) to exclude. For example, exclude=5,27 means tags that have the term_id 5 or 27 will NOT be displayed. Defaults to exclude nothing.

默认值: null


(string) (可选) Comma separated list of tags (term_id) to include. For example, include=5,27 means tags that have the term_id 5 or 27 will be the only tags displayed. Defaults to include everything.

默认值: null


(string) (可选) The function, which, given the count of the posts with that tag, returns a text for the tooltip of the tag link.

默认值: default_topic_count_text


(string) (可选) Set link to allow edit of a particular tag.

  • 'view'
  • 'edit'

默认值: view


(string or array) (可选) Taxonomy or array of taxonomies to use in generating the cloud.

  • 'post_tag'
  • 'category'
  • 'link_category'
  • 'any other registered taxonomy'
  • or array of taxonomies Note: this parameter was introduced with Version 3.1

默认值: post_tag


(boolean) (可选) Display the result or return it in a variable. The default is true (display the tag cloud).

  • 1 (true)
  • 0 (false)

默认值: true

wp_tag_cloud() 参数


Cloud displayed under Popular Tags title

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */

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

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

<?php endif; ?>

Cloud limited in size and ordered by count rather than name

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
<?php wp_tag_cloud( 'smallest=15&largest=40&number=50&orderby=count' ); ?>

Cloud returned as array but not displayed

The variable $tag will contain the tag cloud for use in other PHP code

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
 <?php $tag = wp_tag_cloud( 'format=array' ); ?>

Display a Category Cloud

Use the taxonomy argument to cause a cloud of categories to display.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
<?php wp_tag_cloud( array( 'taxonomy' => 'category' ) ); ?>

Display a Cloud of Categories and Tags

Use the array feature of the taxonomy argument to cause a cloud of categories and tags to display.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */

	$args = array(
		'taxonomy' => array( 'post_tag', 'category' ), 

	wp_tag_cloud( $args );

Change Title Text of Cloud Links

Use the topic_count_text_callback argument to pass in a new callback function. The original function default_topic_count_text() is located in /wp-includes/category-template.php This example changes the title text from the default "topics" to "pictures".

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */

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

wp_tag_cloud() 示例


wp_tag_cloud() 函数的代码位于 wp-includes/category-template.php.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
 * Display tag cloud.
 * The text size is set by the 'smallest' and 'largest' arguments, which will
 * use the 'unit' argument value for the CSS text size unit. The 'format'
 * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
 * 'format' argument will separate tags with spaces. The list value for the
 * 'format' argument will format the tags in a UL HTML list. The array value for
 * the 'format' argument will return in PHP array type format.
 * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
 * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC'.
 * The 'number' argument is how many tags to return. By default, the limit will
 * be to return the top 45 tags in the tag cloud list.
 * The 'topic_count_text' argument is a nooped plural from _n_noop() to generate the
 * text for the tooltip of the tag link.
 * The 'topic_count_text_callback' argument is a function, which given the count
 * of the posts with that tag returns a text for the tooltip of the tag link.
 * The 'post_type' argument is used only when 'link' is set to 'edit'. It determines the post_type
 * passed to edit.php for the popular tags edit links.
 * The 'exclude' and 'include' arguments are used for the {@link get_tags()}
 * function. Only one should be used, because only one will be used and the
 * other ignored, if they are both set.
 * @since 2.3.0
 * @param array|string|null $args Optional. Override default arguments.
 * @return void|array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
 *                    Otherwise, this function outputs the tag cloud.
function wp_tag_cloud( $args = '' ) {
	$defaults = array(
		'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 45,
		'format' => 'flat', 'separator' => "
", 'orderby' => 'name', 'order' => 'ASC',
		'exclude' => '', 'include' => '', 'link' => 'view', 'taxonomy' => 'post_tag', 'post_type' => '', 'echo' => true
	$args = wp_parse_args( $args, $defaults );

	$tags = get_terms( $args['taxonomy'], array_merge( $args, array( 'orderby' => 'count', 'order' => 'DESC' ) ) ); // Always query top tags

	if ( empty( $tags ) || is_wp_error( $tags ) )

	foreach ( $tags as $key => $tag ) {
		if ( 'edit' == $args['link'] )
			$link = get_edit_term_link( $tag->term_id, $tag->taxonomy, $args['post_type'] );
			$link = get_term_link( intval($tag->term_id), $tag->taxonomy );
		if ( is_wp_error( $link ) )

		$tags[ $key ]->link = $link;
		$tags[ $key ]->id = $tag->term_id;

	$return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args

	 * Filter the tag cloud output.
	 * @since 2.3.0
	 * @param string $return HTML output of the tag cloud.
	 * @param array  $args   An array of tag cloud arguments.
	$return = apply_filters( 'wp_tag_cloud', $return, $args );

	if ( 'array' == $args['format'] || empty($args['echo']) )
		return $return;

	echo $return;

wp_tag_cloud() 源文件