云策 WordPress 开发者社区

钩子文档

widget_tag_cloud_args

查看官方原文 ↗
💡 云策文档标注

概述

widget_tag_cloud_args 是一个 WordPress 过滤器，用于修改标签云小工具的参数，包括分类法、字体大小、显示格式等。开发者可以通过此 Hook 自定义标签云的输出行为。

关键要点

  • 过滤器名称：widget_tag_cloud_args，用于过滤标签云小工具的参数数组
  • 参数：$args（标签云参数数组）和 $instance（当前小工具设置数组），后者在 WordPress 4.9.0 版本中添加
  • 默认参数：包括 smallest、largest、unit、number、format、separator、orderby、order、exclude、include、link、taxonomy、echo 等，控制标签大小、数量、排序和显示方式
  • 相关函数：与 wp_tag_cloud() 和 WP_Widget_Tag_Cloud::widget() 关联，用于输出标签云内容
  • 版本变更：WordPress 4.9.0 添加 $instance 参数，3.0.0 添加分类法下拉菜单，2.8.0 引入此过滤器
  • 注意事项：用户反馈指出，在使用 Gutenberg 标签云时，此过滤器可能不会运行，需注意兼容性问题

代码示例

/**
 * 修改标签云小工具参数，使所有标签字体大小相同并使用列表格式以提高可访问性。
 *
 * @param array $args 标签云小工具的参数。
 * @return array 过滤后的标签云小工具参数。
 */
function prefix_widget_tag_cloud_args( $args ) {
	$args['largest']  = 1;
	$args['smallest'] = 1;
	$args['unit']     = 'em';
	$args['format']   = 'list';

	return $args;
}

add_filter( 'widget_tag_cloud_args', 'prefix_widget_tag_cloud_args', 10, 1 );

注意事项

  • 此过滤器可能不适用于 Gutenberg 标签云，使用时需测试兼容性
  • 参数 $instance 在 WordPress 4.9.0 及更高版本中可用，允许访问小工具实例设置
  • 可以通过修改 $args 数组中的键值来自定义标签云行为，如调整字体大小、显示格式或包含特定标签 ID
📄 原文内容

Filters the taxonomy used in the Tag Cloud widget.

Description

See also

Parameters

$argsarray
Args used for the tag cloud widget.
$instancearray
Array of settings for the current widget.

More Information

By default, the following parameters are available to $args:

  • 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
  • link – view
  • taxonomy – Use post tags for basis of cloud
  • echo – echo the results

Source

apply_filters(
	'widget_tag_cloud_args',
	array(
		'taxonomy'   => $current_taxonomy,
		'echo'       => false,
		'show_count' => $show_count,
	),
	$instance
)

View all references View on Trac View on GitHub

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.9.0 Added the $instance parameter.
3.0.0 Added taxonomy drop-down.
2.8.0 Introduced.

User Contributed Notes

  2. Skip to note 5 content


    Mahdi Yazdani


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Modifies tag cloud widget arguments to display all tags in the same font size and use list format for better accessibility.

    /**
 * Modifies tag cloud widget arguments to display all tags in the same font size
 * and use list format for better accessibility.
 *
 * @param 	array $args Arguments for tag cloud widget.
 * @return 	array The filtered arguments for tag cloud widget.
 */
function prefix_widget_tag_cloud_args( $args ) {
	$args['largest']  = 1;
	$args['smallest'] = 1;
	$args['unit']     = 'em';
	$args['format']   = 'list';

	return $args;
}

add_filter( 'widget_tag_cloud_args',    'prefix_widget_tag_cloud_args' 		10, 1 );

  3. Skip to note 6 content


    Steven Lin


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Example Migrated from Codex:

    Include specific tag IDs in tag cloud widget.

    add_filter( 'widget_tag_cloud_args', 'filter_tag_cloud_widget' );

function filter_tag_cloud_widget($args, $instance) {

    $include = array( 58, 59 );

    $args = array(
        'include' => $include,
        'taxonomy' => $current_taxonomy,
        'echo' => false,     
    );

    return $args;
}