WordPress 5.3在REST API中支持object和array元数据类型

从WordPress 5.3开始，register_meta函数（包括register_post_meta）将支持'object'对象和'array'数组元数据类型。以前，要创建复杂的基于元数据的Gutenberg区块，需要对块的复杂属性值进行JSON编码，然后将该字符串传递给API。 现在 REST API 将原生支持那些复杂的元数据类型。这允许利用REST API来执行基于架构的验证，并且还简化通过REST API与这些复杂值交互的客户端代码。

重要的是，这些数据类型遵循JSON规范，而不是PHP定义。为了进行比较，这意味着JSON object类型等效于PHP中的关联数组。JSON array类型是一个数字索引数组。

注册复杂的元数据字段时，几乎总是需要同时指定一个描述预期结构的JSON模式。这可以通过show_in_rest从简单true值切换到array在schema数组键下指定所需架构的来完成。

Object 示例

以下代码示例注册了一个名为“ release”的文章元字段，该字段接受给定的JSON数据。

{
  "meta": {
    "release": {
      "version": "5.2",
      "artist": "Jaco"
    }
  }
}

register_post_meta(
     'post',
     'release',
     array(
         'single'       => true,
         'type'         => 'object',
         'show_in_rest' => array(
             'schema' => array(
                 'type'       => 'object',
                 'properties' => array(
                     'version' => array(
                         'type' => 'string',
                     ),
                     'artist'  => array(
                         'type' => 'string',
                     ),
                 ),
             ),
         ),
     )
 );

默认情况下，仅允许在架构中明确指定的属性。该additionalProperties关键字可以用来改变这种行为。additionalProperties应该是用于验证所有未知对象成员的另一个JSON模式。例如，要强制所有其他属性均为数字，可以使用以下代码。

{
   "meta": {
     "release": {
       "version": "5.2",
       "artist": "Jaco",
       "unknown_field": 5.3
     }
   }
 }

register_post_meta(
     'post',
     'version',
     array(
         'single'       => true,
         'type'         => 'object',
         'show_in_rest' => array(
             'schema' => array(
                 'type'       => 'object',
                 'properties' => array(
                     'version' => array(
                         'type' => 'string',
                     ),
                     'artist'  => array(
                         'type' => 'string',
                     ),
                 ),
                 'additionalProperties' => array(
                     'type' => 'number',
                 ),
             ),
         ),
     )
 );

另外， 可以将 additionalProperties设置为true允许任何格式的未知属性，但是不建议这样做。

Array 示例

以下代码示例注册了一个名为“ projects”的文章元字段，该字段包含一个接受给定JSON数据的项目名称列表。

{
   "meta": {
     "projects": [
       "WordPress",
       "BuddyPress"
     ]
   }
 }

register_post_meta(
     'post',
     'projects',
     array(
         'single'       => true,
         'type'         => 'array',
         'show_in_rest' => array(
             'schema' => array(
                 'type'  => 'array',
                 'items' => array(
                     'type' => 'string',
                 ),
             ),
         ),
     )
 );

“ items”关键字用于定义JSON模式，以验证每个数组成员所针对的JSON模式。它可以是“string”之类的简单类型，也可以是“object”之类的复杂类型。

例如，要接受给定的JSON数据，将使用以下元数据注册。

{
   "meta": {
     "projects": [
       {
         "name": "WordPress",
         "website": "https://wordpress.org"
       },
       {
         "name": "BuddyPress",
         "website": "https://buddypress.org"
       }
     ]
   }
 }

register_post_meta(
     'post',
     'projects',
     array(
         'single'       => true,
         'type'         => 'array',
         'show_in_rest' => array(
             'schema' => array(
                 'items' => array(
                     'type'       => 'object',
                     'properties' => array(
                         'name'    => array(
                             'type' => 'string',
                         ),
                         'website' => array(
                             'type'   => 'string',
                             'format' => 'uri',
                         ),
                     ),
                 ),
             ),
         ),
     )
 );

非单个元数据

非单个（ Non-single ）元字段每个文章具有一组值，而不是每个文章具有一个值。这些值中的每一个都存储在postmeta表中的单独行中。

array和object数据类型也可以用在非单个元数据字段。例如，如果先前的“ release”元键single设置为false，则可接受以下JSON数据。

{
   "meta": {
     "release": [
       {
         "version": "5.2",
         "artist": "Jaco"
       },
       {
         "version": "5.1",
         "artist": "Betty"
       }
     ]
   }
 }

这将添加两个postmeta数据库行。第一个包含{ "version": "5.2", "artist": "Jaco" }，第二个包含{ "version": "5.1", "artist": "Betty" }。

同样， 如果将single设置为false ，下面的数据将被“projects”示例所接受。

{
   "meta": {
     "projects": [
       [
         "WordPress",
         "BuddyPress"
       ],
       [
         "bbPress"
       ]
     ]
   }
 }

这将添加两个postmeta数据库行。第一个包含[ "WordPress", "BuddyPress" ]，第二个包含[ "bbPress" ]。

无效的存储值

如果元字段的现有值未针对注册的类型和架构进行验证，则该元字段的值将返回 null 。这是5.3中的更改，以前仅验证了元类型。