发布于 由admin

详解 WordPress `do_meta_boxes()` 函数源码：它如何遍历 `$wp_meta_boxes` 数组并渲染元数据框。

WordPress do_meta_boxes() 函数源码剖析：一场元数据框的盛大演出

各位观众，各位朋友，大家好！我是今天的讲师，江湖人称“代码老中医”。今天咱们不聊养生，聊聊WordPress后台里那些长得奇形怪状的元数据框，以及它们背后的大Boss——do_meta_boxes() 函数。

这do_meta_boxes()可不是个简单的函数，它就像一个经验丰富的舞台总监，负责安排各个元数据框演员登台表演。它遍历那个神秘的 $wp_meta_boxes 数组，然后像变魔术一样，把那些原本只是数据的元数据框，变成活生生的HTML呈现在你的眼前。

准备好一起深入源码，看看这场元数据框的盛大演出是如何进行的吗？Let’s go！

1. 舞台搭建：$wp_meta_boxes 数组的秘密

在do_meta_boxes()开始工作之前，我们需要先了解一下它要表演的舞台——$wp_meta_boxes 数组。这个数组就像一个剧本，记录了所有元数据框的信息。

这个数组是一个多维数组，它的结构是这样的：

$wp_meta_boxes = array(
    'screen_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',
                    'title' => '元数据框标题',
                    'callback' => 'callback_function', // 回调函数，负责渲染元数据框内容
                    'args' => array(), // 传递给回调函数的参数
                ),
            ),
        ),
    ),
);

是不是有点眼花缭乱？没关系，咱们把它拆开来看：

  • screen_id: 这个就像剧院的名字，告诉你这个元数据框要在哪个屏幕上显示。比如 'post' 就是文章编辑页面，'page' 就是页面编辑页面。
  • context: 这个就像舞台的区域，告诉你这个元数据框要在页面的哪个位置显示。常用的有 'normal' (主体区域)、'advanced' (高级区域) 和 'side' (侧边栏)。
  • priority: 这个就像演员的出场顺序，告诉你这个元数据框的显示优先级。'high' 优先级最高，会最先显示。
  • meta_box_id: 这个就像演员的名字，每个元数据框都有一个唯一的ID。
  • id: 元数据框ID，和外层的key相同，属于冗余信息。
  • title: 元数据框的标题，显示在元数据框的顶部。
  • callback: 这个是重头戏！它是一个回调函数，负责渲染元数据框的内容。这个函数才是真正干活的。
  • args: 传递给回调函数的参数，可以是一些额外的数据。

举个例子，假设我们要添加一个显示作者信息的元数据框到文章编辑页面的侧边栏，可以这样定义：

function my_author_meta_box() {
    add_meta_box(
        'my_author_meta_box_id', // ID
        '作者信息', // 标题
        'my_author_meta_box_callback', // 回调函数
        'post', // 屏幕ID
        'side', // 上下文
        'high' // 优先级
    );
}
add_action( 'add_meta_boxes', 'my_author_meta_box' );

function my_author_meta_box_callback( $post ) {
    // 获取作者信息
    $author_id = $post->post_author;
    $author = get_userdata( $author_id );

    // 显示作者信息
    echo '<p>作者姓名：' . esc_html( $author->display_name ) . '</p>';
    echo '<p>作者邮箱：' . esc_html( $author->user_email ) . '</p>';
}

这段代码会将一个标题为“作者信息”的元数据框添加到文章编辑页面的侧边栏，并显示作者的姓名和邮箱。

2. 导演登场：do_meta_boxes() 函数的源码解析

现在，让我们来看看do_meta_boxes() 函数的源码，看看它是如何遍历 $wp_meta_boxes 数组，并渲染元数据框的。

do_meta_boxes() 函数位于 wp-admin/includes/template.php 文件中。为了方便理解，我对源码进行了简化和注释：

/**
 * Display add meta boxes.
 *
 * @since 2.5.0
 *
 * @global array $wp_meta_boxes
 *
 * @param string|WP_Screen $screen   Screen identifier.
 * @param string          $context  The context where the boxes should display.
 * @param mixed           $object   The object to pass as argument to display the box.
 */
function do_meta_boxes( $screen, $context, $object ) {
    global $wp_meta_boxes;

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

    $page = $screen->id;

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

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

    $priorities = array( 'high', 'core', 'default', 'low' );

    foreach ( $priorities as $priority ) {
        if ( isset( $wp_meta_boxes[ $page ][ $context ][ $priority ] ) ) {
            foreach ( (array) $wp_meta_boxes[ $page ][ $context ][ $priority ] as $meta_box ) {
                if ( is_callable( $meta_box['callback'] ) ) {
                    echo '<div id="' . esc_attr( $meta_box['id'] ) . '" class="postbox">';
                    echo '<div class="postbox-header">';
                    echo '<h2 class="hndle">' . esc_html( $meta_box['title'] ) . '</h2>';
                    echo '</div>';
                    echo '<div class="inside">';
                    call_user_func( $meta_box['callback'], $object, $meta_box['args'] );
                    echo '</div>';
                    echo '</div>';
                }
            }
        }
    }
}

这段代码的主要流程是这样的：

  1. 准备工作:

    • 接收三个参数：$screen (屏幕ID)、$context (上下文) 和 $object (传递给回调函数的对象)。
    • 将 $screen 转换为 WP_Screen 对象。
    • 获取屏幕ID $page。
    • 检查 $wp_meta_boxes 数组中是否存在指定屏幕ID和上下文的元数据框，如果不存在则直接返回。

  2. 遍历优先级:

    • 定义一个优先级数组 $priorities，按照 'high', 'core', 'default', 'low' 的顺序排列。
    • 遍历优先级数组，依次处理每个优先级的元数据框。

  3. 遍历元数据框:

    • 对于每个优先级，遍历该优先级下的所有元数据框。
    • 检查元数据框的回调函数是否可调用。

  4. 渲染元数据框:

    • 如果回调函数可调用，则创建一个 HTML 结构来包裹元数据框的内容。这个结构包括一个 div 元素，包含 id 和 class 属性，用于标识和样式化元数据框。
    • 调用回调函数 call_user_func()，并将 $object 和 $meta_box['args'] 作为参数传递给回调函数。回调函数负责生成元数据框的实际内容。

3. 细节分析：call_user_func() 的妙用

在do_meta_boxes() 函数中，call_user_func() 函数扮演着非常重要的角色。它负责调用元数据框的回调函数，并将数据传递给它。

call_user_func() 函数是 PHP 的一个内置函数，它可以动态地调用函数。它的第一个参数是要调用的函数名，后面的参数是要传递给函数的参数。

在do_meta_boxes() 函数中，call_user_func() 函数的用法是这样的：

call_user_func( $meta_box['callback'], $object, $meta_box['args'] );
  • $meta_box['callback'] 是要调用的回调函数名。
  • $object 是要传递给回调函数的第一个参数，通常是当前编辑的文章或页面的对象。
  • $meta_box['args'] 是要传递给回调函数的第二个参数，可以是一些额外的数据。

通过使用 call_user_func() 函数，do_meta_boxes() 函数可以灵活地调用不同的回调函数，从而渲染出各种各样的元数据框。

4. 实战演练：自定义元数据框的显示

现在，让我们通过一个实际的例子，来演示如何使用 do_meta_boxes() 函数来控制自定义元数据框的显示。

假设我们已经定义了一个名为 my_custom_meta_box 的元数据框，并将其添加到文章编辑页面的侧边栏。现在，我们想要根据用户的角色，来决定是否显示这个元数据框。

我们可以通过以下步骤来实现：

  1. 定义一个过滤器函数:
function my_custom_meta_box_filter( $wp_meta_boxes ) {
    $screen = get_current_screen();

    if ( $screen && 'post' === $screen->id ) {
        $current_user = wp_get_current_user();

        // 检查用户是否具有特定角色
        if ( ! in_array( 'administrator', (array) $current_user->roles ) ) {
            // 如果用户不是管理员，则移除元数据框
            unset( $wp_meta_boxes['post']['side']['core']['my_custom_meta_box_id'] );
        }
    }

    return $wp_meta_boxes;
}
add_filter( 'add_meta_boxes', 'my_custom_meta_box_filter', 20 );

这段代码会检查当前用户是否是管理员。如果用户不是管理员，则从 $wp_meta_boxes 数组中移除 my_custom_meta_box 元数据框。

  1. 添加元数据框:
function my_add_custom_meta_box() {
    add_meta_box(
        'my_custom_meta_box_id',
        '自定义元数据框',
        'my_custom_meta_box_callback',
        'post',
        'side',
        'core'
    );
}
add_action( 'add_meta_boxes', 'my_add_custom_meta_box' );

function my_custom_meta_box_callback( $post ) {
    echo '<p>这是一个自定义元数据框。</p>';
}

这段代码会添加一个名为“自定义元数据框”的元数据框到文章编辑页面的侧边栏。

通过以上两步，我们就可以实现根据用户的角色来控制自定义元数据框的显示。只有管理员才能看到这个元数据框，其他用户则看不到。

5. 注意事项：esc_attr() 和 esc_html() 的重要性

在do_meta_boxes() 函数的源码中，我们可以看到 esc_attr() 和 esc_html() 函数被广泛使用。这两个函数的作用是对输出的字符串进行转义，以防止 XSS 攻击。

  • esc_attr(): 用于转义 HTML 属性。
  • esc_html(): 用于转义 HTML 内容。

在渲染元数据框时，一定要对所有输出的字符串进行转义，以确保安全性。

6. 总结：do_meta_boxes() 函数的核心价值

do_meta_boxes() 函数是 WordPress 后台的核心函数之一，它负责遍历 $wp_meta_boxes 数组，并渲染元数据框。通过理解 do_meta_boxes() 函数的源码，我们可以更好地控制元数据框的显示，并根据实际需求进行定制。

do_meta_boxes() 函数的核心价值在于：

  • 灵活性: 可以灵活地添加和移除元数据框。
  • 可定制性: 可以根据用户的角色、文章类型等条件来控制元数据框的显示。
  • 安全性: 通过使用 esc_attr() 和 esc_html() 函数，可以防止 XSS 攻击。

希望通过今天的讲解，大家对 do_meta_boxes() 函数有了更深入的了解。掌握了这个函数，你就可以像一个真正的舞台总监一样，自由地安排 WordPress 后台的元数据框演出！

表格总结

函数/变量 作用
$wp_meta_boxes 存储所有元数据框信息的数组，是 do_meta_boxes() 函数遍历的核心数据结构。
do_meta_boxes() 遍历 $wp_meta_boxes 数组，根据指定的屏幕ID、上下文和优先级，渲染元数据框。
add_meta_box() 用于添加元数据框到 $wp_meta_boxes 数组中。
call_user_func() 动态调用元数据框的回调函数，并将数据传递给它。
esc_attr() 转义 HTML 属性，防止 XSS 攻击。
esc_html() 转义 HTML 内容，防止 XSS 攻击。
Screen ID 定义元数据框显示在哪个后台页面，例如 post, page, 或自定义文章类型。
Context 定义元数据框在页面的哪个区域显示，例如 normal, advanced, side。
Priority 定义元数据框在同一上下文中的显示顺序，例如 high, core, default, low。
Callback Function 元数据框的核心渲染函数，负责生成元数据框的 HTML 内容。
Args 传递给回调函数的参数，可以包含文章ID或其他自定义数据。
add_action('add_meta_boxes', ...) 一个钩子，允许开发者在 WordPress 添加元数据框的流程中执行自定义代码。通常用于调用 add_meta_box() 函数。
add_filter('add_meta_boxes', ...) 一个钩子，允许开发者修改 $wp_meta_boxes 数组。通常用于根据特定条件（例如用户角色）来隐藏或修改元数据框。

好了，今天的讲座就到这里。希望大家有所收获，下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注