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

嘿，大家好！今天咱们来聊聊 WordPress 里一个挺实用的函数：add_meta_box()，它能让你在后台页面（比如文章编辑页、页面编辑页）添加自定义的元数据框，也就是咱们常说的“自定义字段”。这玩意儿能扩展 WordPress 的功能，让你可以存储和管理更多类型的数据。

咱们的目标是深入源码，看看 add_meta_box() 到底是怎么工作的，以及如何灵活地运用它。准备好了吗？ Let’s dive in!

1. 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: 元数据框的唯一标识符，别跟其他的重复了，不然会出问题。
$title: 元数据框的标题，显示在后台页面上。
$callback: 一个回调函数，负责渲染元数据框的内容（比如表单字段）。
$screen: 指定在哪个页面显示元数据框。可以是文章类型（’post’, ‘page’），也可以是自定义文章类型，甚至可以是 WP_Screen 对象。默认是当前页面。
$context: 元数据框显示的位置，可选值有 ‘normal’ (内容区域), ‘advanced’ (内容区域下方), 和 ‘side’ (侧边栏)。
$priority: 元数据框在同一上下文中显示的优先级，可选值有 ‘high’, ‘core’, ‘default’, ‘low’。
$callback_args: 传递给回调函数的额外参数。

一个简单的例子：

add_action( 'add_meta_boxes', 'my_custom_meta_box' );

function my_custom_meta_box() {
    add_meta_box(
        'my_meta_box_id',
        'My Custom Title',
        'my_meta_box_callback',
        'post',
        'normal',
        'default'
    );
}

function my_meta_box_callback( $post ) {
    // 使用 $post 对象获取当前文章的数据
    $value = get_post_meta( $post->ID, '_my_meta_value_key', true );

    echo '<label for="my_meta_field">My Custom Field:</label>';
    echo '<input type="text" id="my_meta_field" name="my_meta_field" value="' . esc_attr( $value ) . '" size="25" />';

    // 添加安全字段，防止跨站请求伪造 (CSRF)
    wp_nonce_field( 'my_meta_box_nonce', 'my_meta_box_nonce' );
}

add_action( 'save_post', 'my_meta_box_save' );

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

    // 如果是自动保存，忽略
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
        return;
    }

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

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

这个例子做了什么？

用 add_action 挂载 my_custom_meta_box 函数到 add_meta_boxes 动作钩子上。这个钩子会在后台页面加载时触发，允许你添加元数据框。
my_custom_meta_box 函数调用 add_meta_box 来注册一个新的元数据框。
my_meta_box_callback 函数负责渲染元数据框的内容，这里简单地显示一个文本输入框。注意这里使用了 get_post_meta 获取之前保存的值。另外，生成了一个nonce，用于安全验证。
my_meta_box_save 函数在文章保存时被触发，负责验证用户权限、清理数据，并将数据保存到数据库中。使用了wp_verify_nonce验证nonce，如果失败，则不保存数据。

2. 源码剖析：add_meta_box() 内部的秘密

现在，让我们深入 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_object( $screen ) ) {
        return;
    }

    $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,
    );

    return true;
}

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

获取当前页面： $screen = get_current_screen(); 这行代码获取当前显示的 WP_Screen 对象，代表当前后台页面。
确保 $wp_meta_boxes 存在： if ( ! isset( $wp_meta_boxes ) ) { ... } 这个判断确保全局变量 $wp_meta_boxes 存在。 $wp_meta_boxes 是一个多维数组，用于存储所有已注册的元数据框的信息。
组织元数据框信息： 代码的核心部分是将元数据框的信息存储到 $wp_meta_boxes 数组中。这个数组的结构是：
```
$wp_meta_boxes[ $page ][ $context ][ $priority ][ $id ] = array(
    'id'       => $id,
    'title'    => $title,
    'callback' => $callback,
    'args'     => $callback_args,
);
```
- $page: 当前页面的 ID (比如 ‘post’, ‘page’)
- $context: 元数据框的位置 (‘normal’, ‘advanced’, ‘side’)
- $priority: 元数据框的优先级 (‘high’, ‘core’, ‘default’, ‘low’)
- $id: 元数据框的唯一 ID
- 数组中的值包含了元数据框的标题、回调函数和参数。

简单来说，add_meta_box() 函数只是把你的元数据框信息存储到了一个全局数组 $wp_meta_boxes 中。 它并没有实际渲染元数据框。渲染的任务是由其他函数完成的。

3. 渲染元数据框：do_meta_boxes() 的舞台

那么，到底是谁负责渲染元数据框呢？答案是 do_meta_boxes() 函数。这个函数会在后台页面加载时被调用，它会遍历 $wp_meta_boxes 数组，并调用相应的回调函数来渲染元数据框。

do_meta_boxes() 函数位于 wp-admin/includes/template.php 文件中。

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

    if ( is_string( $screen ) ) {
        $screen = convert_to_screen( $screen );
    }

    if ( ! is_object( $screen ) ) {
        return;
    }

    $page = $screen->id;

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

    $sorted_meta_boxes = array();

    foreach ( array( 'high', 'core', 'default', 'low' ) as $priority ) {
        if ( isset( $wp_meta_boxes[ $page ][ $context ][ $priority ] ) ) {
            $sorted_meta_boxes = array_merge( $sorted_meta_boxes, $wp_meta_boxes[ $page ][ $context ][ $priority ] );
        }
    }

    /**
     * Fires before meta boxes are rendered.
     *
     * @since 4.4.0
     *
     * @param WP_Screen $screen Screen object.
     * @param string    $context The context where the boxes are displayed.
     * @param mixed     $object  The object being displayed.
     */
    do_action( 'do_meta_boxes', $screen, $context, $object );

    foreach ( (array) $sorted_meta_boxes as $meta_box ) {
        if ( ! is_callable( $meta_box['callback'] ) ) {
            continue;
        }

        echo '<div id="' . esc_attr( $meta_box['id'] ) . '" class="postbox">';
        echo '<button type="button" class="handlediv" aria-expanded="true">';
        echo '<span class="screen-reader-text">Toggle panel: ' . esc_html( $meta_box['title'] ) . '</span>';
        echo '<span class="toggle-indicator" aria-hidden="true"></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>';
    }
}

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

获取页面 ID： $page = $screen->id; 获取当前页面的 ID。
检查元数据框是否存在： if ( empty( $wp_meta_boxes[ $page ][ $context ] ) ) { return; } 如果当前页面和上下文没有注册任何元数据框，则直接返回。
按优先级排序： 代码按照 ‘high’, ‘core’, ‘default’, ‘low’ 的顺序将元数据框排序。
触发 do_meta_boxes 动作钩子： do_action( 'do_meta_boxes', $screen, $context, $object ); 这个钩子允许你添加自定义的逻辑，在渲染元数据框之前执行。
遍历并渲染元数据框： 核心部分是 foreach ( (array) $sorted_meta_boxes as $meta_box ) { ... } 循环。它遍历排序后的元数据框，并执行以下操作：
- 检查回调函数是否可调用： if ( ! is_callable( $meta_box['callback'] ) ) { continue; } 确保回调函数存在且可调用。
- 输出 HTML 结构： 输出元数据框的基本 HTML 结构，包括标题、折叠按钮等。
- 调用回调函数： call_user_func( $meta_box['callback'], $object, $meta_box['args'] ); 这是关键的一步！ 调用 add_meta_box() 中指定的回调函数，并将当前对象（比如 $post 对象）和回调参数传递给它。回调函数负责渲染元数据框的具体内容。

总结一下：do_meta_boxes() 函数负责从 $wp_meta_boxes 数组中获取元数据框的信息，并调用相应的回调函数来渲染它们。

4. add_meta_boxes 动作钩子：添加元数据框的入口

你可能注意到了，在我们的例子中，我们使用 add_action( 'add_meta_boxes', 'my_custom_meta_box' ); 将 my_custom_meta_box 函数挂载到了 add_meta_boxes 动作钩子上。那么，add_meta_boxes 钩子到底是什么时候触发的呢？

这个钩子是在 edit_form_after_title 函数中触发的。 edit_form_after_title 函数位于 wp-admin/edit-form-advanced.php 文件中，它负责渲染文章编辑页面的表单。

<?php
/**
 * Fires at the end of the Post title form field.
 *
 * @since 1.1.0
 *
 * @param WP_Post $post Post object.
 */
do_action( 'edit_form_after_title', $post );

/**
 * Fires before the main content editor on the Edit Post screen.
 *
 * @since 1.1.0
 *
 * @param WP_Post $post Post object.
 */
do_action( 'edit_form_after_editor', $post );

?>
<div id="poststuff">
    <?php
    /**
     * Fires at the beginning of the Edit form page.
     *
     * @since 2.0.0
     *
     * @param string $post_type The post type of the Post being edited.
     *                          Empty string if new Post.
     * @param WP_Post $post Post object.
     */
    do_action( 'dbx_post_advanced', $post );
    /**
     * Fires after all meta boxes have been added.
     *
     * @since 3.0.0
     *
     * @param string $post_type The post type of the Post being edited.
     * @param WP_Post $post Post object.
     */
    do_action( 'add_meta_boxes', $post->post_type, $post );
    /**
     * Fires after the content editor box.
     *
     * @since 3.0.0
     *
     * @param string $post_type The post type of the Post being edited.
     * @param WP_Post $post Post object.
     */
    do_action( 'edit_form_after_content', $post );

    ?>

    <div id="postbox-container-1" class="postbox-container">
        <?php do_action('submitpage_box'); ?>
        <?php do_meta_boxes($current_screen, 'side', $post); ?>
    </div>

    <div id="postbox-container-2" class="postbox-container">
        <?php
        do_meta_boxes($current_screen, 'normal', $post);
        do_meta_boxes($current_screen, 'advanced', $post);
        ?>
    </div>

</div> <!-- #poststuff -->

可以看到，在 edit_form_after_title 之后， do_action( 'add_meta_boxes', $post->post_type, $post ); 被调用，触发了 add_meta_boxes 钩子。这就是为什么我们需要将 add_meta_box() 函数挂载到 add_meta_boxes 钩子上的原因。

然后，do_meta_boxes 函数被调用三次，分别渲染 ‘side’, ‘normal’, 和 ‘advanced’ 上下文的元数据框。

总结：add_meta_boxes 钩子是添加元数据框的入口。通过将你的函数挂载到这个钩子上，你可以使用 add_meta_box() 函数来注册你的元数据框。

5. 深入理解 $screen 参数：灵活控制元数据框的显示

add_meta_box() 函数的 $screen 参数允许你指定在哪些页面上显示元数据框。它可以是文章类型（’post’, ‘page’），也可以是自定义文章类型，甚至可以是 WP_Screen 对象。

文章类型字符串： 最简单的用法是传递一个文章类型字符串，比如 ‘post’ 或 ‘page’。

add_meta_box(
    'my_meta_box_id',
    'My Custom Title',
    'my_meta_box_callback',
    'post', // 只在文章编辑页显示
    'normal',
    'default'
);

自定义文章类型： 如果你的主题或插件注册了自定义文章类型，你可以将自定义文章类型的名称传递给 $screen 参数。

add_meta_box(
    'my_meta_box_id',
    'My Custom Title',
    'my_meta_box_callback',
    'product', // 只在 "product" 自定义文章类型编辑页显示
    'normal',
    'default'
);

WP_Screen 对象： WP_Screen 对象提供了更精细的控制。你可以使用 get_current_screen() 函数获取当前页面的 WP_Screen 对象，并将其传递给 $screen 参数。这允许你根据更复杂的条件来控制元数据框的显示。

add_action( 'add_meta_boxes', 'my_custom_meta_box' );

function my_custom_meta_box() {
    $screen = get_current_screen();

    // 只在文章编辑页，并且文章 ID 大于 100 时显示元数据框
    if ( $screen->id == 'post' && isset( $_GET['post'] ) && $_GET['post'] > 100 ) {
        add_meta_box(
            'my_meta_box_id',
            'My Custom Title',
            'my_meta_box_callback',
            $screen, // 传递 WP_Screen 对象
            'normal',
            'default'
        );
    }
}

使用 WP_Screen 对象，你可以访问页面的各种属性，比如 id (页面 ID), post_type (文章类型), taxonomy (分类法) 等，从而实现更灵活的控制。

6. $context 和 $priority 参数：控制元数据框的布局

$context 和 $priority 参数控制元数据框在页面上的布局。

$context： 指定元数据框显示的位置。

值描述

‘normal’ 内容区域，在编辑器下方

‘advanced’ 内容区域下方，在 ‘normal’ 的下方

‘side’ 侧边栏
$priority： 指定元数据框在同一上下文中显示的优先级。

值描述

‘high’ 优先级高，显示在顶部

‘core’ WordPress 核心元数据框，优先级较高

‘default’ 默认优先级

‘low’ 优先级低，显示在底部

值	描述
‘normal’	内容区域，在编辑器下方
‘advanced’	内容区域下方，在 ‘normal’ 的下方
‘side’	侧边栏

值	描述
‘high’	优先级高，显示在顶部
‘core’	WordPress 核心元数据框，优先级较高
‘default’	默认优先级
‘low’	优先级低，显示在底部

通过调整 $context 和 $priority 参数，你可以控制元数据框在页面上的显示顺序和位置。

7. 总结：add_meta_box() 的完整生命周期

让我们回顾一下 add_meta_box() 的完整生命周期：

注册元数据框： 使用 add_meta_box() 函数注册元数据框，并将元数据框的信息存储到全局数组 $wp_meta_boxes 中。通常，你会在 add_action( 'add_meta_boxes', 'my_custom_meta_box' ); 中调用 add_meta_box()。
触发 add_meta_boxes 钩子： edit_form_after_title 函数触发 add_meta_boxes 钩子。
渲染元数据框： do_meta_boxes() 函数从 $wp_meta_boxes 数组中获取元数据框的信息，并调用相应的回调函数来渲染它们。 edit_form_advanced.php 文件调用 do_meta_boxes 函数三次，分别渲染 ‘side’, ‘normal’, 和 ‘advanced’ 上下文的元数据框。
保存数据： 在文章保存时，验证用户权限、清理数据，并将数据保存到数据库中。通常，你会在 add_action( 'save_post', 'my_meta_box_save' ); 中处理数据保存。

8. 高级技巧：使用 callback_args 传递参数

add_meta_box() 函数的 $callback_args 参数允许你将额外的参数传递给回调函数。这在需要动态生成元数据框内容时非常有用。

add_action( 'add_meta_boxes', 'my_custom_meta_box' );

function my_custom_meta_box() {
    add_meta_box(
        'my_meta_box_id',
        'My Custom Title',
        'my_meta_box_callback',
        'post',
        'normal',
        'default',
        array(
            'field_id' => 'my_meta_field',
            'field_label' => 'My Custom Field:'
        )
    );
}

function my_meta_box_callback( $post, $args ) {
    $value = get_post_meta( $post->ID, '_my_meta_value_key', true );

    echo '<label for="' . esc_attr( $args['field_id'] ) . '">' . esc_html( $args['field_label'] ) . '</label>';
    echo '<input type="text" id="' . esc_attr( $args['field_id'] ) . '" name="' . esc_attr( $args['field_id'] ) . '" value="' . esc_attr( $value ) . '" size="25" />';

    wp_nonce_field( 'my_meta_box_nonce', 'my_meta_box_nonce' );
}

在这个例子中，我们使用 $callback_args 传递了 field_id 和 field_label 两个参数给 my_meta_box_callback 函数。在回调函数中，我们可以通过 $args 数组来访问这些参数。

9. 常见问题和注意事项

ID 冲突： 确保你的元数据框 ID 是唯一的，避免与其他插件或主题的元数据框 ID 冲突。
安全： 始终验证用户权限和清理用户输入，防止安全漏洞。使用 nonce 字段来防止 CSRF 攻击。
性能： 避免在回调函数中执行复杂的查询或计算，影响页面加载速度。
兼容性： 测试你的元数据框在不同的主题和插件环境下的兼容性。
数据验证： 在保存数据之前，始终验证数据的类型和格式，确保数据的完整性。

10. 总结

add_meta_box() 函数是 WordPress 中一个非常强大和灵活的工具，可以让你在后台页面添加自定义的元数据框，扩展 WordPress 的功能。通过深入理解 add_meta_box() 的源码和工作原理，你可以更好地利用它来构建更强大的 WordPress 插件和主题。希望今天的讲座能帮助你更好地理解和使用 add_meta_box() 函数。祝大家编程愉快！

发表回复 取消回复

发表回复取消回复