深入理解 WordPress `add_submenu_page()` 函数源码：如何注册子菜单并将其与顶级菜单关联。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位听众，各位未来的WordPress大师们，早上好/下午好/晚上好！（取决于你读到这段文字的时间）。今天咱们不开玩笑，直接进入正题：深入挖掘WordPress的add_submenu_page()函数，看看它是如何魔法般地把子菜单挂载到顶级菜单下面的。

一、 add_submenu_page()：你的子菜单制造机

首先，咱们要认识一下今天的主角——add_submenu_page()函数。这家伙，说白了，就是个子菜单制造机。它的作用是：在一个已有的顶级菜单项下，添加一个新的子菜单项。

add_submenu_page()的基本语法如下：

<?php
add_submenu_page(
    string   $parent_slug,
    string   $page_title,
    string   $menu_title,
    string   $capability,
    string   $menu_slug,
    callable $callback = ''
);
?>

是不是觉得参数有点多？别怕，咱们一个个拆解：

参数名	类型	描述
`$parent_slug`	string	顶级菜单的slug。这是最关键的参数，它告诉WordPress你想把这个子菜单挂载到哪个顶级菜单下面。这个slug必须与已存在的顶级菜单的slug完全匹配。
`$page_title`	string	页面的标题。这个标题会显示在浏览器的标签页上，或者在管理界面的面包屑导航中。
`$menu_title`	string	菜单的标题。这个标题就是你在WordPress后台菜单里看到的文字。
`$capability`	string	用户权限。只有具备相应权限的用户才能看到和访问这个子菜单。常用的权限有`manage_options`(管理员权限), `edit_posts`(编辑文章的权限)等等。
`$menu_slug`	string	菜单的slug。这个slug是子菜单的唯一标识符，也是URL的一部分。注意，这个slug必须是唯一的，否则可能会和其他菜单冲突。
`$callback`	callable	回调函数。当用户点击这个子菜单时，WordPress会执行这个回调函数。你可以在这个函数里编写你的页面内容，比如显示表单、处理数据等等。如果省略这个参数，WordPress会尝试加载一个名为`{$menu_slug}.php`的文件。

二、实例演示：给“工具”菜单添加一个子菜单

理论说了一堆，不如来点实际的。咱们来给WordPress后台的“工具”菜单添加一个名为“我的工具”的子菜单。

<?php
add_action( 'admin_menu', 'my_custom_submenu_page' );

function my_custom_submenu_page() {
    add_submenu_page(
        'tools.php',             // 顶级菜单的slug (这里是 "工具" 菜单)
        '我的工具页面标题',      // 页面的标题
        '我的工具',              // 菜单的标题
        'manage_options',        // 用户权限 (管理员)
        'my-custom-submenu-page', // 菜单的slug
        'my_custom_submenu_page_callback' // 回调函数
    );
}

function my_custom_submenu_page_callback() {
    echo '<div class="wrap">';
    echo '<h1>我的工具页面</h1>';
    echo '<p>这里是我的工具页面的内容。</p>';
    echo '</div>';
}
?>

这段代码做了什么呢？

add_action( 'admin_menu', 'my_custom_submenu_page' );: 这行代码告诉WordPress，当admin_menu这个钩子被触发时（也就是WordPress后台菜单生成的时候），执行my_custom_submenu_page函数。
my_custom_submenu_page(): 这个函数负责调用add_submenu_page()来注册子菜单。
- 'tools.php'：指定了顶级菜单的slug为tools.php，对应的是WordPress后台的“工具”菜单。注意，这个tools.php是“工具”菜单的真实slug，而不是你在后台看到的“工具”两个字。你可以在浏览器开发者工具中查看“工具”菜单的链接，就能找到这个slug。
- '我的工具页面标题'：设置了页面的标题，会在浏览器的标签页上显示。
- '我的工具'：设置了菜单的标题，会在后台菜单里显示。
- 'manage_options'：设置了用户权限，只有管理员才能看到这个子菜单。
- 'my-custom-submenu-page'：设置了菜单的slug，用于生成URL。访问这个子菜单的URL将会是wp-admin/tools.php?page=my-custom-submenu-page。
- 'my_custom_submenu_page_callback'：设置了回调函数，当用户点击这个子菜单时，WordPress会执行这个函数。
my_custom_submenu_page_callback(): 这个函数负责显示子菜单页面的内容。这里只是简单地输出了一个标题和一段文字。你可以根据自己的需求，在这个函数里编写更复杂的内容。

把这段代码放到你的主题的functions.php文件中，或者放到一个自定义的插件里，然后刷新你的WordPress后台，你就会在“工具”菜单下面看到一个新的子菜单“我的工具”了！

三、源码剖析：add_submenu_page()的内部运作

光会用还不够，咱们还要深入了解add_submenu_page()的内部运作机制。这样才能更好地理解它，更好地使用它。

add_submenu_page()函数位于wp-admin/includes/plugin.php文件中。它的核心功能是：

构建菜单项的URL: add_submenu_page()会根据$parent_slug和$menu_slug参数，构建子菜单的URL。
将菜单项添加到全局变量$submenu: WordPress使用一个名为$submenu的全局变量来存储所有的子菜单项。add_submenu_page()会将新的子菜单项添加到$submenu数组中，并以$parent_slug作为键。
处理回调函数: add_submenu_page()会检查$callback参数是否为空。如果为空，它会尝试加载一个名为{$menu_slug}.php的文件。如果不为空，它会将$callback函数注册到admin_page_{$menu_slug}动作钩子上。

咱们来看一下add_submenu_page()的简化版源码（为了方便理解，我省略了一些不重要的代码）：

<?php
function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '' ) {
    global $submenu;

    $menu_slug = sanitize_key( $menu_slug ); // 清理菜单slug，防止注入攻击

    // 构建菜单项的URL
    $hookname = get_plugin_page_hookname( $menu_slug, $parent_slug ); // 获取插件页面的钩子名称
    if ( empty( $callback ) && ! empty( $hookname ) ) {
        add_action( $hookname, 'plugin_php_self_check' );
        $callback = create_function( '', 'return;' ); // 创建一个空函数
    }

    // 将菜单项添加到全局变量 $submenu
    $submenu[ $parent_slug ][] = array( $menu_title, $capability, $menu_slug, $page_title );

    // 处理回调函数
    if ( ! empty( $callback ) ) {
        add_action( $hookname, $callback );
    }

    return $hookname;
}
?>

这段代码虽然简化了，但已经包含了add_submenu_page()的核心逻辑。

global $submenu;: 声明使用全局变量$submenu。
sanitize_key( $menu_slug );: 对菜单slug进行清理，防止注入攻击。这是一个非常重要的安全措施。
$submenu[ $parent_slug ][] = array( $menu_title, $capability, $menu_slug, $page_title );: 这是最关键的一行代码。它将子菜单项添加到$submenu数组中。$parent_slug是顶级菜单的slug，$menu_title是菜单的标题，$capability是用户权限，$menu_slug是菜单的slug，$page_title是页面的标题。
add_action( $hookname, $callback );: 这行代码将回调函数注册到admin_page_{$menu_slug}动作钩子上。当用户点击这个子菜单时，WordPress会触发这个钩子，并执行$callback函数。

四、高级技巧：add_submenu_page()的各种用法

掌握了add_submenu_page()的基本用法，咱们再来学习一些高级技巧，让你的子菜单更加灵活。

使用不同的用户权限: 你可以根据不同的需求，设置不同的用户权限。例如，只允许编辑人员访问某个子菜单，或者只允许特定角色的用户访问某个子菜单。

<?php
add_submenu_page(
    'tools.php',
    '我的工具页面标题',
    '我的工具',
    'edit_posts', // 只有编辑人员才能访问
    'my-custom-submenu-page',
    'my_custom_submenu_page_callback'
);
?>

使用自定义的回调函数: 你可以编写自定义的回调函数，来实现更复杂的功能。例如，显示一个表单，让用户输入数据，然后将数据保存到数据库中。

<?php
function my_custom_submenu_page_callback() {
    ?>
    <div class="wrap">
        <h1>我的工具页面</h1>
        <form method="post" action="">
            <label for="my_option">我的选项：</label>
            <input type="text" name="my_option" id="my_option" value="<?php echo get_option( 'my_option' ); ?>">
            <?php submit_button( '保存' ); ?>
        </form>
    </div>
    <?php

    if ( $_SERVER['REQUEST_METHOD'] == 'POST' ) {
        update_option( 'my_option', $_POST['my_option'] );
        echo '<div class="updated"><p>选项已保存！</p></div>';
    }
}
?>

使用admin_head-{$hookname}钩子: 你可以使用admin_head-{$hookname}钩子，在子菜单页面中添加自定义的CSS和JavaScript代码。{$hookname}是add_submenu_page()函数返回的钩子名称。

<?php
add_action( 'admin_menu', 'my_custom_submenu_page' );

function my_custom_submenu_page() {
    $hookname = add_submenu_page(
        'tools.php',
        '我的工具页面标题',
        '我的工具',
        'manage_options',
        'my-custom-submenu-page',
        'my_custom_submenu_page_callback'
    );

    add_action( 'admin_head-' . $hookname, 'my_custom_submenu_page_scripts' );
}

function my_custom_submenu_page_scripts() {
    ?>
    <style>
        .wrap h1 {
            color: red;
        }
    </style>
    <script>
        alert( 'Hello from my custom submenu page!' );
    </script>
    <?php
}
?>

五、常见问题与注意事项

在使用add_submenu_page()时，有一些常见问题需要注意：

顶级菜单的slug必须正确: 这是最容易出错的地方。如果你输入的$parent_slug不正确，子菜单就无法挂载到正确的顶级菜单下面。务必确认顶级菜单的slug是否正确，可以使用开发者工具查看。
菜单的slug必须唯一: 如果你使用的$menu_slug与其他菜单冲突，可能会导致菜单显示不正确，或者出现其他错误。建议使用一个具有唯一性的slug，例如使用你的插件或主题的名称作为前缀。
用户权限必须合理: 如果你设置的用户权限过高，可能会导致一些不必要的安全风险。建议只授予用户必要的权限。
注意安全: 在处理用户输入的数据时，一定要注意安全。使用sanitize_text_field()、esc_attr()等函数来清理和转义用户输入的数据，防止XSS攻击。

六、总结

今天，咱们深入学习了WordPress的add_submenu_page()函数。我们了解了它的基本语法、内部运作机制，以及一些高级技巧。希望这些知识能够帮助你更好地开发WordPress插件和主题，打造更加强大的WordPress后台管理界面。

记住，编程就像练武，光说不练假把式。赶快动手实践一下，把今天学到的知识应用到你的项目中吧！如果你在实践过程中遇到任何问题，欢迎随时向我提问。

祝大家编程愉快！咱们下次再见！

发表回复 取消回复

发表回复取消回复