云策 WordPress 开发者社区

插件开发文档

角色与权限

查看官方原文 ↗
💡 云策文档标注

概述

角色与权限是 WordPress 中控制用户权限的两个核心概念，用于定义用户在后台的访问和操作能力。文档详细介绍了如何添加、移除角色和权限，以及相关函数的使用方法。

关键要点

  • 角色定义一组权限，默认包括超级管理员、管理员、编辑、作者、贡献者和订阅者。
  • 使用 add_role() 添加新角色，remove_role() 移除角色，注意首次调用后角色信息会存储或从数据库中移除。
  • 权限定义角色能执行的操作，如编辑文章、发布文章等，可通过 get_role() 和 add_cap()/remove_cap() 管理。
  • 使用 user_can() 和 current_user_can() 检查用户权限，后者针对当前用户，适用于前后端权限控制。
  • 在多站点环境中，使用 current_user_can_for_blog() 测试特定博客的权限。

代码示例

function wporg_simple_role() {
    add_role(
        'simple_role',
        'Simple Role',
        array(
            'read'         => true,
            'edit_posts'   => true,
            'upload_files' => true,
        ),
    );
}
add_action( 'init', 'wporg_simple_role' );

if ( current_user_can( 'edit_posts' ) ) {
    edit_post_link( esc_html__( 'Edit', 'wporg' ), '<p>', '</p>' );
}

注意事项

  • 避免移除管理员和超级管理员角色，并确保插件/主题代码能处理未来 WordPress 更新可能重新添加默认角色的情况。
  • 移除默认角色（如订阅者）时，需使用 update_option('default_role', YOUR_NEW_DEFAULT_ROLE) 更新默认角色设置。
  • 自定义权限在默认 WordPress 后台可能无效，但可用于自定义管理界面和前端区域。
📄 原文内容

Roles and capabilities are two important aspects of WordPress that allow you to control user privileges.

WordPress stores the Roles and their Capabilities in the options table under the user_roles key.

Roles

A role defines a set of capabilities for a user. For example, what the user may see and do in his dashboard.

By default, WordPress have six roles:

  • Super Admin
  • Administrator
  • Editor
  • Author
  • Contributor
  • Subscriber

More roles can be added and the default roles can be removed.

Adding Roles

Add new roles and assign capabilities to them with add_role() .

function wporg_simple_role() {
	add_role(
		'simple_role',
		'Simple Role',
		array(
			'read'         => true,
			'edit_posts'   => true,
			'upload_files' => true,
		),
	);
}

// Add the simple_role.
add_action( 'init', 'wporg_simple_role' );
After the first call to add_role() , the Role and it’s Capabilities will be stored in the database!

Sequential calls will do nothing: including altering the capabilities list, which might not be the behavior that you’re expecting.

To alter the capabilities list in bulk: remove the role using remove_role() and add it again using add_role() with the new capabilities.

Make sure to do it only if the capabilities differ from what you’re expecting (i.e. condition this) or you’ll degrade performance considerably!

Removing Roles

Remove roles with remove_role() .

function wporg_simple_role_remove() {
	remove_role( 'simple_role' );
}

// Remove the simple_role.
add_action( 'init', 'wporg_simple_role_remove' );
After the first call to remove_role() , the Role and it’s Capabilities will be removed from the database!

Sequential calls will do nothing.

If you’re removing the default roles:

  • We advise against removing the Administrator and Super Admin roles!
  • Make sure to keep the code in your plugin/theme as future WordPress updates may add these roles again.
  • Run
    update_option('default_role', YOUR_NEW_DEFAULT_ROLE)
    since you’ll be deleting subscriber which is WP’s default role.

Capabilities

Capabilities define what a role can and can not do: edit posts, publish posts, etc.

Custom post types can require a certain set of Capabilities.

Adding Capabilities

You may define new capabilities for a role.

Use get_role() to get the role object, then use the add_cap() method of that object to add a new capability.

function wporg_simple_role_caps() {
	// Gets the simple_role role object.
	$role = get_role( 'simple_role' );

	// Add a new capability.
	$role->add_cap( 'edit_others_posts', true );
}

// Add simple_role capabilities, priority must be after the initial role definition.
add_action( 'init', 'wporg_simple_role_caps', 11 );
It’s possible to add custom capabilities to any role.

Under the default WordPress admin, they would have no effect, but they can be used for custom admin screen and front-end areas.

Removing Capabilities

You may remove capabilities from a role.

The implementation is similar to Adding Capabilities with the difference being the use of remove_cap() method for the role object.

Using Roles and Capabilities

Get Role

Get the role object including all of it’s capabilities with get_role() .

get_role( $role );

User Can

Check if a user have a specified role or capability with user_can() .

user_can( $user, $capability );
There is an undocumented, third argument, $args, that may include the object against which the test should be performed.

E.g. Pass a post ID to test for the capability of that specific post.

Current User Can

current_user_can() is a wrapper function for user_can() using the current user object as the $user parameter.

Use this in scenarios where back-end and front-end areas should require a certain level of privileges to access and/or modify.

current_user_can( $capability );

Example

Here’s a practical example of adding an Edit link on the in a template file if the user has the proper capability:

if ( current_user_can( 'edit_posts' ) ) {
	edit_post_link( esc_html__( 'Edit', 'wporg' ), '<p>', '</p>' );
}

Multisite

The current_user_can_for_blog() function is used to test if the current user has a certain role or capability on a specific blog.

current_user_can_for_blog( $blog_id, $capability );

Reference

Codex Reference for User Roles and Capabilities.