云策 WordPress 开发者社区

函数文档

wp_roles()

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

概述

wp_roles() 函数用于获取全局 WP_Roles 实例，并在必要时实例化它。这是 WordPress 中管理用户角色和权限的核心函数。

关键要点

  • 函数返回 WP_Roles 全局实例，如果未实例化则自动创建
  • 通过全局变量 $wp_roles 实现单例模式，确保实例唯一性
  • 在 WordPress 4.3.0 版本中引入

代码示例

function wp_roles() {
	global $wp_roles;

	if ( ! isset( $wp_roles ) ) {
		$wp_roles = new WP_Roles();
	}
	return $wp_roles;
}

注意事项

  • 该函数常用于与用户角色相关的操作，如获取可编辑角色列表、添加或移除角色能力等
  • 相关函数包括 get_role(), add_role(), remove_role() 等，用于角色管理
  • 在插件或主题开发中，直接调用 wp_roles() 可安全访问角色实例，避免重复实例化
📄 原文内容

Retrieves the global WP_Roles instance and instantiates it if necessary.

Return

WP_Roles WP_Roles global instance if not already instantiated.

Source

function wp_roles() {
	global $wp_roles;

	if ( ! isset( $wp_roles ) ) {
		$wp_roles = new WP_Roles();
	}
	return $wp_roles;
}

View all references View on Trac View on GitHub

Uses Description
WP_Roles::__construct()wp-includes/class-wp-roles.php

Constructor.
Used by Description
wp_switch_roles_and_user()wp-includes/ms-blogs.php

Switches the initialized roles and current user capabilities to another site.
wp_get_users_with_no_role()wp-includes/user.php

Gets the user IDs of all users with no role on this site.
WP_Users_List_Table::get_role_list()wp-admin/includes/class-wp-users-list-table.php

Returns an array of translated user role names for a given user object.
populate_roles()wp-admin/includes/schema.php

Execute WordPress role creation for the various WordPress versions.
edit_user()wp-admin/includes/user.php

Edit user settings based on contents of $_POST
get_editable_roles()wp-admin/includes/user.php

Fetch a filtered list of user roles that the current user is allowed to edit.
WP_Users_List_Table::get_views()wp-admin/includes/class-wp-users-list-table.php

Returns an associative array listing all the views that can be used with this table.
WP_User::get_role_caps()wp-includes/class-wp-user.php

Retrieves all of the capabilities of the user’s roles, and merges them with individual user capabilities.
WP_Role::add_cap()wp-includes/class-wp-role.php

Assign role a capability.
WP_Role::remove_cap()wp-includes/class-wp-role.php

Removes a capability from a role.
get_role()wp-includes/capabilities.php

Retrieves role object.
remove_role()wp-includes/capabilities.php

Removes a role, if it exists.
add_role()wp-includes/capabilities.php

Adds a role, if it does not exist.
count_users()wp-includes/user.php

Counts number of users who have each of the user roles.

Show 9 moreShow less

Changelog

Version Description
4.3.0 Introduced.