阐述 WordPress `admin_menu` 钩子源码：它在后台管理页面的加载流程中处于哪个阶段，以及如何通过它添加自定义菜单。

晚上好，各位！欢迎来到今天的“WordPress 钩子漫游指南”系列讲座。今天咱们要扒一扒 WordPress 后台菜单的门道，核心主角就是 admin_menu 钩子。准备好迎接一场精彩的源码探险了吗？Let’s dive in!

一、后台加载“谍战片”：admin_menu 的登场时机

要理解 admin_menu 的作用，咱们得先了解 WordPress 后台加载的流程。可以把它想象成一部“谍战片”，每个阶段都有不同的角色和任务。

身份验证（Authentication）： 首先，WordPress 要确认你是谁，有没有权限进入后台。
核心加载（Core Loading）： 接着，加载 WordPress 的核心文件，包括各种函数、类和钩子。
插件加载（Plugins Loading）： 所有激活的插件开始加载，它们会注册自己的钩子，准备“埋伏”。
主题加载（Theme Loading）： 加载当前使用的主题。
后台初始化（Admin Initialization）： 这是关键时刻！WordPress 开始初始化后台界面，准备生成菜单。
admin_menu 钩子触发： 就在后台初始化阶段，admin_menu 钩子被触发！这是我们“动手脚”的最佳时机。
渲染后台界面（Admin Interface Rendering）： 最后，WordPress 根据我们添加到菜单中的信息，渲染出最终的后台界面。

用一张表格来总结一下：

阶段	描述
身份验证	确认用户身份和权限。
核心加载	加载 WordPress 核心文件。
插件加载	加载激活的插件。
主题加载	加载当前主题。
后台初始化	初始化后台界面，准备生成菜单。
`admin_menu` 钩子触发	我们的主角登场！在这个阶段，我们可以使用 `add_menu_page()`、`add_submenu_page()` 等函数，向后台添加自定义菜单和子菜单。
渲染后台界面	根据菜单信息，渲染最终的后台界面。

二、admin_menu 源码解剖：深入“敌后”

让我们看看 admin_menu 钩子在 WordPress 源码中是如何被使用的。你可以在 wp-admin/menu.php 文件中找到相关的代码。

在 wp-admin/admin.php (或者更早的加载过程中)中，你会看到类似这样的代码：

do_action( 'admin_menu' );

这行代码就是 admin_menu 钩子被触发的地方。do_action() 函数会执行所有绑定到 admin_menu 钩子上的函数。换句话说，所有插件和主题中通过 add_action( 'admin_menu', 'your_function' ); 注册的函数，都会在这个时候被调用。

三、添加自定义菜单：我们的“秘密武器”

现在，让我们看看如何利用 admin_menu 钩子，添加我们自己的菜单。WordPress 提供了几个关键的函数：

add_menu_page()：添加一个顶级的菜单项。
add_submenu_page()：添加一个子菜单项。

1. add_menu_page()：创建顶级菜单

add_menu_page() 函数的语法如下：

add_menu_page(
    string   $page_title,
    string   $menu_title,
    string   $capability,
    string   $menu_slug,
    callable $function = '',
    string   $icon_url = '',
    int      $position = null
);

$page_title：页面标题，显示在浏览器的标签页上。
$menu_title：菜单标题，显示在后台菜单中。
$capability：用户需要具备的权限才能访问该菜单。例如 'manage_options' 只有管理员才能访问。
$menu_slug：菜单的唯一标识符，用于生成 URL。
$function：点击菜单后执行的函数，用于渲染页面内容。
$icon_url：菜单的图标 URL。可以是 WordPress 自带的 Dashicons，也可以是自定义的图片 URL。
$position：菜单在后台菜单中的位置。数字越小，位置越靠前。

示例代码：

function my_custom_menu() {
    add_menu_page(
        '我的自定义页面标题',          // 页面标题
        '我的菜单',             // 菜单标题
        'manage_options',       // 权限
        'my-custom-menu',       // 菜单 Slug
        'my_custom_page_content', // 回调函数
        'dashicons-admin-tools',  // 图标
        25                       // 位置
    );
}
add_action( 'admin_menu', 'my_custom_menu' );

function my_custom_page_content() {
    echo '<h1>欢迎来到我的自定义页面！</h1>';
    echo '<p>这里可以放任何你想要的内容。</p>';
}

这段代码做了什么？

my_custom_menu() 函数负责调用 add_menu_page() 函数，添加菜单。
my_custom_page_content() 函数负责渲染页面的内容。

2. add_submenu_page()：添加子菜单

add_submenu_page() 函数的语法如下：

add_submenu_page(
    string   $parent_slug,
    string   $page_title,
    string   $menu_title,
    string   $capability,
    string   $menu_slug,
    callable $function = ''
);

$parent_slug：父菜单的 Slug，也就是你想把子菜单添加到哪个菜单下面。
$page_title：页面标题，显示在浏览器的标签页上。
$menu_title：菜单标题，显示在后台菜单中。
$capability：用户需要具备的权限才能访问该菜单。
$menu_slug：菜单的唯一标识符，用于生成 URL。
$function：点击菜单后执行的函数，用于渲染页面内容。

示例代码：

function my_custom_submenu() {
    add_submenu_page(
        'my-custom-menu',       // 父菜单 Slug
        '我的自定义子页面标题',        // 页面标题
        '我的子菜单',           // 菜单标题
        'manage_options',       // 权限
        'my-custom-submenu',    // 菜单 Slug
        'my_custom_submenu_content' // 回调函数
    );
}
add_action( 'admin_menu', 'my_custom_submenu' );

function my_custom_submenu_content() {
    echo '<h1>欢迎来到我的自定义子页面！</h1>';
    echo '<p>这里是子页面的内容。</p>';
}

这段代码会在 my-custom-menu 这个顶级菜单下添加一个子菜单。

四、权限管理：确保安全第一

$capability 参数非常重要，它可以控制哪些用户可以访问你的菜单。WordPress 提供了很多内置的权限，例如：

Capability	描述
`manage_options`	管理选项。只有管理员才能拥有这个权限。
`edit_posts`	编辑文章。
`publish_posts`	发布文章。
`read`	阅读。所有登录用户都有这个权限。
`edit_pages`	编辑页面。
`upload_files`	上传文件。

你可以根据你的需求选择合适的权限。如果你想自定义权限，可以使用 add_cap() 函数。

五、Dashicons：让你的菜单更漂亮

$icon_url 参数可以让你为菜单添加图标。WordPress 自带了一套名为 Dashicons 的图标库，你可以在 https://developer.wordpress.org/resource/dashicons/ 找到所有可用的图标。

使用 Dashicons 非常简单，只需要在 $icon_url 参数中传入 dashicons-图标名称 即可。例如，'dashicons-admin-tools'。

六、位置控制：让菜单井然有序

$position 参数可以让你控制菜单在后台菜单中的位置。数字越小，位置越靠前。WordPress 已经占用了一些位置，例如：

位置	菜单
5	文章
10	媒体
20	页面
25	评论
60	外观
65	插件
70	用户
75	工具
80	设置

你可以选择一个没有被占用的位置，或者在已有的位置之间插入你的菜单。

七、高级技巧：动态菜单和条件判断

有时候，你可能需要根据不同的条件，动态地添加菜单。例如，只有在某个插件激活时，才显示某个菜单。

你可以使用 is_plugin_active() 函数来判断插件是否激活，然后根据结果来决定是否添加菜单。

示例代码：

function my_conditional_menu() {
    if ( is_plugin_active( 'my-plugin/my-plugin.php' ) ) {
        add_menu_page(
            '我的条件菜单标题',          // 页面标题
            '我的条件菜单',             // 菜单标题
            'manage_options',       // 权限
            'my-conditional-menu',  // 菜单 Slug
            'my_conditional_page_content', // 回调函数
            'dashicons-admin-tools',  // 图标
            25                       // 位置
        );
    }
}
add_action( 'admin_menu', 'my_conditional_menu' );

function my_conditional_page_content() {
    echo '<h1>欢迎来到我的条件菜单页面！</h1>';
    echo '<p>只有在 my-plugin 插件激活时，才能看到这个页面。</p>';
}

八、常见问题与解决方案

菜单不显示：
- 检查你的代码是否有语法错误。
- 检查你的权限是否正确。
- 检查你的 $position 参数是否与其他菜单冲突。
- 确保你的代码在 admin_menu 钩子触发之前执行。
菜单位置错乱：
- 调整 $position 参数的值，使其与其他菜单错开。
点击菜单后页面 404：
- 检查你的 $menu_slug 参数是否正确。
- 检查你的回调函数是否正确定义。
- 尝试刷新 WordPress 的 rewrite 规则。

九、最佳实践

将你的菜单代码放在一个独立的插件文件中，方便管理和维护。
使用有意义的 $menu_slug 和 $page_title，方便用户识别。
合理使用权限控制，确保只有授权用户才能访问你的菜单。
为你的菜单添加图标，使其更美观。
使用条件判断，动态地添加菜单，提高灵活性。

十、总结

admin_menu 钩子是 WordPress 后台菜单管理的核心。通过它，我们可以轻松地添加自定义菜单和子菜单，扩展 WordPress 的功能。掌握了 admin_menu 钩子的使用方法，你就可以像一位经验丰富的“特工”，在 WordPress 后台自由穿梭，打造属于你自己的定制化管理界面。

今天的讲座就到这里。希望大家能够通过今天的学习，对 admin_menu 钩子有更深入的了解。下次再见！

发表回复 取消回复

发表回复取消回复