剖析 WordPress `admin_bar_menu` 钩子源码：如何向管理员工具栏添加自定义菜单项。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位同学，大家好！今天咱们开一场小灶，专门聊聊WordPress后台那个让人又爱又恨的“管理员工具栏”。没错，就是你登录后台，页面最上方那个黑不溜秋的条条。它看起来不起眼，但能量巨大，是快速访问各种后台功能的入口。今天，咱们就一起扒开 admin_bar_menu 钩子的源码，看看怎么往这个工具栏里塞点自己的私货，打造一个更贴心的后台体验。

开胃小菜：什么是 admin_bar_menu？

首先，admin_bar_menu 是 WordPress 提供的一个 action 钩子 (action hook)。啥是 action hook？简单来说，它就像一个埋伏好的“钩子”，WordPress 在执行特定代码的时候会“抛出”这个钩子，允许你挂载自己的函数，执行一些定制化的操作。

admin_bar_menu 钩子就是在 WordPress 创建管理员工具栏菜单的时候被触发的。通过它，你可以添加、修改、甚至删除工具栏上的菜单项。

正餐：源码剖析与实战演练

咱们先来看看 WordPress 是怎么用 admin_bar_menu 钩子的：

/**
 * Filters the administration menu.
 *
 * @since 3.1.0
 *
 * @param WP_Admin_Bar $wp_admin_bar WP_Admin_Bar instance, passed by reference.
 */
function wp_admin_bar_render( $wp_admin_bar ) {
    /**
     * Fires before the administration bar is rendered.
     *
     * @since 3.1.0
     */
    do_action( 'wp_before_admin_bar_render' );

    $root_id = 'root-default';

    $wp_admin_bar->add_menu( array(
        'id'    => $root_id,
        'group' => true,
    ) );

    $wp_admin_bar->add_menu( array(
        'id'    => 'wp-logo',
        'title' => '<span class="ab-icon"></span><span class="screen-reader-text">' . __( 'About WordPress' ) . '</span>',
        'href'  => get_admin_url( '', 'about.php' ),
        'group' => true,
    ) );

    // Add the WordPress menu items
    $wp_admin_bar->add_menu( array(
        'id'     => 'about',
        'title'  => __( 'About WordPress' ),
        'href'   => get_admin_url( '', 'about.php' ),
        'parent' => 'wp-logo',
    ) );
    // 更多默认菜单项...

    /**
     * Fires after the administration bar is rendered.
     *
     * @since 3.1.0
     */
    do_action( 'wp_after_admin_bar_render' );
}

这段代码位于 wp-includes/admin-bar.php 文件中（具体位置可能因为版本不同而略有差异）。简化来说，这个函数主要做了这几件事：

触发 wp_before_admin_bar_render 钩子：允许你在工具栏渲染之前做一些操作。
创建根节点：也就是工具栏的“骨架”。
添加 WordPress Logo 和 “关于 WordPress” 菜单。
触发 wp_after_admin_bar_render 钩子：允许你在工具栏渲染之后做一些操作。

关键在于，这个函数接收一个 $wp_admin_bar 对象，这是一个 WP_Admin_Bar 类的实例，它提供了 add_menu() 方法，用来添加菜单项。

实战1：添加一个简单的菜单项

现在，咱们就来动手添加一个自己的菜单项。假设你想在工具栏上添加一个“我的网站”链接，直接跳转到你的网站首页。

add_action( 'admin_bar_menu', 'add_my_website_menu', 999 ); // 999 是优先级，确保我们的菜单在最后显示

function add_my_website_menu( $wp_admin_bar ) {
    $args = array(
        'id'    => 'my_website', // 菜单项的唯一ID，很重要！
        'title' => '我的网站',   // 菜单项显示的文字
        'href'  => get_home_url(), // 链接地址
        'meta'  => array(
            'class' => 'my-website-menu', // 可以添加CSS类
            'title' => '访问我的网站',    // 鼠标悬停时的提示文字
        ),
    );
    $wp_admin_bar->add_menu( $args );
}

把这段代码放到你的主题的 functions.php 文件里（或者一个自定义插件里），刷新后台，你应该就能在工具栏上看到“我的网站”这个菜单项了。

代码解释：

add_action( 'admin_bar_menu', 'add_my_website_menu', 999 );：把 add_my_website_menu 函数挂载到 admin_bar_menu 钩子上。 999 是优先级，数字越大，执行顺序越晚，这样可以确保你的菜单项显示在靠后的位置，避免被其他插件覆盖。
add_my_website_menu( $wp_admin_bar )：这是你的自定义函数，接收 $wp_admin_bar 对象。
$args：一个数组，包含了菜单项的各种属性。
- id：菜单项的唯一ID，必须是唯一的，否则可能会冲突。
- title：菜单项显示的文字。
- href：点击菜单项跳转的链接地址。
- meta：一个数组，可以添加额外的属性，比如 CSS 类 (class) 和鼠标悬停时的提示文字 (title)。
$wp_admin_bar->add_menu( $args );：调用 $wp_admin_bar 对象的 add_menu() 方法，把你的菜单项添加到工具栏上。

实战2：添加一个带子菜单的菜单项

光有单调的链接怎么够？咱们来添加一个带子菜单的菜单项，就像 WordPress 默认的“站点”菜单那样。

add_action( 'admin_bar_menu', 'add_my_menu_with_submenu', 999 );

function add_my_menu_with_submenu( $wp_admin_bar ) {
    // 添加父菜单
    $args = array(
        'id'    => 'my_main_menu',
        'title' => '我的菜单',
        'href'  => '#', // 父菜单通常不直接跳转，可以设置为 '#'
        'meta'  => array(
            'title' => '我的菜单',
        ),
    );
    $wp_admin_bar->add_menu( $args );

    // 添加子菜单项 1
    $args = array(
        'id'     => 'my_submenu_1',
        'title'  => '子菜单 1',
        'href'   => admin_url( 'admin.php?page=my_custom_page' ), // 跳转到自定义页面
        'parent' => 'my_main_menu', // 关键：指定父菜单的 ID
        'meta'   => array(
            'title' => '子菜单 1',
        ),
    );
    $wp_admin_bar->add_menu( $args );

    // 添加子菜单项 2
    $args = array(
        'id'     => 'my_submenu_2',
        'title'  => '子菜单 2',
        'href'   => get_home_url() . '/my-custom-page', // 跳转到前端页面
        'parent' => 'my_main_menu', // 关键：指定父菜单的 ID
        'meta'   => array(
            'title' => '子菜单 2',
        ),
    );
    $wp_admin_bar->add_menu( $args );
}

代码解释：

添加父菜单： id 为 my_main_menu，href 设置为 #，表示不直接跳转。
添加子菜单： parent 属性是关键！把它设置为父菜单的 id (my_main_menu)，就告诉 WordPress，这个菜单项是父菜单的子菜单。

实战3：修改现有的菜单项

除了添加菜单项，你还可以修改现有的菜单项。比如，你想修改 WordPress 默认的“站点”菜单的标题。

add_action( 'admin_bar_menu', 'modify_site_menu', 999 );

function modify_site_menu( $wp_admin_bar ) {
    $wp_admin_bar->add_menu( array(
        'id'    => 'site-name', // WordPress 默认的“站点”菜单的 ID
        'title' => '我的站点',   // 修改后的标题
        'meta'  => array(
            'title' => '访问我的站点',
        ),
    ) );
}

注意：

要修改菜单项，你需要知道它的 id。你可以通过浏览 WordPress 源码或者使用浏览器的开发者工具来找到菜单项的 id。
修改菜单项本质上是使用相同的 id 重新添加一个菜单项，新的菜单项会覆盖旧的菜单项。

实战4：删除现有的菜单项

如果你觉得某些菜单项碍眼，想把它从工具栏上移除，也很简单。

add_action( 'admin_bar_menu', 'remove_site_menu', 999 );

function remove_site_menu( $wp_admin_bar ) {
    $wp_admin_bar->remove_menu( 'site-name' ); // WordPress 默认的“站点”菜单的 ID
}

注意：

同样，你需要知道要删除的菜单项的 id。
remove_menu() 方法会直接从工具栏上移除指定的菜单项。

高级技巧：添加自定义 CSS 样式

想要让你的菜单项更个性化？可以通过 meta 属性添加自定义 CSS 类，然后编写 CSS 样式来美化它。

add_action( 'admin_bar_menu', 'add_my_styled_menu', 999 );

function add_my_styled_menu( $wp_admin_bar ) {
    $args = array(
        'id'    => 'my_styled_menu',
        'title' => '个性菜单',
        'href'  => '#',
        'meta'  => array(
            'class' => 'my-styled-menu', // 添加自定义 CSS 类
        ),
    );
    $wp_admin_bar->add_menu( $args );
}

然后在你的主题的 style.css 文件中添加 CSS 样式：

#wp-admin-bar-my_styled_menu a {
    color: #ff0000 !important; /* 红色文字 */
    font-weight: bold !important; /* 加粗 */
}

注意：

工具栏的 CSS 样式比较特殊，你需要使用 #wp-admin-bar-菜单ID a 这样的选择器来覆盖默认样式。
!important 可以确保你的样式生效，避免被其他样式覆盖。

总结：admin_bar_menu 的核心要点

为了方便大家记忆，我把 admin_bar_menu 的核心要点整理成一个表格：

关键点	说明
`admin_bar_menu`	一个 action hook，在 WordPress 创建管理员工具栏菜单时触发。
`$wp_admin_bar`	`WP_Admin_Bar` 类的实例，提供了添加、修改、删除菜单项的方法。
`add_menu()`	`WP_Admin_Bar` 类的方法，用于添加菜单项。
`remove_menu()`	`WP_Admin_Bar` 类的方法，用于删除菜单项。
`id`	菜单项的唯一 ID，非常重要！用于修改、删除菜单项，以及指定父菜单。
`title`	菜单项显示的文字。
`href`	菜单项点击后跳转的链接地址。
`parent`	子菜单的父菜单 ID，用于创建带子菜单的菜单项。
`meta`	一个数组，用于添加额外的属性，比如 CSS 类 (`class`) 和鼠标悬停时的提示文字 (`title`)。
优先级 (Priority)	使用 `add_action()` 函数时可以指定优先级，数字越大，执行顺序越晚。通常使用 `999` 确保你的菜单项显示在靠后的位置，避免被其他插件覆盖。

注意事项：

冲突问题： 不同的插件可能会同时修改工具栏，导致冲突。使用优先级可以缓解这个问题，但不能完全避免。最好的办法是仔细测试，确保你的代码与其他插件兼容。
版本兼容性： WordPress 的 API 可能会在不同版本之间发生变化。在编写代码时，要注意版本兼容性，避免在旧版本或新版本上出现问题。
缓存问题： 修改工具栏后，可能需要清除缓存才能看到效果。

总结陈词：

好了，今天的“管理员工具栏改造计划”就到这里了。希望通过今天的讲解，大家能够掌握 admin_bar_menu 钩子的使用方法，打造一个更符合自己需求的 WordPress 后台。记住，代码是最好的老师，多动手实践，才能真正掌握这些技巧。如果你还有什么问题，欢迎随时提问！

下次咱们再聊点更有意思的 WordPress 黑科技！拜拜！

发表回复 取消回复

发表回复取消回复