探讨 `add_meta_box()` 函数的源码，它是如何在文章编辑页添加自定义元数据框的？

各位Coder们，晚上好！我是老码农，今天咱们聊聊WordPress里一个非常实用，但又容易被忽视的函数：add_meta_box()。 它的作用可大了，能够让我们在文章编辑页面，像变魔术一样，添加自定义的元数据框，方便用户输入各种额外信息。

今天，咱们就一起扒开它的源码，看看这魔法是怎么实现的。准备好了吗？ Let’s dive in!

1. 什么是元数据框（Meta Box）？

首先，咱们得搞清楚元数据框是个啥玩意儿。你可以把它想象成文章编辑页面里的一块小区域，用来填写一些额外的信息，这些信息不是文章正文，但又和文章密切相关。比如，电影评论文章，你可以用元数据框来填写电影评分、导演、主演等等。

2. add_meta_box() 函数的基本用法

在开始深入源码之前，先简单回顾一下add_meta_box()的基本用法，这样对理解源码更有帮助。

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

参数说明：

• $id: 元数据框的唯一ID，别和别人重名了。
• $title: 元数据框的标题，显示在框框的顶部。
• $callback: 一个回调函数，用来生成元数据框的内容。
• $screen: 在哪些文章类型或页面上显示这个元数据框，可以是文章类型名（比如'post'、'page'），也可以是屏幕对象。
• $context: 元数据框显示的位置，有'normal'（正文下方）、'advanced'（高级）、'side'（侧边栏）等等。
• $priority: 元数据框的优先级，决定了它在相同$context下的显示顺序，有'high'、'core'、'default'、'low'。
• $callback_args: 传递给回调函数的额外参数。

3. 开始源码之旅：add_meta_box()的实现

add_meta_box() 函数位于 wp-admin/includes/meta-boxes.php 文件中。 让我们来揭开它的真面目。

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

    $screen = get_current_screen();
    if ( is_string( $screen ) ) {
        $screen = convert_to_screen( $screen );
    } elseif ( is_null( $screen ) ) {
        $screen = get_current_screen();
    }

    if ( ! is_scalar( $id ) ) {
        _doing_it_wrong( __FUNCTION__, __( 'Meta box ID must be a string.' ), '3.0' );
        return;
    }

    if ( isset( $wp_meta_boxes[ $screen->id ][ $context ][ $priority ][ $id ] ) ) {
        return;
    }

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

代码分析：

1. 全局变量 $wp_meta_boxes: 这个全局变量是关键，它是一个多维数组，用来存储所有注册的元数据框的信息。它的结构大致如下：

   $wp_meta_boxes[
       'screen_id' => [  // 屏幕ID，比如 'post'、'page'
           'context' => [   // 上下文，比如 'normal'、'advanced'、'side'
               'priority' => [ // 优先级，比如 'high'、'default'、'low'
                   'meta_box_id' => [ // 元数据框ID
                       'id' => 'meta_box_id',
                       'title' => 'Meta Box Title',
                       'callback' => 'callback_function',
                       'args' => [],
                   ],
               ],
           ],
       ],
   ];

2. 获取当前屏幕对象: get_current_screen() 函数用来获取当前屏幕的对象，比如文章编辑页面、页面编辑页面等等。如果 $screen 参数是字符串，就用 convert_to_screen() 函数把它转换成屏幕对象。

3. 参数验证: 代码会检查 $id 是否是字符串，如果不是，会抛出一个 _doing_it_wrong() 错误提示。

4. 检查是否已存在: 代码会检查是否已经存在相同 ID 的元数据框，如果存在，就直接返回，避免重复注册。

5. 存储元数据框信息: 最核心的部分来了！代码将元数据框的 ID、标题、回调函数、参数等信息存储到全局变量 $wp_meta_boxes 中。 注意，这里仅仅是存储信息，并没有真正渲染元数据框。

4. 元数据框的渲染：do_meta_boxes() 和 meta_box_callback()

光有注册还不够，还得把元数据框显示出来才行。 这就涉及到 do_meta_boxes() 函数和 meta_box_callback() 函数。

• do_meta_boxes(): 这个函数负责在文章编辑页面上输出所有注册的元数据框。它通常在 edit_form_after_title 钩子（在文章标题之后）或 edit_form_advanced 钩子（在高级编辑区域）中被调用。

• meta_box_callback(): 这个函数是一个通用的回调函数，它会调用我们注册时提供的 $callback 函数，来生成元数据框的内容。

下面是 do_meta_boxes() 函数的简化版代码（为了方便理解，省略了一些错误处理和兼容性代码）：

function do_meta_boxes( $screen, $context, $object ) {
    global $wp_meta_boxes;

    if ( empty( $wp_meta_boxes[ $screen ][ $context ] ) ) {
        return false;
    }

    $sorted_meta_boxes = $wp_meta_boxes[ $screen ][ $context ];
    uksort( $sorted_meta_boxes, 'sort_order_callback' );

    echo '<div id="' . esc_attr( $context ) . '-sortables" class="meta-box-sortables">';

    foreach ( $sorted_meta_boxes as $priority => $meta_boxes ) {
        foreach ( (array) $meta_boxes as $id => $meta_box ) {
            echo '<div id="' . esc_attr( $id ) . '" class="postbox">';
            echo '<button type="button" class="handlediv" aria-expanded="true">';
            echo '<span class="screen-reader-text">切换面板显示</span>';
            echo '</button>';
            echo '<h2 class="hndle ui-sortable-handle"><span>' . esc_html( $meta_box['title'] ) . '</span></h2>';
            echo '<div class="inside">';
            call_user_func( $meta_box['callback'], $object, $meta_box['args'] ); // 调用回调函数
            echo '</div>';
            echo '</div>';
        }
    }

    echo '</div>';

    return true;
}

代码分析：

1. 获取元数据框信息: 首先，根据 $screen 和 $context 参数，从全局变量 $wp_meta_boxes 中获取对应的元数据框信息。

2. 排序: 使用 uksort() 函数对元数据框按照优先级进行排序。

3. 循环输出: 循环遍历排序后的元数据框，为每个元数据框生成 HTML 结构，包括标题、展开/折叠按钮等等。

4. 调用回调函数: 最关键的一步！ 使用 call_user_func() 函数调用注册时提供的 $callback 函数，并将当前文章对象 $object 和 $callback_args 作为参数传递给回调函数。

5. meta_box_callback(): 实际上, 我们自己定义的回调函数会被 call_user_func() 直接调用。 但是 WordPress 提供了一个默认的 meta_box_callback() 函数， 通常情况下我们不会直接使用它。 但是了解一下这个函数有助于我们理解 WordPress 元数据框的机制。

5. 一个完整的例子

为了更好地理解，咱们来看一个完整的例子。 假设我们要为文章添加一个“作者评分”的元数据框。

<?php
/**
 * 添加元数据框
 */
function add_author_rating_meta_box() {
    add_meta_box(
        'author_rating',          // ID
        '作者评分',             // 标题
        'author_rating_callback', // 回调函数
        'post',                   // 文章类型
        'side',                   // 上下文
        'high'                    // 优先级
    );
}
add_action( 'add_meta_boxes', 'add_author_rating_meta_box' );

/**
 * 元数据框的回调函数
 *
 * @param WP_Post $post 当前文章对象
 */
function author_rating_callback( $post ) {
    // 添加 nonce 字段，用于安全验证
    wp_nonce_field( 'author_rating_nonce', 'author_rating_nonce' );

    // 获取已保存的评分
    $rating = get_post_meta( $post->ID, '_author_rating', true );
    if ( empty( $rating ) ) {
        $rating = 0;
    }

    // 输出评分输入框
    echo '<label for="author_rating_field">评分 (1-5):</label>';
    echo '<input type="number" id="author_rating_field" name="author_rating_field" min="1" max="5" value="' . esc_attr( $rating ) . '" />';
}

/**
 * 保存元数据
 *
 * @param int $post_id 当前文章ID
 */
function save_author_rating( $post_id ) {
    // 检查是否提交了数据
    if ( ! isset( $_POST['author_rating_field'] ) ) {
        return;
    }

    // 验证 nonce
    if ( ! isset( $_POST['author_rating_nonce'] ) || ! wp_verify_nonce( $_POST['author_rating_nonce'], 'author_rating_nonce' ) ) {
        return;
    }

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

    // 清理和保存数据
    $rating = sanitize_text_field( $_POST['author_rating_field'] );
    update_post_meta( $post_id, '_author_rating', $rating );
}
add_action( 'save_post', 'save_author_rating' );

代码解释：

1. add_author_rating_meta_box() 函数: 这个函数使用 add_meta_box() 函数注册了一个名为 author_rating 的元数据框，指定了标题、回调函数、文章类型、上下文和优先级。 它挂载到 add_meta_boxes 这个 action 上， 当 WordPress 开始渲染后台编辑页面的时候，会触发这个 action。

2. author_rating_callback() 函数: 这个函数是元数据框的回调函数，负责生成元数据框的内容。它首先添加了一个 nonce 字段，用于安全验证。然后，它获取已保存的评分，并输出一个评分输入框。

3. save_author_rating() 函数: 这个函数负责保存元数据。它首先检查是否提交了数据，验证 nonce，检查用户权限，然后清理和保存数据。 它挂载到 save_post 这个 action 上， 当 WordPress 保存文章的时候，会触发这个 action。

6. 安全性考虑

在使用元数据框时，安全性非常重要。 一定要做好以下几点：

• Nonce 验证: 使用 wp_nonce_field() 函数生成 nonce 字段，并在保存数据时使用 wp_verify_nonce() 函数进行验证，防止跨站请求伪造（CSRF）攻击。
• 用户权限检查: 使用 current_user_can() 函数检查用户是否具有编辑文章的权限，防止未经授权的用户修改元数据。
• 数据清理: 使用 sanitize_text_field() 等函数对用户输入的数据进行清理，防止 XSS 攻击。

7. get_current_screen() 的深入理解

get_current_screen() 函数在 add_meta_box() 中扮演着重要的角色，因为它决定了元数据框将出现在哪个页面。 让我们更深入地了解一下这个函数。

get_current_screen() 函数的源码位于 wp-admin/includes/screen.php 文件中。 它的主要作用是获取当前的屏幕对象，这个对象包含了当前页面的各种信息，比如 ID、base、parent_base、parent_file等等。

function get_current_screen() {
    global $current_screen, $hook_suffix;

    if ( ! is_a( $current_screen, 'WP_Screen' ) ) {
        set_current_screen();
    }

    return $current_screen;
}

代码分析：

1. 全局变量 $current_screen: 这个全局变量存储了当前的屏幕对象。

2. set_current_screen() 函数: 如果 $current_screen 对象不存在，就调用 set_current_screen() 函数来创建它。

set_current_screen() 函数会根据当前的 URL 和其他信息，判断当前页面的类型，并创建一个对应的 WP_Screen 对象。 比如，如果当前页面是文章编辑页面，它就会创建一个 ID 为 post 的 WP_Screen 对象。

在 add_meta_box() 函数中，get_current_screen() 函数获取到的屏幕对象，被用来确定元数据框应该显示在哪个页面上。

8. $context 和 $priority 的作用

$context 和 $priority 参数决定了元数据框在页面上的显示位置和顺序。

• $context: 决定了元数据框显示在页面的哪个区域，常见的取值有：

  • 'normal': 显示在正文编辑器的下方。
  • 'advanced': 也显示在正文编辑器的下方，但是通常用于更高级的设置。
  • 'side': 显示在侧边栏。

• $priority: 决定了在同一个 $context 下，元数据框的显示顺序，常见的取值有：

  • 'high': 优先级最高，显示在最上面。
  • 'core': 核心元数据框，通常由 WordPress 核心功能使用。
  • 'default': 默认优先级。
  • 'low': 优先级最低，显示在最下面。

9. 总结

add_meta_box() 函数是 WordPress 中一个非常强大的工具，可以让我们轻松地为文章编辑页面添加自定义的元数据框。 理解它的源码，可以帮助我们更好地使用它，并根据自己的需求进行扩展。

咱们今天从 add_meta_box() 的基本用法入手，深入分析了它的源码，了解了元数据框的注册和渲染过程，以及安全性考虑。 希望今天的讲解能帮助大家更好地掌握这个函数，在 WordPress 开发中更加游刃有余。

记住，熟练掌握这些底层机制，才能在面对复杂需求时，更加得心应手，写出高质量的代码！

今天的分享就到这里，感谢大家的收听！ 祝大家编码愉快！