解析 WordPress `add_meta_box()` 函数的源码：如何向后台页面添加自定义元数据框。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众，晚上好！我是今晚的主讲人，让我们一起扒一扒 WordPress 的 add_meta_box()，看看它到底是怎么把那些花花绿绿的元数据框塞到后台页面里的。

开场白：元数据框，你是我的小呀小苹果

在 WordPress 的世界里，元数据就像文章、页面等内容的“附加说明书”。想象一下，你的文章不光有标题和正文，还能有作者心情、阅读难度、推荐等级等各种自定义信息，这些信息就存在元数据里。而 add_meta_box() 就是用来把这些元数据以一个美观的框框的形式展示在后台编辑页面上的神器。

第一幕：add_meta_box() 的基本构成

add_meta_box() 的核心作用就是注册一个元数据框，让 WordPress 知道：嘿，这里有个框要显示！它的基本语法如下：

add_meta_box(
    string   $id,
    string   $title,
    callable $callback,
    string|string[]|WP_Screen $screen = null,
    string   $context = 'advanced',
    string   $priority = 'default',
    array    $callback_args = null
);

我们来逐一解读这些参数：

$id (字符串): 元数据框的唯一身份证号。记住，全局唯一！别和其他的框撞衫了，不然 WordPress 会一脸懵逼。
$title (字符串): 元数据框的标题，就是显示在框框顶部的文字。
$callback (可调用): 最关键的部分！这是一个函数，负责生成元数据框里的 HTML 内容，也就是框框里显示什么，全靠它说了算。
$screen (字符串|字符串数组|WP_Screen): 指定要在哪些页面上显示这个元数据框。可以是文章类型（’post’、’page’），也可以是自定义文章类型。甚至可以是一个 WP_Screen 对象，高级用法！
$context (字符串): 决定元数据框显示的位置。有 ‘normal’（正文下方，默认）、’advanced’（正文下方，但可拖动）、’side’（侧边栏）。
$priority (字符串): 决定元数据框的显示优先级。有 ‘high’、’core’、’default’、’low’。优先级高的框会更靠上显示。
$callback_args (数组): 传递给 $callback 函数的额外参数。方便在回调函数里获取一些外部数据。

第二幕：代码实战，手把手教你添加元数据框

光说不练假把式，我们来写个例子，添加一个“作者心情”的元数据框到文章编辑页面。

定义 add_meta_box()：

add_action( 'add_meta_boxes', 'my_add_meta_box' );

function my_add_meta_box() {
    add_meta_box(
        'author_mood',  // ID: 作者心情
        '作者心情',      // 标题
        'author_mood_callback', // 回调函数
        'post',         // 显示在文章编辑页面
        'side',         // 显示在侧边栏
        'high'          // 优先级高
    );
}

解释：

add_action( 'add_meta_boxes', 'my_add_meta_box' ); 这行代码告诉 WordPress，在添加元数据框的时候，执行 my_add_meta_box 函数。
my_add_meta_box 函数里调用了 add_meta_box()，注册了一个ID为 author_mood 的元数据框，标题是"作者心情"，显示在文章编辑页面的侧边栏，优先级较高。

定义回调函数 author_mood_callback()：

function author_mood_callback( $post ) {
    // 获取已保存的元数据值
    $mood = get_post_meta( $post->ID, '_author_mood', true );

    // 输出 HTML 表单
    echo '<label for="author_mood_field">今天心情如何？</label>';
    echo '<select id="author_mood_field" name="author_mood_field">';
    echo '<option value="happy" ' . selected( $mood, 'happy', false ) . '>快乐</option>';
    echo '<option value="sad" ' . selected( $mood, 'sad', false ) . '>悲伤</option>';
    echo '<option value="angry" ' . selected( $mood, 'angry', false ) . '>愤怒</option>';
    echo '</select>';

    // 添加一个 nonce 字段，用于安全验证
    wp_nonce_field( 'author_mood_nonce', 'author_mood_nonce_field' );
}

解释：

$post 参数： WordPress 会自动把当前文章对象传递给回调函数。
get_post_meta()：从数据库中获取已保存的作者心情。 '_author_mood' 是元数据的键名，注意前面加下划线，表示这是一个自定义元数据（通常以下划线开头的元数据是隐藏的，不会在“自定义字段”里显示）。
selected()： WordPress 的函数，用于在 <select> 选项中标记已选中的选项。
wp_nonce_field()：生成一个随机数，用于防止跨站请求伪造（CSRF）攻击。非常重要！

保存元数据：

add_action( 'save_post', 'save_author_mood' );

function save_author_mood( $post_id ) {
    // 验证 nonce 字段
    if ( ! isset( $_POST['author_mood_nonce_field'] ) || ! wp_verify_nonce( $_POST['author_mood_nonce_field'], 'author_mood_nonce' ) ) {
        return;
    }

    // 检查用户权限
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return;
    }

    // 清理和保存数据
    if ( isset( $_POST['author_mood_field'] ) ) {
        $mood = sanitize_text_field( $_POST['author_mood_field'] );
        update_post_meta( $post_id, '_author_mood', $mood );
    }
}

解释：

add_action( 'save_post', 'save_author_mood' ); 告诉 WordPress，在保存文章的时候，执行 save_author_mood 函数。
wp_verify_nonce()：验证 nonce 字段，确保请求来自合法的来源。
current_user_can()：检查当前用户是否有权限编辑这篇文章。
sanitize_text_field()：对用户输入的数据进行清理，防止恶意代码注入。
update_post_meta()：将作者心情保存到数据库。

第三幕：高级技巧，玩转元数据框

使用 $callback_args 传递参数：

有时候，我们需要在回调函数里使用一些外部数据。比如，我们想根据当前用户的角色，显示不同的心情选项。

add_action( 'add_meta_boxes', 'my_add_meta_box' );

function my_add_meta_box() {
    $user = wp_get_current_user();
    $roles = ( array ) $user->roles;

    $args = array(
        'user_roles' => $roles,
    );

    add_meta_box(
        'author_mood',
        '作者心情',
        'author_mood_callback',
        'post',
        'side',
        'high',
        $args  // 传递参数
    );
}

function author_mood_callback( $post, $args ) {
    $user_roles = $args['args']['user_roles']; // 获取传递的参数

    // 根据用户角色显示不同的心情选项
    if ( in_array( 'administrator', $user_roles ) ) {
        $mood_options = array(
            'happy' => '快乐',
            'sad'   => '悲伤',
            'angry' => '愤怒',
            'super_happy' => '超级快乐',
        );
    } else {
        $mood_options = array(
            'happy' => '快乐',
            'sad'   => '悲伤',
            'angry' => '愤怒',
        );
    }

    $mood = get_post_meta( $post->ID, '_author_mood', true );

    echo '<label for="author_mood_field">今天心情如何？</label>';
    echo '<select id="author_mood_field" name="author_mood_field">';
    foreach ( $mood_options as $value => $label ) {
        echo '<option value="' . $value . '" ' . selected( $mood, $value, false ) . '>' . $label . '</option>';
    }
    echo '</select>';

    wp_nonce_field( 'author_mood_nonce', 'author_mood_nonce_field' );
}

解释：

在 add_meta_box() 的第七个参数 $callback_args 中，我们传递了一个包含用户角色的数组。
在 author_mood_callback() 函数中，我们可以通过 $args['args']['user_roles'] 获取到传递的参数。

使用 WP_Screen 对象：

$screen 参数可以接受一个 WP_Screen 对象，这允许你更精确地控制元数据框的显示位置。

add_action( 'add_meta_boxes', 'my_add_meta_box' );

function my_add_meta_box() {
    $screen = get_current_screen(); // 获取当前屏幕对象

    if ( $screen && $screen->id === 'my_custom_post_type' ) { // 判断是否是自定义文章类型 'my_custom_post_type' 的编辑页面
        add_meta_box(
            'author_mood',
            '作者心情',
            'author_mood_callback',
            $screen,  // 使用 WP_Screen 对象
            'side',
            'high'
        );
    }
}

解释：

get_current_screen() 函数可以获取当前屏幕的 WP_Screen 对象。
我们可以通过 $screen->id 属性来判断当前页面是否是指定的页面。

使用不同的 context 和 priority 调整布局：

context 和 priority 参数可以让你灵活地调整元数据框在页面上的显示位置和优先级。

`context`	描述
`normal`	元数据框显示在正文编辑器下方，用户可以拖动调整位置。
`advanced`	元数据框显示在正文编辑器下方，用户可以拖动调整位置（与 `normal` 类似，但通常用于更高级的元数据）。
`side`	元数据框显示在侧边栏。

`priority`	描述
`high`	元数据框的优先级最高，会显示在最上面（在同等 `context` 下）。
`core`	WordPress 核心使用的元数据框的优先级。
`default`	默认优先级。
`low`	元数据框的优先级最低，会显示在最下面（在同等 `context` 下）。

第四幕：常见问题与注意事项

$id 冲突：

确保你的 $id 是全局唯一的。如果与其他插件或主题的元数据框 ID 冲突，可能会导致显示问题。
权限问题：

在保存元数据之前，一定要检查用户是否有权限编辑这篇文章。否则，可能会导致安全问题。
数据清理：

对用户输入的数据进行清理，防止恶意代码注入。使用 sanitize_text_field()、sanitize_email() 等函数。
nonce 验证：

使用 wp_nonce_field() 生成 nonce 字段，并在保存元数据之前验证 nonce 字段，防止 CSRF 攻击。
性能优化：

如果你的元数据框里包含大量的 HTML 代码或复杂的逻辑，可能会影响页面的加载速度。尽量优化你的代码，减少不必要的数据库查询。

尾声：元数据框，让你的 WordPress 更加强大

add_meta_box() 是 WordPress 提供的一个非常强大的工具，可以让你轻松地向后台页面添加自定义元数据框，从而扩展 WordPress 的功能。掌握了 add_meta_box() 的用法，你就可以打造出更加个性化、更加强大的 WordPress 网站。

好了，今天的讲座就到这里，希望大家有所收获！感谢大家的观看！

发表回复 取消回复

发表回复取消回复