分析 WordPress `wp_before_admin_bar_render` 钩子源码：如何通过它自定义管理员工具栏。

各位观众，早上好啊！ 今天咱们不聊风花雪月，聊点实在的——WordPress 管理员工具栏的自定义。你是不是也觉得那工具栏千篇一律，恨不得把它改成自己喜欢的模样？别急，今天就教你用 wp_before_admin_bar_render 这个神奇的钩子，让你的工具栏焕然一新！

一、什么是 WordPress 管理员工具栏？

首先，咱们得知道啥是管理员工具栏。 就是你登录 WordPress 后，出现在页面顶部的那个小条条，里面有一些常用的链接，比如编辑文章、后台管理、退出等等。 它方便快捷，但有时候也显得有点“大众脸”。

二、wp_before_admin_bar_render 钩子：改造工具栏的钥匙

这个钩子，顾名思义，就是在 WordPress 渲染管理员工具栏 之前 触发的。 也就是说，我们可以在它触发的时候，对工具栏进行修改，添加、删除、修改项目，随心所欲！

三、源码分析：一探究竟

wp_before_admin_bar_render 钩子位于 wp-includes/class-wp-admin-bar.php 文件中的 WP_Admin_Bar::render() 方法里。 简单来说，这个方法负责渲染工具栏。 在渲染之前，它会调用 do_action( 'wp_before_admin_bar_render' );，这就给了我们机会插手！

// wp-includes/class-wp-admin-bar.php (简化版)
public function render() {
    if ( ! $this->visible() ) {
        return;
    }

    /**
     * Fires before the admin bar is rendered.
     *
     * @since 3.1.0
     */
    do_action( 'wp_before_admin_bar_render' );

    // ... (后面是渲染工具栏的代码，我们暂时忽略)
}

看到 do_action() 了吗？ 这就意味着我们可以通过 add_action() 函数，把我们自己的函数挂载到这个钩子上，从而在工具栏渲染之前执行我们的代码。

四、实战演练：自定义工具栏

现在，让我们来点实际的，一步一步地自定义工具栏。

1. 添加自定义菜单项

这是最常见的需求，让我们在工具栏上添加一个指向自己网站的链接。

add_action( 'wp_before_admin_bar_render', 'add_custom_admin_bar_menu' );

function add_custom_admin_bar_menu() {
    global $wp_admin_bar;

    $wp_admin_bar->add_menu( array(
        'id'    => 'my-site-link', // 唯一ID，非常重要
        'title' => '我的网站',
        'href'  => 'https://www.example.com', // 你的网站地址
        'meta'  => array(
            'target' => '_blank', // 在新标签页打开
            'title'  => '访问我的网站', // 鼠标悬停时的提示
        ),
    ) );
}

这段代码做了什么？

• add_action( 'wp_before_admin_bar_render', 'add_custom_admin_bar_menu' );： 把 add_custom_admin_bar_menu 函数挂载到 wp_before_admin_bar_render 钩子上。
• add_custom_admin_bar_menu() 函数：
  • global $wp_admin_bar;： 获取全局的 $wp_admin_bar 对象，这是操作工具栏的关键。
  • $wp_admin_bar->add_menu()： 向工具栏添加一个新的菜单项。
    • id： 菜单项的唯一 ID，必须是唯一的，否则会出错。
    • title： 菜单项显示的文字。
    • href： 链接地址。
    • meta： 一些额外的属性，比如 target 和 title。

2. 添加子菜单

有时候，我们希望添加一个带有子菜单的父菜单。

add_action( 'wp_before_admin_bar_render', 'add_custom_admin_bar_menu_with_submenu' );

function add_custom_admin_bar_menu_with_submenu() {
    global $wp_admin_bar;

    // 添加父菜单
    $wp_admin_bar->add_menu( array(
        'id'    => 'my-parent-menu',
        'title' => '我的菜单',
        'href'  => '#', // 父菜单通常不跳转，用 # 代替
    ) );

    // 添加子菜单
    $wp_admin_bar->add_menu( array(
        'id'     => 'my-submenu-1',
        'title'  => '子菜单 1',
        'href'   => 'https://www.example.com/page1',
        'parent' => 'my-parent-menu', // 指定父菜单的 ID
    ) );

    $wp_admin_bar->add_menu( array(
        'id'     => 'my-submenu-2',
        'title'  => '子菜单 2',
        'href'   => 'https://www.example.com/page2',
        'parent' => 'my-parent-menu', // 同样指定父菜单的 ID
    ) );
}

关键点：

• parent： 子菜单的 parent 属性必须设置为父菜单的 id。

3. 修改现有菜单项

有时候，我们不需要添加新的菜单，只需要修改现有的菜单项。 比如，修改“WordPress”菜单的链接地址。

add_action( 'wp_before_admin_bar_render', 'modify_wordpress_admin_bar_menu' );

function modify_wordpress_admin_bar_menu() {
    global $wp_admin_bar;

    $wp_admin_bar->add_node( array(
        'id'    => 'wp-logo', // WordPress 菜单的 ID 是 wp-logo
        'href'  => 'https://www.my-custom-wordpress-site.com', // 修改后的链接地址
        'title' => '我的 WordPress', // 修改后的标题
    ) );
}

这里用到了 $wp_admin_bar->add_node() 方法。 注意，和 add_menu() 不同，add_node() 用于修改 现有 的菜单项。

4. 删除现有菜单项

如果你觉得某些菜单项碍眼，可以直接删除。

add_action( 'wp_before_admin_bar_render', 'remove_admin_bar_menu' );

function remove_admin_bar_menu() {
    global $wp_admin_bar;

    $wp_admin_bar->remove_menu( 'wp-logo' ); // 删除 WordPress 菜单
    $wp_admin_bar->remove_menu( 'updates' ); // 删除更新菜单
    // 可以删除更多你不需要的菜单项
}

$wp_admin_bar->remove_menu() 方法可以删除指定的菜单项，只需要提供菜单项的 id 即可。

5. 使用 CSS 自定义样式

光修改菜单内容还不够，我们还可以用 CSS 来美化工具栏。 WordPress 提供了一个专门的 CSS 类 admin-bar，我们可以针对这个类来编写 CSS 样式。

add_action( 'admin_head', 'custom_admin_bar_css' ); // 后台CSS
add_action( 'wp_head', 'custom_admin_bar_css' ); // 前台CSS

function custom_admin_bar_css() {
    echo '<style type="text/css">
        #wpadminbar {
            background: #333 !important;
        }
        #wpadminbar .ab-item {
            color: #fff !important;
        }
        #wpadminbar .ab-item:hover {
            background: #555 !important;
        }
    </style>';
}

这段代码会在后台和前台的 <head> 标签中插入一段 CSS 代码，用于修改工具栏的背景颜色和文字颜色。

五、注意事项

• ID 的唯一性： 每个菜单项的 id 必须是唯一的，否则会导致冲突。
• 优先级： add_action() 函数可以指定优先级，控制代码执行的顺序。 默认优先级是 10，数字越小，优先级越高。 如果你的代码没有生效，可以尝试调整优先级。
• 调试： 如果你的代码没有生效，可以用 var_dump() 或 error_log() 函数来调试，看看 $wp_admin_bar 对象的内容是否符合预期。
• 代码位置： 自定义工具栏的代码应该放在主题的 functions.php 文件中，或者放在自定义插件中。 推荐使用插件，这样即使更换主题，你的自定义代码也不会丢失。

六、总结

咱们来总结一下今天讲的内容：

操作	方法	描述
添加菜单项	$wp_admin_bar->add_menu()	添加一个新的菜单项。
添加子菜单	$wp_admin_bar->add_menu() (设置 parent)	添加一个子菜单，需要指定父菜单的 id。
修改菜单项	$wp_admin_bar->add_node()	修改现有的菜单项。
删除菜单项	$wp_admin_bar->remove_menu()	删除指定的菜单项。
自定义样式	CSS (针对 admin-bar 类)	使用 CSS 修改工具栏的样式。
钩子名称	wp_before_admin_bar_render	在渲染工具栏 之前 触发的钩子。
核心对象	$wp_admin_bar	用于操作工具栏的对象，通过 global $wp_admin_bar; 获取。

七、更高级的玩法

• 根据用户角色显示不同的菜单： 可以使用 current_user_can() 函数来判断当前用户的角色，然后根据角色显示不同的菜单项。
• 动态生成菜单： 可以从数据库或其他数据源中读取数据，然后动态生成菜单项。
• 使用 JavaScript 交互： 可以在菜单项中添加 JavaScript 代码，实现更复杂的交互效果。

八、示例：根据用户角色显示不同的菜单

add_action( 'wp_before_admin_bar_render', 'customize_admin_bar_for_roles' );

function customize_admin_bar_for_roles() {
    global $wp_admin_bar;

    if ( current_user_can( 'administrator' ) ) {
        // 管理员
        $wp_admin_bar->add_menu( array(
            'id'    => 'admin-menu',
            'title' => '管理员菜单',
            'href'  => '#',
        ) );
    } elseif ( current_user_can( 'editor' ) ) {
        // 编辑
        $wp_admin_bar->add_menu( array(
            'id'    => 'editor-menu',
            'title' => '编辑菜单',
            'href'  => '#',
        ) );
    } else {
        // 其他用户
        $wp_admin_bar->add_menu( array(
            'id'    => 'subscriber-menu',
            'title' => '普通用户菜单',
            'href'  => '#',
        ) );
    }
}

这段代码会根据用户的角色，显示不同的菜单项。

九、总结的总结

好了，今天的课程就到这里。 希望大家通过今天的学习，能够熟练地使用 wp_before_admin_bar_render 钩子，把 WordPress 管理员工具栏打造成自己喜欢的样子！ 记住，多实践，多尝试，才能真正掌握这些技巧。 祝大家编程愉快！

记住，编程的世界没有魔法，只有逻辑和耐心。 祝你早日成为 WordPress 工具栏改造大师！