钩子文档

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.

More Information

  • This action is used to add extra submenus and menu options to the admin panel’s menu structure. It runs after the basic admin panel menu structure is in place.
  • This action mustn’t be placed in an admin_init action function because the admin_init action is called after admin_menu.

Source

do_action( 'admin_menu', '' );

Changelog

Version Description
1.5.0 Introduced.

User Contributed Notes

  1. Skip to note 6 content

    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';
    }

  2. Skip to note 7 content

    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';
        }

  3. Skip to note 8 content

    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',
    	);
    }

  4. Skip to note 9 content

    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 );

  5. Skip to note 10 content

    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');
    }