如何利用`WP_Screen`和`add_meta_box`定制后台编辑界面，并实现基于用户角色的显示控制？

WordPress 后台编辑界面深度定制：WP_Screen 与 add_meta_box 的用户角色控制

大家好！今天我们来深入探讨 WordPress 后台编辑界面的定制技巧，重点关注 WP_Screen 类和 add_meta_box 函数，以及如何基于用户角色实现更精细的显示控制。

WP_Screen 类：后台界面的上下文感知

WP_Screen 类是 WordPress 3.4 引入的一个强大的工具，它提供了关于当前后台屏幕的上下文信息。通过它可以获取当前页面 ID、父页面 ID、类型（如 post、taxonomy、settings）、以及是否是某个特定页面的信息。这使得我们可以根据当前屏幕的上下文来定制界面行为。

WP_Screen 的主要属性：

属性	类型	描述
$action	string	当前屏幕执行的动作，例如 add、edit。
$base	string	屏幕的基本标识符，例如 post、edit。
$columns	int	屏幕显示的列数。
$id	string	屏幕的唯一 ID。 通常是 $base 的变体，例如 post-new、edit-post。
$in_admin	bool	是否在后台。
$is_network	bool	是否在网络管理后台（多站点）。
$is_user	bool	是否是用户相关的屏幕（例如，用户列表，用户编辑）。
$parent_base	string	父屏幕的基本标识符。
$parent_file	string	父菜单的文件。
$post_type	string	如果是文章相关的屏幕，则为文章类型。
$taxonomy	string	如果是分类法相关的屏幕，则为分类法名称。
$screen_reader_content	array	用于屏幕阅读器的内容。
$show_screen_options	bool	是否显示屏幕选项。
$taxonomy	string	如果当前屏幕是分类法编辑页面，则此属性包含分类法名称。
$post_type	string	如果当前屏幕是文章编辑页面，则此属性包含文章类型。

如何使用 WP_Screen：

获取当前屏幕对象：

$screen = get_current_screen();

if ( $screen ) {
    echo '屏幕 ID: ' . $screen->id . '<br>';
    echo '文章类型: ' . $screen->post_type . '<br>';
}

这个简单的例子展示了如何获取当前屏幕的 ID 和文章类型。 我们可以根据这些信息来执行不同的操作。

add_meta_box：添加自定义元数据框

add_meta_box 函数允许我们在文章、页面或其他自定义文章类型的编辑页面上添加自定义的元数据框。这些元数据框可以包含任何我们需要的自定义字段，例如文本输入框、下拉列表、复选框等。

add_meta_box 的参数：

add_meta_box(
    string   $id,            // 元数据框的唯一 ID
    string   $title,         // 元数据框的标题
    callable $callback,      // 回调函数，用于渲染元数据框的内容
    string|array|WP_Screen $screen = null, // 屏幕（文章类型、页面等），可以是字符串、数组或 WP_Screen 对象。默认为当前文章类型。
    string   $context = 'advanced', // 元数据框的显示位置，可以是 'normal'、'advanced' 或 'side'
    string   $priority = 'default', // 元数据框的优先级，可以是 'high'、'core'、'default' 或 'low'
    array    $callback_args = null  // 传递给回调函数的参数
);

一个简单的 add_meta_box 示例：

function my_custom_meta_box() {
    add_meta_box(
        'my_meta_box_id',
        'My Custom Meta Box',
        'my_meta_box_callback',
        'post', // 应用于 "post" 文章类型
        'normal',
        'default'
    );
}
add_action( 'add_meta_boxes', 'my_custom_meta_box' );

function my_meta_box_callback( $post ) {
    // 使用 $post 对象获取已保存的元数据
    $value = get_post_meta( $post->ID, '_my_meta_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" />';

    // 添加一个 nonce 字段，用于安全验证
    wp_nonce_field( 'my_meta_box_nonce', 'my_meta_box_nonce_field' );
}

// 保存元数据的函数
function save_my_meta_box_data( $post_id ) {
    // 验证 nonce
    if ( ! isset( $_POST['my_meta_box_nonce_field'] ) || ! wp_verify_nonce( $_POST['my_meta_box_nonce_field'], 'my_meta_box_nonce' ) ) {
        return;
    }

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

    // 检查是否是自动保存
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
        return;
    }

    // 保存数据
    if ( isset( $_POST['my_meta_field'] ) ) {
        $data = sanitize_text_field( $_POST['my_meta_field'] );
        update_post_meta( $post_id, '_my_meta_key', $data );
    }
}
add_action( 'save_post', 'save_my_meta_box_data' );

这段代码创建了一个名为 "My Custom Meta Box" 的元数据框，其中包含一个文本输入框。它还包含了保存元数据的逻辑，包括 nonce 验证、用户权限检查和数据清理。

基于用户角色控制 add_meta_box 的显示

现在，我们来重点讨论如何基于用户角色来控制 add_meta_box 的显示。这可以通过结合 WP_Screen 类和 WordPress 的用户角色管理系统来实现。

基本思路：

1. 获取当前用户。
2. 检查用户的角色。
3. 根据角色决定是否添加 add_meta_box。

示例代码：

function my_custom_meta_box_based_on_role() {
    $current_user = wp_get_current_user();
    $user_roles = ( array ) $current_user->roles;

    // 只允许管理员和编辑者看到元数据框
    if ( in_array( 'administrator', $user_roles ) || in_array( 'editor', $user_roles ) ) {
        add_meta_box(
            'my_role_based_meta_box_id',
            'Role-Based Meta Box',
            'my_meta_box_callback',
            'post',
            'normal',
            'default'
        );
    }
}
add_action( 'add_meta_boxes', 'my_custom_meta_box_based_on_role' );

这段代码首先获取当前用户的角色，然后检查用户是否是管理员或编辑者。如果是，则添加元数据框。

更灵活的角色控制：

我们可以使用 current_user_can() 函数来进行更细粒度的权限控制。 例如，我们可以创建一个自定义的 capability，并将其分配给特定的角色。

// 在插件激活时添加自定义 capability
function add_custom_capability() {
    $roles = get_editable_roles();

    foreach ( $roles as $role_name => $role_info ) {
        $role = get_role( $role_name );
        if($role && $role_name != 'subscriber') { //避免给订阅者添加capability
            $role->add_cap( 'view_custom_meta_box' );
        }

    }
}
register_activation_hook( __FILE__, 'add_custom_capability' );

// 在插件停用时移除自定义 capability
function remove_custom_capability() {
    $roles = get_editable_roles();
    foreach ( $roles as $role_name => $role_info ) {
         $role = get_role( $role_name );
        if($role && $role_name != 'subscriber') { //避免给订阅者移除capability
            $role->remove_cap( 'view_custom_meta_box' );
        }
    }
}
register_deactivation_hook( __FILE__, 'remove_custom_capability' );

function my_custom_meta_box_with_capability() {
    // 检查用户是否具有 "view_custom_meta_box" capability
    if ( current_user_can( 'view_custom_meta_box' ) ) {
        add_meta_box(
            'my_capability_based_meta_box_id',
            'Capability-Based Meta Box',
            'my_meta_box_callback',
            'post',
            'normal',
            'default'
        );
    }
}
add_action( 'add_meta_boxes', 'my_custom_meta_box_with_capability' );

在这个例子中，我们创建了一个名为 view_custom_meta_box 的 capability，并将其分配给需要查看元数据框的角色。 然后，我们使用 current_user_can() 函数来检查用户是否具有该 capability。

使用 WP_Screen 进行更精确的控制：

我们可以将 WP_Screen 类与用户角色控制结合起来，以实现更精确的控制。 例如，我们可以根据文章类型和用户角色来决定是否显示元数据框。

function my_custom_meta_box_with_screen_and_role() {
    $screen = get_current_screen();
    $current_user = wp_get_current_user();
    $user_roles = ( array ) $current_user->roles;

    // 只在 "product" 文章类型的编辑页面上，并且用户是管理员或编辑者时，才显示元数据框
    if ( $screen && $screen->post_type == 'product' && ( in_array( 'administrator', $user_roles ) || in_array( 'editor', $user_roles ) ) ) {
        add_meta_box(
            'my_screen_and_role_based_meta_box_id',
            'Product Meta Box',
            'my_meta_box_callback',
            'product',
            'normal',
            'default'
        );
    }
}
add_action( 'add_meta_boxes', 'my_custom_meta_box_with_screen_and_role' );

这段代码只有在当前屏幕是 "product" 文章类型的编辑页面，并且用户是管理员或编辑者时，才会添加元数据框。

更高级的用法：动态改变 add_meta_box 的参数

除了控制是否显示 add_meta_box，我们还可以根据用户角色动态地改变 add_meta_box 的参数，例如标题、上下文和优先级。

function my_dynamic_meta_box() {
    $current_user = wp_get_current_user();
    $user_roles = (array) $current_user->roles;

    $title = 'Default Meta Box Title';
    $context = 'advanced';
    $priority = 'default';

    if (in_array('administrator', $user_roles)) {
        $title = 'Admin Meta Box Title';
        $context = 'normal';
        $priority = 'high';
    } elseif (in_array('editor', $user_roles)) {
        $title = 'Editor Meta Box Title';
        $context = 'side';
        $priority = 'low';
    }

    add_meta_box(
        'my_dynamic_meta_box_id',
        $title,
        'my_meta_box_callback',
        'post',
        $context,
        $priority
    );
}
add_action('add_meta_boxes', 'my_dynamic_meta_box');

在这个例子中，根据用户的角色，元数据框的标题、位置和优先级会发生变化。

安全注意事项：

• 始终验证用户输入和 nonce 字段，以防止安全漏洞。
• 确保用户具有执行操作所需的权限。
• 使用 sanitize_text_field() 等函数来清理用户输入，以防止 XSS 攻击。
• 不要在客户端存储敏感信息。

示例：一个完整的案例，基于用户角色和文章状态控制元数据框显示

现在，我们来创建一个更完整的案例，演示如何基于用户角色和文章状态来控制元数据框的显示。假设我们有一个 "review" 文章类型，我们希望只有管理员和编辑者才能看到一个 "Review Details" 元数据框，并且只有在文章状态为 "pending" 时才显示。

// 注册 "review" 文章类型（如果尚未注册）
function register_review_post_type() {
    $labels = array(
        'name'               => 'Reviews',
        'singular_name'      => 'Review',
        'menu_name'          => 'Reviews',
        'name_admin_bar'     => 'Review',
        'add_new'            => 'Add New',
        'add_new_item'       => 'Add New Review',
        'new_item'           => 'New Review',
        'edit_item'          => 'Edit Review',
        'view_item'          => 'View Review',
        'all_items'          => 'All Reviews',
        'search_items'       => 'Search Reviews',
        'parent_item_colon'  => 'Parent Reviews:',
        'not_found'          => 'No reviews found.',
        'not_found_in_trash' => 'No reviews found in Trash.'
    );

    $args = array(
        'labels'             => $labels,
        'public'             => true,
        'publicly_queryable' => true,
        'show_ui'            => true,
        'show_in_menu'       => true,
        'query_var'          => true,
        'rewrite'            => array( 'slug' => 'review' ),
        'capability_type'    => 'post',
        'has_archive'        => true,
        'hierarchical'       => false,
        'menu_position'      => null,
        'supports'           => array( 'title', 'editor', 'author', 'thumbnail', 'excerpt', 'comments' )
    );

    register_post_type( 'review', $args );
}
add_action( 'init', 'register_review_post_type' );

// 添加元数据框
function review_details_meta_box() {
    $screen = get_current_screen();
    $current_user = wp_get_current_user();
    $user_roles = ( array ) $current_user->roles;
    global $post;

    // 检查文章状态和用户角色
    if ( $screen && $screen->post_type == 'review' && get_post_status( $post->ID ) == 'pending' && ( in_array( 'administrator', $user_roles ) || in_array( 'editor', $user_roles ) ) ) {
        add_meta_box(
            'review_details_meta_box_id',
            'Review Details',
            'review_details_meta_box_callback',
            'review',
            'normal',
            'default'
        );
    }
}
add_action( 'add_meta_boxes', 'review_details_meta_box' );

// 元数据框的回调函数
function review_details_meta_box_callback( $post ) {
    // 获取已保存的元数据
    $reviewer_name = get_post_meta( $post->ID, '_reviewer_name', true );
    $review_score = get_post_meta( $post->ID, '_review_score', true );

    // 输出表单字段
    echo '<label for="reviewer_name">Reviewer Name:</label>';
    echo '<input type="text" id="reviewer_name" name="reviewer_name" value="' . esc_attr( $reviewer_name ) . '" size="25" /><br><br>';

    echo '<label for="review_score">Review Score:</label>';
    echo '<input type="number" id="review_score" name="review_score" value="' . esc_attr( $review_score ) . '" min="0" max="10" /><br><br>';

    // 添加 nonce 字段
    wp_nonce_field( 'review_details_meta_box_nonce', 'review_details_meta_box_nonce_field' );
}

// 保存元数据
function save_review_details_meta_box_data( $post_id ) {
    // 验证 nonce
    if ( ! isset( $_POST['review_details_meta_box_nonce_field'] ) || ! wp_verify_nonce( $_POST['review_details_meta_box_nonce_field'], 'review_details_meta_box_nonce' ) ) {
        return;
    }

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

    // 检查是否是自动保存
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
        return;
    }

    // 保存数据
    if ( isset( $_POST['reviewer_name'] ) ) {
        $reviewer_name = sanitize_text_field( $_POST['reviewer_name'] );
        update_post_meta( $post_id, '_reviewer_name', $reviewer_name );
    }

    if ( isset( $_POST['review_score'] ) ) {
        $review_score = intval( $_POST['review_score'] );
        update_post_meta( $post_id, '_review_score', $review_score );
    }
}
add_action( 'save_post', 'save_review_details_meta_box_data' );

这段代码创建了一个 "Review" 文章类型，并添加了一个 "Review Details" 元数据框，其中包含 "Reviewer Name" 和 "Review Score" 两个字段。元数据框只会在 "Review" 文章类型的编辑页面上，文章状态为 "pending"，并且用户是管理员或编辑者时才会显示。

更进一步：使用 JavaScript 动态控制元数据框内容

有时候，我们可能需要在客户端使用 JavaScript 来动态控制元数据框的内容。例如，我们可以根据用户的选择来显示或隐藏某些字段。

示例：

// 在元数据框中添加一个复选框
function my_meta_box_callback( $post ) {
    $show_extra_fields = get_post_meta( $post->ID, '_show_extra_fields', true );

    echo '<input type="checkbox" id="show_extra_fields" name="show_extra_fields" value="1" ' . checked( $show_extra_fields, 1, false ) . '>';
    echo '<label for="show_extra_fields">Show Extra Fields</label><br><br>';

    echo '<div id="extra_fields" style="display: none;">';
    echo '<label for="extra_field_1">Extra Field 1:</label>';
    echo '<input type="text" id="extra_field_1" name="extra_field_1" value="' . get_post_meta( $post->ID, '_extra_field_1', true ) . '"><br><br>';
    echo '</div>';

    ?>
    <script type="text/javascript">
        jQuery(document).ready(function($) {
            var showExtraFields = $('#show_extra_fields');
            var extraFields = $('#extra_fields');

            // 初始化时检查复选框的状态
            if (showExtraFields.is(':checked')) {
                extraFields.show();
            }

            // 监听复选框的点击事件
            showExtraFields.on('click', function() {
                if ($(this).is(':checked')) {
                    extraFields.fadeIn();
                } else {
                    extraFields.fadeOut();
                }
            });
        });
    </script>
    <?php

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

// 保存复选框的状态和额外字段
function save_my_meta_box_data( $post_id ) {
    // ... (nonce 验证和权限检查)

    if ( isset( $_POST['show_extra_fields'] ) ) {
        update_post_meta( $post_id, '_show_extra_fields', 1 );
    } else {
        update_post_meta( $post_id, '_show_extra_fields', 0 );
    }

    if ( isset( $_POST['extra_field_1'] ) ) {
        update_post_meta( $post_id, '_extra_field_1', sanitize_text_field( $_POST['extra_field_1'] ) );
    }
}

这段代码首先添加了一个复选框，用于控制是否显示额外字段。 然后，它使用 JavaScript 来监听复选框的点击事件，并根据复选框的状态来显示或隐藏额外字段。

总结

通过 WP_Screen 和 add_meta_box 函数，结合 WordPress 的用户角色管理系统，我们可以构建出高度定制化的后台编辑界面，并实现精细的显示控制。 灵活使用它们，可以根据用户角色和文章状态，动态调整元数据框的显示、内容和行为。希望今天的讲解能够帮助大家更好地定制 WordPress 后台界面。