详解 WordPress `register_meta()` 函数源码：如何将自定义元数据暴露给 Gutenberg 和 REST API。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，大家好！我是你们的老朋友，代码界的段子手，今天咱们来聊聊 WordPress 里一个既强大又有点儿小傲娇的函数：register_meta()。

这玩意儿，说白了，就是个“媒婆”，专门负责把你的自定义元数据（custom meta data）介绍给 WordPress 的两大“相亲对象”——Gutenberg 编辑器和 REST API。让他们能够互相认识，并且能够愉快的互动。

为什么要认识 Gutenberg 和 REST API？

这个问题问得好！

Gutenberg 编辑器： 这是 WordPress 的“新门面”，所见即所得，用户体验杠杠的。如果你想让用户在编辑文章/页面时，能方便地修改你的自定义字段，那就必须让 Gutenberg “认识”这些字段。
REST API： 这是 WordPress 的“数据高速公路”，让外部应用（比如手机 APP、前端框架）可以轻松地读取和修改 WordPress 的数据。如果你的自定义字段需要被外部应用访问，那就必须通过 REST API “暴露”出去。

register_meta()：牵线搭桥的红娘

register_meta() 函数的作用，就是告诉 WordPress，哪些自定义元数据应该被 Gutenberg 和 REST API 知道，以及如何处理这些数据。

语法结构：

register_meta( string $object_type, string $meta_key, array $args = array() )

$object_type：指定元数据所属的对象类型。可以是 post、page、comment、user 等等。简单来说，就是告诉WordPress，这是哪个对象的元数据。
$meta_key：元数据的键名。也就是你存储自定义字段时用的名字。
$args：一个数组，包含各种参数，控制元数据的行为。这是重点！

$args 参数详解：

$args 参数才是这个函数的灵魂所在。它决定了元数据如何被展示、如何被验证、如何被存储等等。我们一个个来看：

参数名称	类型	默认值	描述
`type`	string	`string`	元数据的类型。可以是 `string`、`integer`、`boolean`、`number`、`array`、`object`。告诉 WordPress 这是什么类型的数据，好让它正确处理。
`description`	string	`''`	元数据的描述。这个描述会在 REST API 的 schema 中显示，方便开发者了解这个字段的作用。
`single`	boolean	`false`	是否为单值元数据。如果为 `true`，则每个对象只能有一个该元数据的值。如果为 `false`，则每个对象可以有多个该元数据的值（类似于文章的标签）。
`sanitize_callback`	callable	`null`	用于清理元数据值的回调函数。在保存元数据之前，会先调用这个函数，防止恶意数据注入。
`auth_callback`	callable	`null`	用于验证用户是否有权限修改元数据的回调函数。只有通过验证的用户才能修改元数据。
`show_in_rest`	mixed	`false`	是否在 REST API 中显示元数据。可以设置为 `true`、`false` 或一个包含更多选项的数组。如果设置为 `true`，则元数据会直接显示在 REST API 的响应中。如果是数组，可以控制元数据在 REST API 中的显示方式。
`default`	mixed	`''`	元数据的默认值。如果元数据没有值，则使用这个默认值。
`validate_callback`	callable	`null`	用于验证元数据值的回调函数。在保存元数据之前，会先调用这个函数，验证元数据的值是否符合要求。

实战演练：让 Gutenberg 和 REST API “爱上”你的自定义字段

咱们来写几个例子，看看如何用 register_meta() 让 Gutenberg 和 REST API 乖乖听话。

例子 1：一个简单的作者简介

假设我们想给文章添加一个“作者简介”的自定义字段，让用户可以在 Gutenberg 编辑器中填写，并且可以通过 REST API 获取。

<?php
add_action( 'init', 'register_author_bio_meta' );

function register_author_bio_meta() {
    register_meta( 'post', 'author_bio', array(
        'type'              => 'string',
        'description'       => '作者简介',
        'single'            => true,
        'sanitize_callback' => 'sanitize_text_field', // 清理用户输入
        'auth_callback'     => '__return_true', // 允许所有用户修改
        'show_in_rest'      => true, // 在 REST API 中显示
    ) );
}
?>

这段代码做了什么？

add_action( 'init', 'register_author_bio_meta' )：在 WordPress 初始化时，执行 register_author_bio_meta() 函数。
register_meta( 'post', 'author_bio', ...)：注册一个元数据，类型为 post，键名为 author_bio。
'type' => 'string'：指定元数据类型为字符串。
'description' => '作者简介'：设置元数据的描述。
'single' => true'：指定元数据为单值。
'sanitize_callback' => 'sanitize_text_field'：使用 sanitize_text_field() 函数清理用户输入，防止 XSS 攻击。
'auth_callback' => '__return_true'：允许所有用户修改这个字段。（实际项目中，你需要根据用户角色进行权限控制）
'show_in_rest' => true'：在 REST API 中显示这个字段。

效果：

Gutenberg 编辑器： 在文章编辑页面，你会看到一个“自定义字段”区域，里面有一个名为 author_bio 的字段，可以输入作者简介。
REST API： 通过 REST API 获取文章数据时，你会看到 author_bio 字段的值。

例子 2：一个包含更多选项的show_in_rest

如果我们想更精细地控制元数据在 REST API 中的显示方式，可以使用 show_in_rest 的数组形式。

<?php
add_action( 'init', 'register_featured_color_meta' );

function register_featured_color_meta() {
    register_meta( 'post', 'featured_color', array(
        'type'              => 'string',
        'description'       => '特色颜色',
        'single'            => true,
        'sanitize_callback' => 'sanitize_hex_color', // 清理用户输入
        'auth_callback'     => 'current_user_can( 'edit_posts' )', // 只有能编辑文章的用户才能修改
        'show_in_rest'      => array(
            'schema' => array(
                'type'        => 'string',
                'enum'        => array( 'red', 'green', 'blue' ), // 限制颜色选择
                'description' => '文章的特色颜色，只能是红色、绿色或蓝色',
            ),
        ),
    ) );
}

function sanitize_hex_color( $color ) {
    if ( '' === $color ) {
        return '';
    }

    // 3 or 6 hex digits, or the empty string.
    if ( preg_match( '|^#([A-Fa-f0-9]{3}){1,2}$|', $color ) ) {
        return $color;
    }

    return null;
}
?>

这段代码中，show_in_rest 的值是一个数组，包含一个 schema 元素。schema 用于定义元数据在 REST API 中的数据类型、允许的值等等。

'type' => 'string'：指定元数据类型为字符串。
'enum' => array( 'red', 'green', 'blue' )：限制元数据的值只能是 red、green 或 blue。
'description' => '文章的特色颜色，只能是红色、绿色或蓝色'：设置元数据的描述。

效果：

Gutenberg 编辑器： 你需要自己添加自定义字段的UI，例如使用edit_form_after_title action hook添加一个颜色选择器。
REST API： REST API 的 schema 会显示 featured_color 字段只能是 red、green 或 blue。如果尝试设置其他值，API 会返回错误。

例子 3：一个数组类型的元数据

假设我们想给用户添加一个“兴趣爱好”的自定义字段，用户可以有多个兴趣爱好。

<?php
add_action( 'init', 'register_user_interests_meta' );

function register_user_interests_meta() {
    register_meta( 'user', 'interests', array(
        'type'              => 'array',
        'description'       => '用户兴趣爱好',
        'single'            => false, // 允许有多个值
        'sanitize_callback' => 'sanitize_text_field',
        'auth_callback'     => 'current_user_can( 'edit_users' )',
        'show_in_rest'      => true,
    ) );
}
?>

'type' => 'array'：指定元数据类型为数组。
'single' => false'：指定元数据可以有多个值。

注意点：

sanitize_callback 和 validate_callback： 这两个回调函数非常重要！一定要对用户输入进行清理和验证，防止安全漏洞。sanitize_callback 用于清理数据，validate_callback 用于验证数据是否符合要求。
auth_callback： 权限控制也很重要！只有有权限的用户才能修改元数据。
show_in_rest： 如果你的元数据包含敏感信息，不要在 REST API 中显示！
性能： 如果你注册了大量的元数据，可能会影响 WordPress 的性能。尽量减少不必要的元数据注册。

高级技巧：

自定义 REST API 字段： 除了直接显示元数据，你还可以使用 register_rest_field() 函数，自定义 REST API 字段的显示方式。这可以让你更灵活地控制数据的输出。
Gutenberg 组件： 你可以使用 Gutenberg 的 JavaScript API，创建自定义的 Gutenberg 组件，让用户更方便地编辑自定义字段。

总结：

register_meta() 函数是 WordPress 中一个非常重要的函数，它可以让你轻松地将自定义元数据暴露给 Gutenberg 编辑器和 REST API。掌握这个函数，你就可以更好地扩展 WordPress 的功能，满足各种各样的需求。

记住，安全第一！一定要对用户输入进行清理和验证，防止安全漏洞。

好了，今天的讲座就到这里。希望大家有所收获！如果有什么问题，欢迎在评论区留言。咱们下期再见！

发表回复 取消回复

发表回复取消回复