当前浏览:首页 / WordPress函数 / add_role()

add_role( string $role, string $display_name, bool[] $capabilities = array() )

添加角色(如果不存在)

addmore...

role 角色


参数

$role

(string)(必填) 角色名称。

$display_name

(string)(必填) 角色的显示名称。

$capabilities

(bool[])(可选) 以能力名称为键名的能力列表,例如 array( 'edit_posts' => true, 'delete_posts' => false )

默认值: array()


返回

(WP_Role|null) 如果成功添加角色则为WP_Role对象,如果角色已存在则为null。



源码

查看源码 官方文档


更新日志

版本描述
2.0.0开始引入

使用示例

  • 示例1

    请确保在触发挂钩或条件块中仅使用此函数(以及类似的角色函数)。无需每次加载页面时都执行此操作,每次调用时都会不断更新数据库。

    例如,这将存储跟踪自定义角色版本的选项,并且只更新数据库一次:

    function xx__update_custom_roles() {
        if ( get_option( 'custom_roles_version' ) < 1 ) {
            add_role( 'custom_role', 'Custom Subscriber', array( 'read' => true, 'level_0' => true ) );
            update_option( 'custom_roles_version', 1 );
        }
    }
    add_action( 'init', 'xx__update_custom_roles' );
    
  • 示例2

    您还可以基于现有用户角色轻松创建新用户角色。
    (相当于WP CLI:wp role create <role-key> <role-name> --clone=<role>

    示例:创建一个与管理员具有相同能力的角色

    add_role( 'superintendent', 'Superintendent', get_role( 'administrator' )->capabilities );
    
  • 示例3

    在激活插件时创建新角色
    请参见register_activation_hook

    function add_roles_on_plugin_activation() {
           add_role( 'custom_role', 'Custom Subscriber', array( 'read' => true, 'level_0' => true ) );
       }
    register_activation_hook( __FILE__, 'add_roles_on_plugin_activation' );
  • 示例4

    示例
    创建一个新的“Guest Author”角色。

    $result = add_role(
    	'guest_author',
    	__( 'Guest Author', 'testdomain' ),
        array(
    		'read'         => true,  // true allows this capability
    		'edit_posts'   => true,
    		'delete_posts' => false, // Use false to explicitly deny
        )
    );
    
    if ( null !== $result ) {
        echo "Success: {$result->name} user role created.";
    }
    else {
        echo 'Failure: user role already exists.';
    }
  • 示例5

    注意:删除现有角色
    不能使用add_role()更改现有角色的能力。如果指定的角色名称已存在,此函数将停止执行并返回null

    您可以使用remove_role(),然后使用add_role(),来更改用户角色的能力(或显示名称)。

    这仅用于开发。一旦确定了能力列表,就无需保留remove_role()代码

  • 示例6

    每个用户角色的所有可能能力列表:
    https://wordpress.org/support/article/roles-and-capabilities/#capability-vs-role-table

    Super Admin
    =========================

    create_sites
    delete_sites
    manage_network
    manage_sites
    manage_network_users
    manage_network_plugins
    manage_network_themes
    manage_network_options
    upload_plugins
    upload_themes
    upgrade_network
    setup_network

    Super Admin + Administrator
    ==========================================

    activate_plugins (single site or enabled by network setting)
    create_users (single site)
    delete_plugins (single site)
    delete_themes (single site)
    delete_users (single site)
    edit_files (single site)
    edit_plugins (single site)
    edit_theme_options
    edit_themes (single site)
    edit_users (single site)
    export
    import

    Super Admin + Administrator
    =============================================

    install_plugins (single site)
    install_themes (single site)
    list_users
    manage_options
    promote_users
    remove_users
    switch_themes
    update_core (single site)
    update_plugins (single site)
    update_themes (single site)
    edit_dashboard
    customize
    delete_site

    Super Admin + Administrator + Editor
    ====================================================

    moderate_comments
    manage_categories
    manage_links
    edit_others_posts
    edit_pages
    edit_others_pages
    edit_published_pages
    publish_pages
    delete_pages
    delete_others_pages
    delete_published_pages
    delete_others_posts
    delete_private_posts
    edit_private_posts
    read_private_posts
    delete_private_pages
    edit_private_pages
    read_private_pages
    unfiltered_html (single site)
    unfiltered_html

    Super Admin + Administrator + Editor + Author
    ==========================================================

    edit_published_posts
    upload_files
    publish_posts
    delete_published_posts

    Super Admin + Administrator + Editor + Author + Contributor
    ========================================================================

    edit_posts
    delete_posts

    Super Admin + Administrator + Editor + Author + Contributor + Subscriber
    ======================================================================================

    read

  • 示例7

    注意:当调用时
    在尝试添加或修改角色之前,请确保全局$wp_roles可用。最佳实践是使用插件(或主题)激活挂钩对角色进行更改(因为您只想做一次!)。

    mu-plugins加载太早,因此如果您在mu-plugin的上下文中执行此操作,请使用动作钩子(如'init')来包装add_role()调用。

  • 示例8

    用法

    <?php add_role( $role, $display_name, $capabilities ); ?>