钩子文档

admin_bar_menu

💡 云策文档标注

概述

admin_bar_menu 是一个 WordPress 动作钩子,用于在管理工具栏中添加、移除或修改菜单项。开发者可以通过此钩子自定义工具栏内容,优先级参数影响菜单项的位置。

关键要点

  • admin_bar_menu 钩子用于操作管理工具栏菜单,可添加、移除或修改节点。
  • 优先级决定新菜单项的放置顺序,高优先级可用于修改现有项。
  • 移除或操作现有节点而无特定优先级时,应使用 wp_before_admin_bar_render 钩子。
  • 参数 $wp_admin_bar 是 WP_Admin_Bar 实例的引用,用于调用 add_menu 等方法。
  • 核心菜单项的优先级可在 WP_Admin_Bar::add_menus() 中查看,以辅助设置自定义优先级。

代码示例

add_action( 'admin_bar_menu', 'admin_bar_item', 500 );
function admin_bar_item ( WP_Admin_Bar $admin_bar ) {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    $admin_bar->add_menu( array(
        'id'    => 'menu-id',
        'parent' => null,
        'group'  => null,
        'title' => 'Menu Title',
        'href'  => admin_url('admin.php?page=custom-page'),
        'meta' => [
            'title' => __( 'Menu Title', 'textdomain' ),
        ]
    ) );
}

注意事项

  • 确保回调函数名称与 add_action 中指定的一致,以避免“无效回调”错误。
  • 使用 parent 参数如 'top-secondary' 可将菜单项放置在工具栏右侧。
  • 在非管理员区域显示菜单时,需添加条件检查如 is_admin()。

📄 原文内容

Loads all necessary admin bar items.

Description

This hook can add, remove, or manipulate admin bar items. The priority determines the placement for new items, and changes to existing items would require a high priority. To remove or manipulate existing nodes without a specific priority, use wp_before_admin_bar_render.

Parameters

$wp_admin_barWP_Admin_Bar
The WP_Admin_Bar instance, passed by reference.

Source

do_action_ref_array( 'admin_bar_menu', array( &$wp_admin_bar ) );

Changelog

Version Description
3.1.0 Introduced.

User Contributed Notes

  1. Skip to note 6 content

    This hook is used to add the admin bar menu.

    Example:-

    add_action( 'admin_bar_menu', 'admin_bar_item', 500 );
    function admin_bar_item ( WP_Admin_Bar $admin_bar ) {
    	if ( ! current_user_can( 'manage_options' ) ) {
    		return;
    	}
    	$admin_bar->add_menu( array(
    		'id'    => 'menu-id',
    		'parent' => null,
    		'group'  => null,
    		'title' => 'Menu Title', //you can use img tag with image link. it will show the image icon Instead of the title.
    		'href'  => admin_url('admin.php?page=custom-page'),
    		'meta' => [
    			'title' => __( 'Menu Title', 'textdomain' ), //This title will show on hover
    		]
    	) );
    }

  2. Skip to note 7 content

    Display custom menu only for the admin area and add dropdown menu

    function ci_admin_bar_item( WP_Admin_Bar $wp_admin_bar ) {
    
    	if ( !is_admin() ) {
    		return;
    	} // Display Menu only for wp-admin area
    
    	$menu_id = 'new-order-notify';
    
    	$wp_admin_bar->add_menu(
    		array(
    			'id'     => $menu_id,
    			'parent' => null , // use 'top-secondary' for toggle menu position.
    			'href'   => admin_url( 'admin.php?page=custom-page-slug' ),
    			'title'  => __( 'New Order Notification', 'text-domain' ),
    		)
    	);
    	$wp_admin_bar->add_menu(
    		array(
    			'parent' => $menu_id,
    			'title'  => __( 'Disable', 'text-domain'  ),
    			'id'     => 'new-order-notification-disable',
    			'href'   => admin_url( 'admin.php?page=custom-submenu-slug' ),
    
    		)
    	);
    
    }
    add_action( 'admin_bar_menu', 'ci_admin_bar_item', 100 );

  3. Skip to note 8 content

    Add date and time to right side of the admin bar near the “Howdy” and avatar section

    I researched all day to figure out how to do this and wanted to share a working example to help save others some time and frustration.

    CAVEAT: This code is tested and verified it works as of Sept 2023. However, WordPress is always changing, so it is possible if you are reading this in ten years it may not be valid anymore.

    • $parent_slug : this is an id you make up. It should be self explanatory, in this case adminbar-date-time
    • top-secondary : tells WP to put this node / link / text on the right side
    • the 500 in add_action() : means keep it on the leftmost of that rightmost section
    • $local_time : uses the WP API current_time() function to grab the time and date for the timezone registered in Settings > General
    • $title : This the text that actually displays in the admin bar. Can be text, variables, and HTML. Here we calculate the date and time first as $local_time and the result of that variable is what will display in the admin bar. If we wanted we could do 'title' => __( 4 * 8 ), and 32 is what would be shown in the admin bar.
    • href : If you are making this a hyperlink then put the destination URL here. In this example, options-general.php is the Settings > General page so you can change time and date if you want
    add_action( 'admin_bar_menu', 'wpdocs_add_date_time_adminbar_right', 500 );
    function wpdocs_add_date_time_adminbar_right( WP_Admin_Bar $wp_admin_bar ) {
        $parent_slug = 'adminbar-date-time';
        $local_time  = date( 'Y-m-d, g:i a', current_time( 'timestamp', 0 ) );
    
        $wp_admin_bar->add_menu( array(
            'id'     => $parent_slug,
            'parent' => 'top-secondary',
            'group'  => null,
            'title'  => $local_time,
            'href'   => admin_url( '/options-general.php' ),
        ) );
    }

  4. Skip to note 10 content

    This is how you can add admin bar menus to the right side.

    add_action( 'admin_bar_menu', 'admin_bar_item', 500 );
    function admin_bar_menus( WP_Admin_Bar $wp_admin_bar ) {
    
        $parent_slug = 'license-manager-wppt';
    
        $wp_admin_bar->add_menu( array(
            'id'    => $parent_slug,
            'parent' => 'top-secondary',
            'group'  => null,
            'title' => __( 'License Manager', 'lmfwppt' ),
            'href'  => admin_url('admin.php?page=license-manager-wppt'),
        ) );
    
    }