admin_menu
云策文档标注
概述
admin_menu 是一个 WordPress 动作钩子,在管理后台菜单加载前触发,主要用于向管理面板菜单结构添加额外的子菜单和菜单选项。它运行在基本管理面板菜单结构就位之后,不应放置在 admin_init 动作函数中。
关键要点
- admin_menu 钩子用于扩展管理后台菜单,如添加自定义菜单项或修改现有菜单。
- 参数 $context 是一个空字符串,表示上下文为空。
- 此钩子必须在 admin_init 之前调用,因为 admin_init 在 admin_menu 之后执行。
- 可以通过全局变量 $menu 和 $submenu 直接修改菜单标签或结构。
- 使用 add_menu_page() 和 add_submenu_page() 函数来添加新菜单页面。
- 注意删除菜单项时需使用正确的 slug,并避免在 admin_menu 钩子中直接删除无效的菜单项。
代码示例
// 修改媒体菜单标签示例
add_action( 'admin_menu', 'change_media_label' );
function change_media_label(){
global $menu, $submenu;
$menu[10][0] = 'Photos/Videos';
$submenu['upload.php'][5][0] = 'All Photos/Videos';
$submenu['upload.php'][10][0] = 'Upload new';
}// 添加自定义菜单页面示例
add_action( 'admin_menu', array( $this, 'wpdocs_add_menu_page' ), 99 );
public function wpdocs_add_menu_page() {
add_menu_page(
esc_html__( 'WooCommerce B2B Sales Agents', 'woocommerce-b2b-sales-agents' ),
esc_html__( 'WooCommerce B2B Sales Agents', 'woocommerce-b2b-sales-agents'),
'manage_woocommerce',
'wcb2bsa-commissions',
null,
'dashicons-businessman',
55.5
);
add_submenu_page(
'wcb2bsa-commissions',
esc_html__( 'Commissions', 'woocommerce-b2b-sales-agents' ),
esc_html__( 'Commissions', 'woocommerce-b2b-sales-agents' ),
'manage_woocommerce',
'wcb2bsa-commissions',
array( $this, 'wpdocs_add_menu_page_callback' )
);
}注意事项
- 避免在 admin_init 动作函数中使用 admin_menu,因为执行顺序可能导致问题。
- 删除菜单项时,确保使用 remove_menu_page() 函数并提供正确的 slug,否则可能无效。
- 钩子优先级可用于控制执行顺序,例如使用 99 或 99999 来延迟或提前执行。
原文内容
Fires before the administration menu loads in the admin.
Parameters
$contextstring-
Empty context.
Source
do_action( 'admin_menu', '' );
Changelog
| Version | Description |
|---|---|
| 1.5.0 | Introduced. |
Skip to note 6 content
Aurovrata Venet
If you want to change a menu label, you can hook this action and change the
global $menu, $submenu values,add_action( 'admin_menu', 'change_media_label' ); function change_media_label(){ global $menu, $submenu; debug_msg($menu); $menu[10][0] = 'Photos/Videos'; $submenu['upload.php'][5][0] = 'All Photos/Videos'; $submenu['upload.php'][10][0] = 'Upload new'; }Skip to note 7 content
Milad
This snippet add admin menu and submenu HTML content
//call the 'add_menu_page' function with 'admin_menu' action hook add_action( 'admin_menu', array( $this, 'wpdocs_add_menu_page' ), 99 ); /** * Add page to admin menu */ public function wpdocs_add_menu_page() { add_menu_page( esc_html__( 'WooCommerce B2B Sales Agents', 'woocommerce-b2b-sales-agents' ), esc_html__( 'WooCommerce B2B Sales Agents', 'woocommerce-b2b-sales-agents'), 'manage_woocommerce', 'wcb2bsa-commissions', null, 'dashicons-businessman', 55.5 ); add_submenu_page( 'wcb2bsa-commissions', esc_html__( 'Commissions', 'woocommerce-b2b-sales-agents' ), esc_html__( 'Commissions', 'woocommerce-b2b-sales-agents' ), 'manage_woocommerce', 'wcb2bsa-commissions', array( $this, 'wpdocs_add_menu_page_callback' ) ); } /** * Add page to admin menu callback */ public function wpdocs_add_menu_page_callback() { include WCB2BSA_ABSPATH . 'includes/views/html-admin--page-commissions.php'; }Skip to note 8 content
Chigozie Orunta
Let’s say you’re building a plugin and you need to register an overview or dashboard menu option for your plugin page, you can do it like so:
// Define constants define( 'PLUGIN_SLUG', 'your-plugin' ); define( 'PLUGIN_ROLE', 'manage_options' ); define( 'PLUGIN_DOMAIN', 'your-plugin-text-domain' ); add_action( 'admin_menu', 'register_your_plugin_menu', 9 ); function register_your_plugin_menu() { add_menu_page( __( 'Your Plugin', PLUGIN_DOMAIN ), 'Your Plugin', PLUGIN_ROLE, PLUGIN_SLUG, false, 'dashicons-admin-generic', '' ); add_submenu_page( PLUGIN_SLUG, 'Your Plugin', 'Dashboard', PLUGIN_ROLE, PLUGIN_SLUG, 'your_plugin_dashboard_callback', ); }Skip to note 9 content
Gamelot
You may come across the fact that deleting items having the slug like admin.php?page=jetpack in the admin_menu hook does not affect the menu in any way and the items remain in their places. To fix it, define correct slugs to delete with remove_menu_page() function.
Try this code:
function wpdocs_list_menus() { global $menu; var_dump( $menu ); } add_action( 'admin_menu', 'wpdocs_list_menus', 99999 );Skip to note 10 content
Steven Lin
Example migrated from Codex:
The example comes from the wpautop-control plugin, in which the code is used to add an options page to the “Settings” menu.
add_action('admin_menu', 'wpautop_control_menu'); function wpautop_control_menu() { add_submenu_page('options-general.php', 'wpautop-control', 'wpautop control', 'manage_options', 'wpautop-control-menu', 'wpautop_control_options'); }