add_dashboard_page()
云策文档标注
概述
add_dashboard_page() 函数用于在 WordPress 后台仪表盘主菜单下添加一个子菜单页面。它是 add_submenu_page() 的包装函数，指定父菜单为 'index.php'，简化了仪表盘子页面的创建过程。
关键要点
- 函数基于用户角色和能力（Capabilities）控制菜单显示，需在回调函数中验证用户权限。
- 参数包括页面标题、菜单标题、能力要求、菜单slug、回调函数和位置，其中 $position 参数从 WordPress 5.3.0 开始支持。
- 必须在 admin_menu Hook 中调用，以避免权限错误或过早执行问题。
- 返回值为页面 hook_suffix 或 false（用户无权限时）。
代码示例
/**
* Add a page to the dashboard menu.
*/
function wpdocs_plugin_menu() {
add_dashboard_page( __( 'WPDocs Plugin Dashboard', 'textdomain' ), __( 'WPDocs Plugin', 'textdomain' ), 'read', 'wpdocs-unique-identifier', 'wpdocs_plugin_function' );
}
add_action('admin_menu', 'wpdocs_plugin_menu');注意事项
- 确保回调函数检查用户能力，避免安全漏洞。
- 如果遇到“您没有足够权限访问此页面”错误，检查是否在 admin_menu Hook 之前调用函数。
原文内容
Adds a submenu page to the Dashboard 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_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
}
Skip to note 2 content
Codex
Typical usage occurs in a function registered with the ‘admin_menu’ hook:
/** * Add a page to the dashboard menu. */ function wpdocs_plugin_menu() { add_dashboard_page( __( 'WPDocs Plugin Dashboard', 'textdomain' ), __( 'WPDocs Plugin', 'textdomain' ), 'read', 'wpdocs-unique-identifier', 'wpdocs_plugin_function' ); } add_action('admin_menu', 'wpdocs_plugin_menu');