云策 WordPress 开发者社区

函数文档

wp_register_ability_category()

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

概述

wp_register_ability_category() 函数用于注册一个新的能力类别，以组织和分组相关能力，便于发现和管理。能力类别必须在引用它们的能力之前注册，且必须在 wp_abilities_api_categories_init 动作钩子上进行。

关键要点

  • 函数用于注册能力类别，需提供唯一 slug 和参数数组
  • 必须在 wp_abilities_api_categories_init 动作钩子上调用，否则会触发 _doing_it_wrong() 警告并返回 null
  • 参数包括必需的 label 和 description，以及可选的 meta
  • 返回 WP_Ability_Category 实例或 null
  • 内部调用 WP_Ability_Categories_Registry::register() 方法

代码示例

function my_plugin_register_categories() {
    wp_register_ability_category(
        'content-management',
        array(
            'label'       => __( 'Content Management', 'my-plugin' ),
            'description' => __( 'Abilities for managing and organizing content.', 'my-plugin' ),
        )
    );
}
add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' );

注意事项

  • slug 必须仅包含小写字母数字字符和短横线（如 'data-export'）
  • 确保在正确时机注册，避免功能失败
📄 原文内容

Registers a new ability category.

Description

Ability categories provide a way to organize and group related abilities for better discoverability and management. Ability categories must be registered before abilities that reference them.

Ability categories must be registered on the wp_abilities_api_categories_init action hook.

Example:

function my_plugin_register_categories() {
    wp_register_ability_category(
        'content-management',
        array(
            'label'       => __( 'Content Management', 'my-plugin' ),
            'description' => __( 'Abilities for managing and organizing content.', 'my-plugin' ),
        )
    );
}
add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' );

See also

Parameters

$slugstringrequired
The unique slug for the ability category. Must contain only lowercase alphanumeric characters and dashes (e.g., 'data-export').
mixed> $args { An associative array of arguments for the ability category.
@type string $label Required. The human-readable label for the ability category.
@type string $description Required. A description of what abilities in this category do.
@type array $meta Optional. Additional metadata for the ability category.
}

Return

WP_Ability_Category|null The registered ability category instance on success, null on failure.

Source

function wp_register_ability_category( string $slug, array $args ): ?WP_Ability_Category {
	if ( ! doing_action( 'wp_abilities_api_categories_init' ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: 1: wp_abilities_api_categories_init, 2: ability category slug. */
				__( 'Ability categories must be registered on the %1$s action. The ability category %2$s was not registered.' ),
				'<code>wp_abilities_api_categories_init</code>',
				'<code>' . esc_html( $slug ) . '</code>'
			),
			'6.9.0'
		);
		return null;
	}

	$registry = WP_Ability_Categories_Registry::get_instance();
	if ( null === $registry ) {
		return null;
	}

	return $registry->register( $slug, $args );
}

View all references View on Trac View on GitHub

Uses Description
WP_Ability_Categories_Registry::get_instance()wp-includes/abilities-api/class-wp-ability-categories-registry.php

Utility method to retrieve the main instance of the registry class.
doing_action()wp-includes/plugin.php

Returns whether or not an action hook is currently being processed.
__()wp-includes/l10n.php

Retrieves the translation of $text.
esc_html()wp-includes/formatting.php

Escaping for HTML blocks.
_doing_it_wrong()wp-includes/functions.php

Marks something as being incorrectly called.

Show 3 moreShow less

Used by Description
wp_register_core_ability_categories()wp-includes/abilities.php

Registers the core ability categories.

Changelog

Version Description
6.9.0 Introduced.