add_users_page()
云策文档标注
概述
add_users_page() 函数用于在 WordPress 后台的 Users 或 Profile 主菜单下添加一个子菜单页面。它根据当前用户的权限自动选择父菜单，并返回页面 hook_suffix 或 false。
关键要点
- 函数是 add_submenu_page() 的包装器，指定父菜单为 'users.php' 或 'profile.php'，取决于用户是否具有 'edit_users' 能力。
- 参数包括页面标题、菜单标题、所需能力、菜单 slug、回调函数和位置，其中能力参数控制菜单显示和访问权限。
- 必须在 'admin_menu' hook 中调用，以避免权限错误；回调函数需自行检查用户能力。
- 返回值为页面 hook_suffix（字符串）或 false（如果用户无所需能力）。
代码示例
/**
* Register a new page under "Users".
*/
function wpdocs_my_users_menu() {
add_users_page(
__( 'My Plugin Users', 'textdomain' ),
__( 'My Plugin', 'textdomain' ),
'read',
'my-unique-identifier',
'my_plugin_function'
);
}
add_action('admin_menu', 'wpdocs_my_users_menu');注意事项
如果遇到 "You do not have sufficient permissions to access this page." 错误，可能是因为 hook 调用过早，应确保在 'admin_menu' hook 中使用。
原文内容
Adds a submenu page to the Users/Profile main menu.
Description
This function takes a capability which will be used to determine whether or not a page is included in the menu.
The function which is hooked in to handle the output of the page must check that the user has the required capability as well.
Parameters
$page_titlestringrequired-
The text to be displayed in the title tags of the page when the menu is selected.
$menu_titlestringrequired-
The text to be used for the menu.
$capabilitystringrequired-
The capability required for this menu to be displayed to the user.
$menu_slugstringrequired-
The slug name to refer to this menu by (should be unique for this menu).
$callbackcallableoptional-
The function to be called to output the content for this page.
$positionintoptional-
The position in the menu order this item should appear.
Default:
null
Source
function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
if ( current_user_can( 'edit_users' ) ) {
$parent = 'users.php';
} else {
$parent = 'profile.php';
}
return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
Skip to note 2 content
Codex
Basic Example
Typical usage occurs in a function registered with the ‘admin_menu‘ hook (see Adding Administration Menus):
/** * Register a new page under "Users". */ function wpdocs_my_users_menu() { add_users_page( __( 'My Plugin Users', 'textdomain' ), __( 'My Plugin', 'textdomain' ), 'read', 'my-unique-identifier', 'my_plugin_function' ); } add_action('admin_menu', 'wpdocs_my_users_menu');