剖析 `add_meta_box()` 函数的源码，解释它是如何将自定义元数据框添加到全局数组 “ 中的。

各位观众，晚上好！我是你们的老朋友，今天咱们来聊聊WordPress的 add_meta_box() 函数。这玩意儿看似简单，但背后藏着不少小秘密。今天咱们就扒开它的源码，看看它到底是如何把自定义元数据框塞到WordPress的全局数组 $ 中的。准备好了吗？咱们发车啦！

一、什么是元数据框？为什么要折腾它？

在开始之前，我们先简单回顾一下什么是元数据框（Meta Box）。简单来说，就是WordPress后台文章、页面等编辑界面上，那些用来让你输入额外信息的方框。比如，你可以用元数据框来设置文章的作者署名、来源链接、阅读时长等等。

为什么要折腾它呢？因为WordPress自带的字段有时候不够用啊！我们需要更灵活的方式来存储和展示数据。所以，自定义元数据框就成了我们的好帮手。

二、add_meta_box() 函数：元数据框的“月老”

add_meta_box() 函数就是元数据框的“月老”，负责把你的自定义元数据框“嫁”接到WordPress后台。它的基本语法如下：

<?php
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	string	元数据框的唯一ID，别和别人的重复了，不然会打架的！
$title	string	元数据框的标题，显示在方框顶部的文字。
$callback	callable	回调函数，负责渲染元数据框的内容。这个函数需要你来定义，里面写上你想显示什么表单字段、HTML元素等等。
$screen	string|string[]|WP_Screen	决定元数据框显示在哪个页面。可以是文章类型（post, page），也可以是自定义文章类型。还可以是 WP_Screen 对象。如果省略，则显示在所有文章类型上。
$context	string	元数据框的位置。可选值：'normal'（内容区域，默认）、'advanced'（内容区域下方）、'side'（侧边栏）。
$priority	string	元数据框的优先级。可选值：'high'（高）、'core'（核心）、'default'（默认）、'low'（低）。优先级越高，元数据框显示的位置越靠上。
$callback_args	array	传递给回调函数的参数。

三、add_meta_box() 源码剖析：深入虎穴，一探究竟

好了，参数说明看完，咱们就来深入 add_meta_box() 的源码，看看它到底是怎么工作的。

1. 函数定义和参数处理

add_meta_box() 函数位于 wp-admin/includes/template.php 文件中（别找错了哦！）。它的源码大概是这样的：

<?php
function add_meta_box( $id, $title, $callback, $screen = null, $context = 'advanced', $priority = 'default', $callback_args = null ) {
    global $wp_meta_boxes;

    $screen = convert_to_screen( $screen );

    add_action( 'add_meta_boxes', function() use ( $id, $title, $callback, $screen, $context, $priority, $callback_args ) {
        add_meta_box_cb( $id, $title, $callback, $screen, $context, $priority, $callback_args );
    } );
}
?>

首先，它声明了一个全局变量 $wp_meta_boxes。这个变量就是我们要重点关注的对象，所有通过 add_meta_box() 添加的元数据框信息都会存储在这个数组里。

然后，它调用 convert_to_screen() 函数将 $screen 参数转换为 WP_Screen 对象。这样做是为了确保我们传入的 $screen 参数可以被正确处理，无论是文章类型字符串、文章类型数组还是 WP_Screen 对象。

最后，它使用 add_action() 函数注册了一个钩子 add_meta_boxes。这个钩子会在后台页面加载元数据框的时候被触发。add_action() 注册的回调函数实际上调用了 add_meta_box_cb() 函数，我们继续往下看。

2. add_meta_box_cb() 函数：幕后英雄

add_meta_box_cb() 函数才是真正将元数据框信息添加到 $wp_meta_boxes 数组中的幕后英雄。它的源码如下：

<?php
function add_meta_box_cb( $id, $title, $callback, $screen, $context, $priority, $callback_args = null ) {
    global $wp_meta_boxes;

    $screen = convert_to_screen( $screen );
    $page = $screen->id;

    if ( ! isset( $wp_meta_boxes ) ) {
        $wp_meta_boxes = array();
    }

    if ( ! isset( $wp_meta_boxes[ $page ] ) ) {
        $wp_meta_boxes[ $page ] = array();
    }

    if ( ! isset( $wp_meta_boxes[ $page ][ $context ] ) ) {
        $wp_meta_boxes[ $page ][ $context ] = array();
    }

    if ( ! isset( $wp_meta_boxes[ $page ][ $context ][ $priority ] ) ) {
        $wp_meta_boxes[ $page ][ $context ][ $priority ] = array();
    }

    $wp_meta_boxes[ $page ][ $context ][ $priority ][ $id ] = array(
        'id'            => $id,
        'title'         => $title,
        'callback'      => $callback,
        'args'          => $callback_args,
    );
}
?>

这个函数做了以下几件事：

• 获取全局变量 $wp_meta_boxes: 再次声明全局变量 $wp_meta_boxes，确保可以访问到它。
• 获取页面ID: 从 $screen 对象中获取当前页面的ID，也就是文章类型。
• 初始化数组: 检查 $wp_meta_boxes 数组是否已经存在，如果不存在，则初始化它。然后，依次检查 $wp_meta_boxes[$page]、$wp_meta_boxes[$page][$context] 和 $wp_meta_boxes[$page][$context][$priority] 是否存在，如果不存在，则初始化它们。
• 存储元数据框信息: 将元数据框的信息存储到 $wp_meta_boxes[$page][$context][$priority][$id] 数组中。这个数组的结构非常重要，我们稍后会详细分析。

四、$wp_meta_boxes 数组结构：元数据框的“家”

$wp_meta_boxes 数组的结构是理解 add_meta_box() 函数工作原理的关键。它的结构如下：

$wp_meta_boxes = array(
    'page_id' => array( // 页面ID，例如 'post', 'page', 'my_custom_post_type'
        'context' => array( // 上下文，例如 'normal', 'advanced', 'side'
            'priority' => array( // 优先级，例如 'high', 'core', 'default', 'low'
                'meta_box_id' => array( // 元数据框ID
                    'id'       => 'meta_box_id', // 元数据框ID
                    'title'    => 'Meta Box Title', // 元数据框标题
                    'callback' => 'meta_box_callback_function', // 回调函数
                    'args'     => array( // 传递给回调函数的参数
                        // ...
                    ),
                ),
            ),
        ),
    ),
);

这个数组是一个多维数组，每一层都代表着不同的维度：

• 第一层：页面ID (Page ID)：指的是元数据框显示在哪个页面上，例如文章编辑页面（post）、页面编辑页面（page）或者自定义文章类型的编辑页面。
• 第二层：上下文 (Context)：指的是元数据框在页面上的位置，例如内容区域（normal）、内容区域下方（advanced）或者侧边栏（side）。
• 第三层：优先级 (Priority)：指的是元数据框在同一位置的显示顺序，例如高优先级（high）、核心优先级（core）、默认优先级（default）或者低优先级（low）。
• 第四层：元数据框ID (Meta Box ID)：指的是元数据框的唯一标识符。
• 第五层：元数据框信息 (Meta Box Information)：包含了元数据框的详细信息，例如ID、标题、回调函数和传递给回调函数的参数。

五、实际应用：举个栗子，加深理解

光说不练假把式，咱们来写一个简单的例子，演示如何使用 add_meta_box() 函数添加自定义元数据框。

首先，在你的主题的 functions.php 文件或者自定义插件中添加以下代码：

<?php
add_action( 'add_meta_boxes', 'my_custom_meta_box' );

function my_custom_meta_box() {
    add_meta_box(
        'my_meta_box_id', // ID
        '我的自定义元数据框', // 标题
        'my_meta_box_callback', // 回调函数
        'post', // 页面，这里是文章
        'normal', // 上下文，内容区域
        'high' // 优先级，高
    );
}

function my_meta_box_callback( $post ) {
    // 使用 get_post_meta 获取已保存的数据
    $author_name = get_post_meta( $post->ID, '_author_name', true );

    // 输出表单字段
    ?>
    <label for="author_name">作者署名：</label>
    <input type="text" id="author_name" name="author_name" value="<?php echo esc_attr( $author_name ); ?>" size="25" />
    <p class="description">请输入作者署名。</p>
    <?php
}

add_action( 'save_post', 'my_save_meta_box_data' );

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

    // 检查是否存在 nonce (安全措施，防止 CSRF 攻击)
    if ( ! isset( $_POST['author_name'] ) ) {
        return;
    }

    // 清理数据
    $author_name = sanitize_text_field( $_POST['author_name'] );

    // 保存数据
    update_post_meta( $post_id, '_author_name', $author_name );
}
?>

这段代码做了以下几件事：

• 注册 add_meta_boxes 钩子: 通过 add_action() 函数注册 add_meta_boxes 钩子，并在钩子触发时调用 my_custom_meta_box() 函数。
• 添加元数据框: 在 my_custom_meta_box() 函数中使用 add_meta_box() 函数添加一个自定义元数据框。
• 定义回调函数: 定义 my_meta_box_callback() 函数，用于渲染元数据框的内容。这个函数输出一个文本输入框，用于输入作者署名。
• 保存元数据: 注册 save_post 钩子，并在文章保存时调用 my_save_meta_box_data() 函数。这个函数负责保存用户输入的数据。

现在，当你编辑一篇 WordPress 文章时，你应该可以看到一个标题为“我的自定义元数据框”的方框，里面有一个文本输入框，可以用来输入作者署名。

六、总结：拨开云雾，见月明

通过今天的讲解，我们深入剖析了 add_meta_box() 函数的源码，了解了它是如何将自定义元数据框添加到全局数组 $wp_meta_boxes 中的。我们还通过一个实际的例子，演示了如何使用 add_meta_box() 函数添加自定义元数据框，并保存用户输入的数据。

希望通过今天的讲解，大家能够对 add_meta_box() 函数有更深入的理解，并在实际开发中灵活运用它，打造出更强大的 WordPress 站点。

好了，今天的讲座就到这里，谢谢大家！如果有什么问题，欢迎随时提问。下次再见！