云策 WordPress 开发者社区

函数文档

get_taxonomy_labels()

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

概述

get_taxonomy_labels() 函数基于 WP_Taxonomy 对象构建并返回一个包含所有分类法标签的对象。该函数处理默认标签值，区分非层级（如标签）和层级（如分类）分类法，并支持通过过滤器动态修改标签。

关键要点

  • 参数：接受一个必需的 WP_Taxonomy 对象作为输入。
  • 返回值：返回一个包含标签的对象，默认值根据分类法类型（非层级或层级）有所不同。
  • 标签属性：包括 name、singular_name、search_items 等，部分标签仅适用于特定分类法类型。
  • 过滤器：支持通过 taxonomy_labels_{$taxonomy} 钩子过滤标签，确保过滤后包含所有默认值。
  • 相关函数：与 WP_Taxonomy::get_default_labels() 和 _get_custom_object_labels() 等函数关联。

代码示例

function get_taxonomy_labels( $tax ) {
    $tax->labels = (array) $tax->labels;

    if ( isset( $tax->helps ) && empty( $tax->labels['separate_items_with_commas'] ) ) {
        $tax->labels['separate_items_with_commas'] = $tax->helps;
    }

    if ( isset( $tax->no_tagcloud ) && empty( $tax->labels['not_found'] ) ) {
        $tax->labels['not_found'] = $tax->no_tagcloud;
    }

    $nohier_vs_hier_defaults = WP_Taxonomy::get_default_labels();
    $nohier_vs_hier_defaults['menu_name'] = $nohier_vs_hier_defaults['name'];
    $labels = _get_custom_object_labels( $tax, $nohier_vs_hier_defaults );

    if ( ! isset( $tax->labels->template_name ) && isset( $labels->singular_name ) ) {
        $labels->template_name = sprintf( _x( '%s Archives', 'taxonomy template name' ), $labels->singular_name );
    }

    $taxonomy = $tax->name;
    $default_labels = clone $labels;
    $labels = apply_filters( "taxonomy_labels_{$taxonomy}", $labels );
    $labels = (object) array_merge( (array) $default_labels, (array) $labels );
    return $labels;
}

注意事项

  • 函数内部处理了 helps 和 no_tagcloud 属性的回退逻辑，用于设置特定标签。
  • 返回对象包含 menu_name 属性，默认与 name 属性相同，用于管理菜单选项卡。
  • 标签值可通过 taxonomy_labels_{$taxonomy} 过滤器自定义，但会确保合并默认值以避免丢失必要标签。
📄 原文内容

Builds an object with all taxonomy labels out of a taxonomy object.

Parameters

$taxWP_Taxonomyrequired
Taxonomy object.

Return

object Taxonomy labels object. The first default value is for non-hierarchical taxonomies (like tags) and the second one is for hierarchical taxonomies (like categories).

  • name string
    General name for the taxonomy, usually plural. The same as and overridden by $tax->label. Default 'Tags'/'Categories'.
  • singular_name string
    Name for one object of this taxonomy. Default 'Tag'/'Category'.
  • search_items string
    Default ‘Search Tags'/'Search Categories’.
  • popular_items string
    This label is only used for non-hierarchical taxonomies.
    Default ‘Popular Tags’.
  • all_items string
    Default ‘All Tags'/'All Categories’.
  • parent_item string
    This label is only used for hierarchical taxonomies. Default ‘Parent Category’.
  • parent_item_colon string
    The same as parent_item, but with colon : in the end.
  • name_field_description string
    Description for the Name field on Edit Tags screen.
    Default ‘The name is how it appears on your site’.
  • slug_field_description string
    Description for the Slug field on Edit Tags screen.
    Default ‘The “slug” is the URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, and hyphens’.
  • parent_field_description string
    Description for the Parent field on Edit Tags screen.
    Default ‘Assign a parent term to create a hierarchy.
    The term Jazz, for example, would be the parent of Bebop and Big Band’.
  • desc_field_description string
    Description for the Description field on Edit Tags screen.
    Default ‘The description is not prominent by default; however, some themes may show it’.
  • edit_item string
    Default ‘Edit Tag'/'Edit Category’.
  • view_item string
    Default ‘View Tag'/'View Category’.
  • update_item string
    Default ‘Update Tag'/'Update Category’.
  • add_new_item string
    Default ‘Add Tag'/'Add Category’.
  • new_item_name string
    Default ‘New Tag Name'/'New Category Name’.
  • template_name string
    Default ‘Tag Archives'/'Category Archives’.
  • separate_items_with_commas string
    This label is only used for non-hierarchical taxonomies. Default ‘Separate tags with commas’, used in the meta box.
  • add_or_remove_items string
    This label is only used for non-hierarchical taxonomies. Default ‘Add or remove tags’, used in the meta box when JavaScript is disabled.
  • choose_from_most_used string
    This label is only used on non-hierarchical taxonomies. Default ‘Choose from the most used tags’, used in the meta box.
  • not_found string
    Default ‘No tags found'/'No categories found’, used in the meta box and taxonomy list table.
  • no_terms string
    Default ‘No tags'/'No categories’, used in the posts and media list tables.
  • filter_by_item string
    This label is only used for hierarchical taxonomies. Default ‘Filter by category’, used in the posts list table.
  • items_list_navigation string
    Label for the table pagination hidden heading.
  • items_list string
    Label for the table hidden heading.
  • most_used string
    Title for the Most Used tab. Default ‘Most Used’.
  • back_to_items string
    Label displayed after a term has been updated.
  • item_link string
    Used in the block editor. Title for a navigation link block variation.
    Default ‘Tag Link'/'Category Link’.
  • item_link_description string
    Used in the block editor. Description for a navigation link block variation. Default ‘A link to a tag'/'A link to a category’.

Source

function get_taxonomy_labels( $tax ) {
	$tax->labels = (array) $tax->labels;

	if ( isset( $tax->helps ) && empty( $tax->labels['separate_items_with_commas'] ) ) {
		$tax->labels['separate_items_with_commas'] = $tax->helps;
	}

	if ( isset( $tax->no_tagcloud ) && empty( $tax->labels['not_found'] ) ) {
		$tax->labels['not_found'] = $tax->no_tagcloud;
	}

	$nohier_vs_hier_defaults = WP_Taxonomy::get_default_labels();

	$nohier_vs_hier_defaults['menu_name'] = $nohier_vs_hier_defaults['name'];

	$labels = _get_custom_object_labels( $tax, $nohier_vs_hier_defaults );

	if ( ! isset( $tax->labels->template_name ) && isset( $labels->singular_name ) ) {
		/* translators: %s: Taxonomy name. */
		$labels->template_name = sprintf( _x( '%s Archives', 'taxonomy template name' ), $labels->singular_name );
	}

	$taxonomy = $tax->name;

	$default_labels = clone $labels;

	/**
	 * Filters the labels of a specific taxonomy.
	 *
	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
	 *
	 * Possible hook names include:
	 *
	 *  - `taxonomy_labels_category`
	 *  - `taxonomy_labels_post_tag`
	 *
	 * @since 4.4.0
	 *
	 * @see get_taxonomy_labels() for the full list of taxonomy labels.
	 *
	 * @param object $labels Object with labels for the taxonomy as member variables.
	 */
	$labels = apply_filters( "taxonomy_labels_{$taxonomy}", $labels );

	// Ensure that the filtered labels contain all required default values.
	$labels = (object) array_merge( (array) $default_labels, (array) $labels );

	return $labels;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( “taxonomy_labels_{$taxonomy}”, object $labels )

Filters the labels of a specific taxonomy.

Uses Description
WP_Taxonomy::get_default_labels()wp-includes/class-wp-taxonomy.php

Returns the default labels for taxonomies.
_get_custom_object_labels()wp-includes/post.php

Builds an object with custom-something object (post type, taxonomy) labels out of a custom-something object
_x()wp-includes/l10n.php

Retrieves translated string with gettext context.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 2 moreShow less

Used by Description
WP_Taxonomy::set_props()wp-includes/class-wp-taxonomy.php

Sets taxonomy properties.

Changelog

Version Description
6.6.0 Added the template_name label.
5.9.0 Added the name_field_description, slug_field_description, parent_field_description, and desc_field_description labels.
5.8.0 Added the item_link and item_link_description labels.
5.7.0 Added the filter_by_item label.
4.9.0 Added the most_used and back_to_items labels.
4.4.0 Added the items_list_navigation and items_list labels.
4.3.0 Added the no_terms label.
3.0.0 Introduced.

Show 3 moreShow less

User Contributed Notes