register_theme_feature()

💡 云策文档标注

概述

register_theme_feature() 函数用于注册主题功能，以便在 add_theme_support() 中使用。它仅描述功能的支持选项，而不表示当前主题已支持该功能。

关键要点

函数用于注册主题功能，参数包括 $feature（功能名称）和 $args（可选参数数组）。
$feature 参数是必需的字符串，标识功能名称，如 'custom-logo'、'post-thumbnails' 等。
$args 参数可选，用于描述功能，包括 type、variadic、description、show_in_rest 等属性。
函数返回 true 或 WP_Error 对象，指示注册是否成功。
注册的功能存储在全局变量 $_wp_registered_theme_features 中。

代码示例

function register_theme_feature( $feature, $args = array() ) {
    global $_wp_registered_theme_features;
    if ( ! is_array( $_wp_registered_theme_features ) ) {
        $_wp_registered_theme_features = array();
    }
    $defaults = array(
        'type'         => 'boolean',
        'variadic'     => false,
        'description'  => '',
        'show_in_rest' => false,
    );
    $args = wp_parse_args( $args, $defaults );
    // 更多参数处理和验证逻辑
    $_wp_registered_theme_features[ $feature ] = $args;
    return true;
}

注意事项

type 参数必须是有效的 JSON Schema 类型（如 'string'、'boolean'、'array' 等），否则返回 WP_Error。
当 variadic 为 true 时，type 必须为 'array'，否则返回错误。
对于 'array' 或 'object' 类型，如果 show_in_rest 启用，必须提供 schema 定义。
prepare_callback 必须是可调用函数，否则返回错误。

📄 原文内容

Registers a theme feature for use in add_theme_support() .

Description

This does not indicate that the active theme supports the feature, it only describes the feature’s supported options.

Parameters

$featurestringrequired

The name uniquely identifying the feature. See add_theme_support() for the list of possible values.

More Arguments from add_theme_support( … $feature )

The feature being added. Likely core values include:

'admin-bar'
'align-wide'
'appearance-tools'
'automatic-feed-links'
'block-templates'
'block-template-parts'
'border'
'core-block-patterns'
'custom-background'
'custom-header'
'custom-line-height'
'custom-logo'
'customize-selective-refresh-widgets'
'custom-spacing'
'custom-units'
'dark-editor-style'
'disable-custom-colors'
'disable-custom-font-sizes'
'disable-custom-gradients'
'disable-layout-styles'
'editor-color-palette'
'editor-gradient-presets'
'editor-font-sizes'
'editor-spacing-sizes'
'editor-styles'
'featured-content'
'html5'
'link-color'
'menus'
'post-formats'
'post-thumbnails'
'responsive-embeds'
'starter-content'
'title-tag'
'widgets'
'widgets-block-editor'
'wp-block-styles'

$argsarrayoptional

Data used to describe the theme.

type string
The type of data associated with this feature.
Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'. Defaults to 'boolean'.
variadic bool
Does this feature utilize the variadic support of add_theme_support() , or are all arguments specified as the second parameter. Must be used with the “array” type.
description string
A short description of the feature. Included in the Themes REST API schema. Intended for developers.
show_in_rest bool|array
Whether this feature should be included in the Themes REST API endpoint.
Defaults to not being included. When registering an ‘array’ or ‘object’ type, this argument must be an array with the ‘schema’ key.
- schema array
  Specifies the JSON Schema definition describing the feature. If any objects in the schema do not include the 'additionalProperties' keyword, it is set to false.
- name string
  An alternate name to be used as the property name in the REST API.
- prepare_callback callable
  A function used to format the theme support in the REST API.
  Receives the raw theme support value.

More Arguments from add_theme_support( … $args )

Optional extra arguments to pass along with certain features.

Default:array()

Return

true|WP_Error True if the theme feature was successfully registered, a WP_Error object if not.

Source

function register_theme_feature( $feature, $args = array() ) {
	global $_wp_registered_theme_features;

	if ( ! is_array( $_wp_registered_theme_features ) ) {
		$_wp_registered_theme_features = array();
	}

	$defaults = array(
		'type'         => 'boolean',
		'variadic'     => false,
		'description'  => '',
		'show_in_rest' => false,
	);

	$args = wp_parse_args( $args, $defaults );

	if ( true === $args['show_in_rest'] ) {
		$args['show_in_rest'] = array();
	}

	if ( is_array( $args['show_in_rest'] ) ) {
		$args['show_in_rest'] = wp_parse_args(
			$args['show_in_rest'],
			array(
				'schema'           => array(),
				'name'             => $feature,
				'prepare_callback' => null,
			)
		);
	}

	if ( ! in_array( $args['type'], array( 'string', 'boolean', 'integer', 'number', 'array', 'object' ), true ) ) {
		return new WP_Error(
			'invalid_type',
			__( 'The feature "type" is not valid JSON Schema type.' )
		);
	}

	if ( true === $args['variadic'] && 'array' !== $args['type'] ) {
		return new WP_Error(
			'variadic_must_be_array',
			__( 'When registering a "variadic" theme feature, the "type" must be an "array".' )
		);
	}

	if ( false !== $args['show_in_rest'] && in_array( $args['type'], array( 'array', 'object' ), true ) ) {
		if ( ! is_array( $args['show_in_rest'] ) || empty( $args['show_in_rest']['schema'] ) ) {
			return new WP_Error(
				'missing_schema',
				__( 'When registering an "array" or "object" feature to show in the REST API, the feature's schema must also be defined.' )
			);
		}

		if ( 'array' === $args['type'] && ! isset( $args['show_in_rest']['schema']['items'] ) ) {
			return new WP_Error(
				'missing_schema_items',
				__( 'When registering an "array" feature, the feature's schema must include the "items" keyword.' )
			);
		}

		if ( 'object' === $args['type'] && ! isset( $args['show_in_rest']['schema']['properties'] ) ) {
			return new WP_Error(
				'missing_schema_properties',
				__( 'When registering an "object" feature, the feature's schema must include the "properties" keyword.' )
			);
		}
	}

	if ( is_array( $args['show_in_rest'] ) ) {
		if ( isset( $args['show_in_rest']['prepare_callback'] )
			&& ! is_callable( $args['show_in_rest']['prepare_callback'] )
		) {
			return new WP_Error(
				'invalid_rest_prepare_callback',
				sprintf(
					/* translators: %s: prepare_callback */
					__( 'The "%s" must be a callable function.' ),
					'prepare_callback'
				)
			);
		}

		$args['show_in_rest']['schema'] = wp_parse_args(
			$args['show_in_rest']['schema'],
			array(
				'description' => $args['description'],
				'type'        => $args['type'],
				'default'     => false,
			)
		);

		if ( is_bool( $args['show_in_rest']['schema']['default'] )
			&& ! in_array( 'boolean', (array) $args['show_in_rest']['schema']['type'], true )
		) {
			// Automatically include the "boolean" type when the default value is a boolean.
			$args['show_in_rest']['schema']['type'] = (array) $args['show_in_rest']['schema']['type'];
			array_unshift( $args['show_in_rest']['schema']['type'], 'boolean' );
		}

		$args['show_in_rest']['schema'] = rest_default_additional_properties_to_false( $args['show_in_rest']['schema'] );
	}

	$_wp_registered_theme_features[ $feature ] = $args;

	return true;
}

View all references View on Trac View on GitHub

Uses	Description
rest_default_additional_properties_to_false()`wp-includes/rest-api.php`	Sets the “additionalProperties” to false by default for all object definitions in the schema.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
WP_Error::__construct()`wp-includes/class-wp-error.php`	Initializes the error.

Show 2 more Show less

Used by	Description
create_initial_theme_features()`wp-includes/theme.php`	Creates the initial theme features when the ‘setup_theme’ action is fired.

Changelog

Version	Description
5.5.0	Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.

云策 WordPress 开发者社区

函数文档

register_theme_feature()

概述

关键要点

代码示例

注意事项

Description

See also

Parameters

Return

Source

Changelog

User Contributed Notes

函数文档

概述

关键要点

代码示例

注意事项

Description

See also

Parameters

Return

Source

Related

Changelog

User Contributed Notes