Question

wp_tag_cloud( array|string|null $args = '' )

Display tag cloud.

---

description

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 tag link count.

The ‘topic_count_text_callback’ argument is a function, which given the count of the posts with that tag returns a text for the tag link count.

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 get_tags() function. Only one should be used, because only one will be used and the other ignored, if they are both set.

---

参数

$args

(array|string|null) (Optional) Override default arguments.

Default value: ''

---

返回值

(void|array) Generated tag cloud, only if no failures and 'array' is set for the 'format' argument. Otherwise, this function outputs the tag cloud.

---

源代码

File: wp-includes/category-template.php

function wp_tag_cloud( $args = '' ) {
	$defaults = array(
		'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 45,
		'format' => 'flat', 'separator' => "\n", 'orderby' => 'name', 'order' => 'ASC',
		'exclude' => '', 'include' => '', 'link' => 'view', 'taxonomy' => 'post_tag', 'post_type' => '', 'echo' => true,
		'show_count' => 0,
	);
	$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 ) )
		return;

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

		$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

	/**
	 * Filters 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;
}

---

更新日志

Version	description
4.8.0	Added the show_count argument.
2.3.0	Introduced.

---

相关函数

Uses

• wp-includes/category-template.php: wp_generate_tag_cloud()
• wp-includes/category-template.php: wp_tag_cloud
• wp-includes/functions.php: wp_parse_args()
• wp-includes/taxonomy.php: get_term_link()
• wp-includes/taxonomy.php: get_terms()
• wp-includes/link-template.php: get_edit_term_link()
• wp-includes/plugin.php: apply_filters()
• wp-includes/load.php: is_wp_error()
Show 3 more uses Hide more uses

---

Used By

• wp-includes/widgets/class-wp-widget-tag-cloud.php: WP_Widget_Tag_Cloud::widget()

---

User Contributed Notes

1. Skip to note content You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note Contributed by Codex

   Cloud limited in size and ordered by count rather than name

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

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.

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

	wp_tag_cloud( $args );
?>

Cloud displayed under Popular Tags title

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

Cloud returned as array but not displayed

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

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

Display a Category Cloud

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

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

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”.

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