如何利用`WP_Screen`和`add_meta_box`定制后台编辑界面？

好的，现在开始我们的讲座。

讲座主题：利用 WP_Screen 和 add_meta_box 定制 WordPress 后台编辑界面

今天我们来深入探讨如何使用 WordPress 的 WP_Screen 类和 add_meta_box 函数来定制后台编辑界面。这两个工具是构建复杂、用户友好的 WordPress 后台体验的关键。

一、WP_Screen：了解你的上下文

WP_Screen 类提供了一种在 WordPress 后台上下文中识别当前屏幕的方法。它允许你根据当前页面的类型、ID 和其他属性来有条件地执行代码。

1.1 WP_Screen 的作用

• 识别当前屏幕: 确定用户当前正在查看哪个后台页面（例如，文章编辑页面、分类目录编辑页面、自定义设置页面等）。
• 有条件地加载资源: 根据当前屏幕加载特定的 CSS 样式表、JavaScript 脚本或执行其他操作。
• 控制界面元素: 根据当前屏幕显示或隐藏特定的界面元素，例如元框 (meta boxes)。

1.2 获取 WP_Screen 对象

在 WordPress 后台，你可以使用 get_current_screen() 函数来获取当前的 WP_Screen 对象。这个函数只能在 admin_enqueue_scripts 或更晚的 admin 钩子中使用，因为在此之前屏幕对象尚未完全初始化。

add_action( 'admin_enqueue_scripts', 'my_admin_scripts' );

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

    if ( $screen ) {
        // 现在你可以使用 $screen 对象
        // 例如： var_dump($screen);  // 输出屏幕对象的信息
    }
}

1.3 WP_Screen 对象的属性

WP_Screen 对象包含许多有用的属性，可以帮助你识别当前屏幕。以下是一些常用的属性：

属性	类型	描述
id	string	当前屏幕的 ID。这通常是 post 类型名称（例如，post，page，my_custom_post_type）或菜单项的 slug。
post_type	string	如果当前屏幕是文章编辑页面，则此属性包含 post 类型名称。否则，此属性可能为 null 或空字符串。
taxonomy	string	如果当前屏幕是分类目录或标签编辑页面，则此属性包含分类法名称。否则，此属性可能为 null 或空字符串。
base	string	屏幕的基本类型。例如，post (编辑文章), edit (文章列表), taxonomy (分类目录编辑), settings_page (设置页面) 等。
action	string	当前屏幕的操作。例如，add (添加新文章), edit (编辑现有文章)。
is_network	boolean	指示当前屏幕是否是网络管理屏幕（在 WordPress 多站点环境中）。
parent_base	string	指示当前屏幕的父级屏幕的基本类型。
parent_file	string	指示当前屏幕的父级菜单项的文件名。

1.4 使用 WP_Screen 的示例

以下是一些使用 WP_Screen 对象的示例：

• 仅在特定 post 类型的编辑页面上加载 CSS：

add_action( 'admin_enqueue_scripts', 'my_custom_post_type_css' );

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

    if ( $screen && $screen->post_type === 'my_custom_post_type' && $screen->base === 'post' ) {
        wp_enqueue_style( 'my-custom-post-type-style', plugin_dir_url( __FILE__ ) . 'css/my-custom-post-type.css' );
    }
}

• 仅在特定分类法的编辑页面上显示消息：

add_action( 'admin_notices', 'my_custom_taxonomy_notice' );

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

    if ( $screen && $screen->taxonomy === 'my_custom_taxonomy' && $screen->base === 'term' ) {
        echo '<div class="notice notice-info"><p>请注意：这是一个自定义分类法。</p></div>';
    }
}

• 检查是否在文章添加页面：

add_action( 'admin_enqueue_scripts', 'my_admin_scripts' );

function my_admin_scripts() {
    $screen = get_current_screen();
    if ( $screen && $screen->base == 'post' && $screen->action == 'add' ) {
        // 在文章添加页面执行的操作
        wp_enqueue_script( 'my-custom-script', plugin_dir_url( __FILE__ ) . 'js/my-custom-script.js', array( 'jquery' ), '1.0', true );
    }
}

二、add_meta_box：添加自定义元框

add_meta_box 函数允许你向 WordPress 后台编辑页面添加自定义元框。元框是位于编辑页面上的可拖动框，用于显示和编辑与文章、页面或自定义文章类型相关的元数据。

2.1 add_meta_box 的参数

add_meta_box 函数接受以下参数：

• $id (string, required): 元框的唯一 ID。
• $title (string, required): 元框的标题。
• $callback (callable, required): 用于显示元框内容的函数。
• $screen (string|array|WP_Screen, optional): 要显示元框的屏幕。可以是单个 post 类型名称、post 类型名称数组或 WP_Screen 对象。默认为当前屏幕。
• $context (string, optional): 元框在屏幕上的位置。可以是 'normal'（常规）、'advanced'（高级）或 'side'（侧边栏）。默认为 'advanced'。
• $priority (string, optional): 元框在上下文中的优先级。可以是 'high'（高）、'core'（核心）、'default'（默认）或 'low'（低）。默认为 'default'。
• $callback_args (array, optional): 传递给回调函数的参数数组。

2.2 add_meta_box 的使用示例

以下是一个添加自定义元框的示例，用于显示和编辑文章的自定义价格：

add_action( 'add_meta_boxes', 'my_add_price_meta_box' );

function my_add_price_meta_box() {
    add_meta_box(
        'my_price_meta_box',      // ID
        '商品价格',                // Title
        'my_price_meta_box_callback', // Callback
        'product',                // Screen (post type)
        'side',                   // Context
        'high'                    // Priority
    );
}

function my_price_meta_box_callback( $post ) {
    // 添加 nonce 字段以进行安全验证
    wp_nonce_field( 'my_price_meta_box', 'my_price_meta_box_nonce' );

    // 获取现有的价格值
    $price = get_post_meta( $post->ID, '_price', true );

    // 显示价格输入字段
    echo '<label for="my_price_field">价格：</label>';
    echo '<input type="text" id="my_price_field" name="my_price_field" value="' . esc_attr( $price ) . '" size="25" />';
}

add_action( 'save_post', 'my_save_price_meta_box_data' );

function my_save_price_meta_box_data( $post_id ) {
    // 检查用户是否具有保存文章的权限
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return;
    }

    // 检查 nonce 字段
    if ( ! isset( $_POST['my_price_meta_box_nonce'] ) || ! wp_verify_nonce( $_POST['my_price_meta_box_nonce'], 'my_price_meta_box' ) ) {
        return;
    }

    // 如果自动保存，则退出
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
        return;
    }

    // 保存价格数据
    if ( isset( $_POST['my_price_field'] ) ) {
        $price = sanitize_text_field( $_POST['my_price_field'] );
        update_post_meta( $post_id, '_price', $price );
    }
}

代码解释：

1. my_add_price_meta_box 函数:

   • 使用 add_meta_box 函数注册一个新的元框。
   • $id: my_price_meta_box – 元框的唯一 ID。
   • $title: 商品价格 – 元框的标题。
   • $callback: my_price_meta_box_callback – 用于显示元框内容的函数。
   • $screen: 'product' – 将元框添加到 product post 类型的编辑页面。
   • $context: 'side' – 将元框放置在侧边栏中。
   • $priority: 'high' – 在侧边栏中将元框放置在顶部。

2. my_price_meta_box_callback 函数:

   • 使用 wp_nonce_field 函数添加一个 nonce 字段，以防止跨站请求伪造 (CSRF) 攻击。
   • 使用 get_post_meta 函数检索现有的价格值。
   • 显示一个文本输入字段，允许用户输入价格。

3. my_save_price_meta_box_data 函数:

   • 使用 current_user_can 函数检查用户是否具有保存文章的权限。
   • 使用 wp_verify_nonce 函数验证 nonce 字段。
   • 使用 sanitize_text_field 函数清理用户输入。
   • 使用 update_post_meta 函数保存价格数据。

2.3 使用 WP_Screen 和 add_meta_box 的结合

将 WP_Screen 和 add_meta_box 结合使用，可以更精确地控制元框的显示位置和行为。

以下是一个示例，展示如何仅在特定 post 类型的 新建 编辑页面上显示元框：

add_action( 'add_meta_boxes', 'my_add_meta_boxes' );

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

    if ( $screen && $screen->post_type === 'my_custom_post_type' && $screen->base === 'post' && $screen->action === 'add' ) {
        add_meta_box(
            'my_custom_meta_box',
            '自定义元框',
            'my_custom_meta_box_callback',
            'my_custom_post_type',
            'normal',
            'default'
        );
    }
}

function my_custom_meta_box_callback( $post ) {
    // 元框的内容
    echo '<p>这是一个自定义元框，仅在新建 my_custom_post_type 文章时显示。</p>';
}

在这个例子中，我们首先使用 get_current_screen() 获取当前的 WP_Screen 对象。然后，我们检查 $screen->post_type 是否为 my_custom_post_type， $screen->base是否为post, 并且 $screen->action 是否为 add。只有当所有条件都满足时，我们才调用 add_meta_box 函数来添加元框。

三、高级技巧

• 使用 callback_args 传递参数: 你可以使用 add_meta_box 的 $callback_args 参数将额外的参数传递给回调函数。这对于在不同的元框中使用相同的回调函数时非常有用。

add_action( 'add_meta_boxes', 'my_add_meta_boxes' );

function my_add_meta_boxes() {
    add_meta_box(
        'my_meta_box_1',
        '元框 1',
        'my_meta_box_callback',
        'post',
        'normal',
        'default',
        array( 'message' => '这是元框 1 的消息' )
    );

    add_meta_box(
        'my_meta_box_2',
        '元框 2',
        'my_meta_box_callback',
        'post',
        'normal',
        'default',
        array( 'message' => '这是元框 2 的消息' )
    );
}

function my_meta_box_callback( $post, $args ) {
    echo '<p>' . $args['args']['message'] . '</p>';
}

• 使用 JavaScript 增强元框: 你可以使用 JavaScript 来增强元框的功能，例如添加动态字段、实现表单验证或使用 AJAX 与服务器通信。

• 创建可重复的元框: 可以使用自定义字段组（例如，使用 ACF 或 Metabox.io 插件）来创建可重复的元框，允许用户添加多个相同类型的字段组。

• 使用 remove_meta_box 移除元框: 你可以使用 remove_meta_box 函数来移除 WordPress 默认或插件添加的元框。

add_action( 'admin_menu', 'my_remove_meta_boxes' );

function my_remove_meta_boxes() {
    remove_meta_box( 'postexcerpt', 'post', 'normal' ); // 移除文章摘要元框
}

四、最佳实践

• 使用唯一 ID: 为每个元框选择一个唯一的 ID，以避免与其他插件或主题冲突。
• 使用 nonce 字段: 始终使用 nonce 字段来保护你的元框免受 CSRF 攻击。
• 清理用户输入: 在保存元数据之前，始终清理用户输入，以防止安全漏洞。
• 使用 esc_attr 和 wp_kses_post: 在显示元数据时，使用 esc_attr 和 wp_kses_post 函数来转义和过滤输出，以防止 XSS 攻击。
• 考虑用户体验: 设计你的元框时要考虑用户体验，使其易于使用和理解。

五、错误处理和调试

• 检查错误日志: 如果你的元框没有正确显示或保存数据，请检查 WordPress 错误日志以查找错误消息。
• 使用 var_dump 或 print_r: 使用 var_dump 或 print_r 函数来输出变量的内容，以帮助你调试代码。
• 使用浏览器开发者工具: 使用浏览器开发者工具来检查 HTML 结构和 JavaScript 代码，以查找错误。
• 禁用插件和主题: 尝试禁用其他插件和主题，以查看它们是否与你的代码冲突。

总结

WP_Screen 和 add_meta_box 是定制 WordPress 后台编辑界面的强大工具。 通过理解 WP_Screen 提供的上下文信息，并利用 add_meta_box 创建自定义元框，你可以构建高度定制化和用户友好的 WordPress 后台体验。 请记住安全最佳实践和错误处理方法，以确保你的代码安全可靠。