wp_tag_cloud()

💡 云策文档标注

概述

wp_tag_cloud() 是 WordPress 核心函数，用于生成并显示标签云（tag cloud），其中标签大小基于其关联文章数量动态调整。该函数接受多种参数来自定义输出，并可通过过滤器进行修改。

关键要点

输出标签云，标签大小与使用频率成正比，支持自定义字体大小、单位、数量、格式等。
参数包括 $args 数组，可控制显示数量、链接类型、排序方式、CSS 单位等，默认值在函数内部定义。
返回值取决于 'echo' 和 'format' 参数：若 'echo' 为 true 则直接输出，否则返回字符串或数组。
内部调用 get_terms() 获取标签，并使用 wp_generate_tag_cloud() 生成云图，支持 'wp_tag_cloud' 过滤器。
相关函数包括 wp_generate_tag_cloud()、get_term_link()、get_terms() 等，用于扩展功能。

代码示例

// 显示分类和标签的云图
$args = array(
    'taxonomy' => array( 'post_tag', 'category' ),
);
wp_tag_cloud( $args );

// 显示分类云图
wp_tag_cloud( array( 'taxonomy' => 'category' ) );

// 自定义标题文本回调
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 ) );
}

注意事项

默认查询按 'count' 降序获取热门标签，但输出排序可通过 'orderby' 和 'order' 参数调整。
若 'echo' 为 false 且 'format' 为 'array'，函数返回数组供进一步处理，否则直接输出 HTML。
参数 'show_count' 控制是否显示标签计数，自版本 4.8.0 起可用。
使用 'taxonomy' 参数可扩展至其他分类法，如分类（category），支持数组形式。

📄 原文内容

Displays a tag cloud.

Description

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

Parameters

$argsarray|stringoptional

Array or string of arguments for displaying a tag cloud. See wp_generate_tag_cloud() and get_terms() for the full lists of arguments that can be passed in $args.

number int
The number of tags to display. Accepts any positive integer or zero to return all. Default 45.
link string
Whether to display term editing links or term permalinks.
Accepts 'edit' and 'view'. Default 'view'.
post_type string
The post type. Used to highlight the proper post type menu on the linked edit page. Defaults to the first post type associated with the taxonomy.
echo bool
Whether or not to echo the return value. Default true.

More Arguments from wp_generate_tag_cloud( … $args )

Array or string of arguments for generating a tag cloud.

smallest int
Smallest font size used to display tags. Paired with the value of $unit, to determine CSS text size unit. Default 8 (pt).
largest int
Largest font size used to display tags. Paired with the value of $unit, to determine CSS text size unit. Default 22 (pt).
unit string
CSS text size unit to use with the $smallest and $largest values. Accepts any valid CSS text size unit. Default 'pt'.
number int
The number of tags to return. Accepts any positive integer or zero to return all.
Default 0.
format string
Format to display the tag cloud in. Accepts 'flat' (tags separated with spaces), 'list' (tags displayed in an unordered list), or 'array' (returns an array).
Default 'flat'.
separator string
HTML or text to separate the tags. Default “n” (newline).
orderby string
Value to order tags by. Accepts 'name' or 'count'.
Default 'name'. The ‘tag_cloud_sort’ filter can also affect how tags are sorted.
order string
How to order the tags. Accepts 'ASC' (ascending), 'DESC' (descending), or 'RAND' (random). Default 'ASC'.
filter int|bool
Whether to enable filtering of the final output via ‘wp_generate_tag_cloud’. Default 1.
topic_count_text array
Nooped plural text from _n_noop() to supply to tag counts. Default null.
topic_count_text_callback callable
Callback used to generate nooped plural text for tag counts based on the count. Default null.
topic_count_scale_callback callable
Callback used to determine the tag count scaling value. Default default_topic_count_scale() .
show_count bool|int
Whether to display the tag counts. Default 0. Accepts 0, 1, or their bool equivalents.

Return

void|string|string[] Void if 'echo' argument is true, or on failure. Otherwise, tag cloud as a string or an array, depending on 'format' argument.

Source

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(
		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, $tag->taxonomy, $args['post_type'] );
		} else {
			$link = get_term_link( $tag, $tag->taxonomy );
		}

		if ( is_wp_error( $link ) ) {
			return;
		}

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

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

	/**
	 * Filters the tag cloud output.
	 *
	 * @since 2.3.0
	 *
	 * @param string|string[] $return Tag cloud as a string or an array, depending on 'format' argument.
	 * @param array           $args   An array of tag cloud arguments. See wp_tag_cloud()
	 *                                for information on accepted arguments.
	 */
	$return = apply_filters( 'wp_tag_cloud', $return, $args );

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

	echo $return;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_tag_cloud’, string|string[] $return, array $args ): Filters the tag cloud output.

Uses	Description
wp_generate_tag_cloud()`wp-includes/category-template.php`	Generates a tag cloud (heatmap) from provided data.
get_term_link()`wp-includes/taxonomy.php`	Generates a permalink for a taxonomy term archive.
get_terms()`wp-includes/taxonomy.php`	Retrieves the terms in a given taxonomy or list of taxonomies.
get_edit_term_link()`wp-includes/link-template.php`	Retrieves the URL for editing a given term.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.

Show 3 more Show less

Used by	Description
WP_Widget_Tag_Cloud::widget()`wp-includes/widgets/class-wp-widget-tag-cloud.php`	Outputs the content for the current Tag Cloud widget instance.

Changelog

Version	Description
4.8.0	Added the `show_count` argument.
2.8.0	Added the `taxonomy` argument.
2.3.0	Introduced.

User Contributed Notes

Skip to note 7 content

Codex

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Cloud limited in size and ordered by count rather than name
Log in to add feedback
Skip to note 8 content

Codex

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Cloud returned as array but not displayed

The variable $tag will contain the tag cloud for use in other PHP code
```
 
```
Log in to add feedback
Skip to note 9 content

Codex

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
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.
```
 array( 'post_tag', 'category' ), 
	); 

	wp_tag_cloud( $args );
?>
```
Log in to add feedback
Skip to note 10 content

Codex

10 years ago

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
Cloud displayed under Popular Tags title
```
<h2>Popular Tags</h2>
<ul>
<li></li>
</ul>
```
Log in to add feedback
Skip to note 11 content

Codex

10 years ago

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
Display a Category Cloud

Use the taxonomy argument to cause a cloud of categories to display.
```
 'category' ) ); ?>
```
Log in to add feedback
Skip to note 12 content

Codex

10 years ago

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
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”.
```
 'my_tag_text_callback' ) ); 

	function my_tag_text_callback( $count ) {
		return sprintf( _n( '%s picture', '%s pictures', $count ), number_format_i18n( $count ) );
	}
?>
```
Log in to add feedback

云策 WordPress 开发者社区

函数文档