云策 WordPress 开发者社区

函数文档

rest_is_field_included()

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

概述

rest_is_field_included() 函数用于在 WordPress REST API 中判断指定字段是否应包含在响应体中，支持处理嵌套字段（如 parent.child）。该函数通过检查字段数组，根据父子关系逻辑返回布尔值。

关键要点

  • 函数接受两个参数：$field（要测试的字段字符串）和 $fields（端点支持的字段数组）。
  • 返回布尔值，指示是否包含该字段。
  • 如果父字段被传入，任何嵌套子字段的存在都会使函数返回 true（例如，"title" 在 "title.raw" 或 "title.rendered" 存在时返回 true）。
  • 函数逻辑包括直接匹配和基于字符串前缀的父子关系检查。

代码示例

function rest_is_field_included( $field, $fields ) {
    if ( in_array( $field, $fields, true ) ) {
        return true;
    }

    foreach ( $fields as $accepted_field ) {
        /*
         * Check to see if $field is the parent of any item in $fields.
         * A field "parent" should be accepted if "parent.child" is accepted.
         */
        if ( str_starts_with( $accepted_field, "$field." ) ) {
            return true;
        }
        /*
         * Conversely, if "parent" is accepted, all "parent.child" fields
         * should also be accepted.
         */
        if ( str_starts_with( $field, "$accepted_field." ) ) {
            return true;
        }
    }

    return false;
}

注意事项

  • 该函数自 WordPress 5.3.0 版本引入。
  • 广泛用于多个 REST API 控制器的 prepare_item_for_response() 方法中，以优化响应字段选择。
  • 确保字段名和嵌套结构符合 API 端点定义，避免逻辑错误。
📄 原文内容

Given an array of fields to include in a response, some of which may be nested.fields, determine whether the provided field should be included in the response body.

Description

If a parent field is passed in, the presence of any nested field within that parent will cause the method to return true. For example “title” will return true if any of title, title.raw or title.rendered is provided.

Parameters

$fieldstringrequired
A field to test for inclusion in the response body.
$fieldsarrayrequired
An array of string fields supported by the endpoint.

Return

bool Whether to include the field or not.

Source

function rest_is_field_included( $field, $fields ) {
	if ( in_array( $field, $fields, true ) ) {
		return true;
	}

	foreach ( $fields as $accepted_field ) {
		/*
		 * Check to see if $field is the parent of any item in $fields.
		 * A field "parent" should be accepted if "parent.child" is accepted.
		 */
		if ( str_starts_with( $accepted_field, "$field." ) ) {
			return true;
		}
		/*
		 * Conversely, if "parent" is accepted, all "parent.child" fields
		 * should also be accepted.
		 */
		if ( str_starts_with( $field, "$accepted_field." ) ) {
			return true;
		}
	}

	return false;
}

View all references View on Trac View on GitHub

Used by Description
WP_REST_Abilities_V1_Categories_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php

Prepares an ability category for response.
WP_REST_Abilities_V1_List_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php

Prepares an ability for response.
WP_REST_Font_Faces_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-font-faces-controller.php

Prepares a single font face output for response.
WP_REST_Font_Families_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-font-families-controller.php

Prepares a single font family output for response.
WP_REST_Font_Collections_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-font-collections-controller.php

Prepare a single collection output for response.
WP_REST_Template_Autosaves_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-template-autosaves-controller.php

Prepares the item for the REST response.
WP_REST_Template_Revisions_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-template-revisions-controller.php

Prepares the item for the REST response.
WP_REST_Navigation_Fallback_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-navigation-fallback-controller.php

Matches the post data to the schema we want.
WP_REST_Global_Styles_Revisions_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-global-styles-revisions-controller.php

Prepares the revision for the REST response.
WP_REST_Block_Patterns_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php

Prepare a raw block pattern before it gets output in a REST API response.
WP_REST_Block_Pattern_Categories_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-block-pattern-categories-controller.php

Prepare a raw block pattern category before it gets output in a REST API response.
WP_REST_Menu_Items_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php

Prepares a single nav menu item output for response.
WP_REST_Global_Styles_Controller::get_theme_item()wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php

Returns the given theme global styles config.
WP_REST_Global_Styles_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php

Prepare a global styles config output for response.
WP_REST_Menus_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php

Prepares a single term output for response.
WP_REST_Menu_Locations_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-menu-locations-controller.php

Prepares a menu location object for serialization.
WP_REST_Widgets_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-widgets-controller.php

Prepares the widget for the REST response.
WP_REST_Sidebars_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php

Prepares a single sidebar output for response.
WP_REST_Templates_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php

Prepare a single template output for response
WP_REST_Widget_Types_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php

Prepares a widget type object for serialization.
WP_REST_Application_Passwords_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-application-passwords-controller.php

Prepares the application password for the REST response.
WP_REST_Block_Directory_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php

Parse block metadata for a block, and prepare it for an API response.
WP_REST_Plugins_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php

Prepares the plugin for the REST response.
WP_REST_Block_Types_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php

Prepares a block type object for serialization.
WP_REST_Search_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-search-controller.php

Prepares a single search result for response.
WP_REST_Themes_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php

Prepares a single theme output for response.
WP_REST_Users_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

Prepares a single user output for response.
WP_REST_Revisions_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php

Prepares the revision for the REST response.
WP_REST_Terms_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php

Prepares a single term output for response.
WP_REST_Posts_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

Prepares a single post output for response.
WP_REST_Taxonomies_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php

Prepares a taxonomy object for serialization.
WP_REST_Post_Types_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php

Prepares a post type object for serialization.
WP_REST_Controller::add_additional_fields_to_object()wp-includes/rest-api/endpoints/class-wp-rest-controller.php

Adds the values from additional fields to a data object.
WP_REST_Comments_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

Prepares a single comment output for response.
WP_REST_Server::get_index()wp-includes/rest-api/class-wp-rest-server.php

Retrieves the site index.

Show 30 moreShow less

Changelog

Version Description
5.3.0 Introduced.