发布于 由admin

分析 WordPress `add_options_page()` 函数的源码：如何注册一个通用的设置页面。

各位观众老爷，欢迎来到今天的WordPress源码分析小讲堂！今天咱们要聊的是add_options_page()这个函数，它可是WordPress后台设置页面的基石之一。说白了，就是教你怎么在WordPress后台搞一个属于你自己的设置页面，让用户可以自定义插件或者主题的行为。

废话不多说，咱们直接上源码，然后一点一点啃透它！

add_options_page() 源码剖析

在wp-admin/includes/plugin.php文件中，你能找到add_options_page()的芳踪。它的原型是这样的：

function add_options_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $callback, int $position = null ) {
    global $wp_menu;

    $hookname = get_plugin_page_hookname( $menu_slug, 'admin.php' );

    if ( empty( $hookname ) ) {
        return false;
    }

    $page_hook = add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );

    if ( ! empty( $page_hook ) ) {
        add_action( $hookname, $callback );
        return $page_hook;
    }

    return false;
}

是不是看起来有点眼花缭乱？别怕，咱们慢慢来，像剥洋葱一样，一层一层地扒开它。

参数详解：

| 参数名 | 类型 | 描述 |
| :———— | :—– | :————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————取自官方文档

1. $page_title (页面标题):

这个参数定义了当你的设置页面被激活时，浏览器顶部显示的标题。

2. $menu_title (菜单标题):

这个参数定义了在WordPress管理菜单中，你的设置页面显示的文本。比如，你会看到“我的插件设置”这样的链接。

3. $capability (权限):

这个参数决定了哪些用户可以访问你的设置页面。WordPress有一套权限系统，比如'manage_options'，通常是管理员才有的权限。

4. $menu_slug (菜单别名):

这个参数是页面的唯一标识符。它会成为URL的一部分，比如options-general.php?page=my-plugin-settings。

5. $callback (回调函数):

这个参数是一个函数名，当你的设置页面被加载时，这个函数会被调用。你可以在这个函数里编写你的设置页面内容和逻辑。

6. $position (位置，可选):

这个参数允许你指定你的设置页面在“设置”菜单中的位置。如果你不指定，WordPress会自动把它放在最后。

源码逻辑解读：

  1. get_plugin_page_hookname( $menu_slug, 'admin.php' ): 这一行代码根据你提供的$menu_slug生成一个钩子名称。这个钩子名称是WordPress内部用来触发你的回调函数的。

  2. add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position ): 这一行才是关键！它调用了add_submenu_page()函数，将你的设置页面添加到“设置”菜单下。'options-general.php' 表示父级菜单是“设置”。

  3. add_action( $hookname, $callback ): 这一行将你的回调函数绑定到之前生成的钩子上。当WordPress加载你的设置页面时，它会触发这个钩子，从而执行你的回调函数。

简单来说，add_options_page()做了两件事：

  • 在“设置”菜单下添加一个子菜单项。
  • 将你的回调函数绑定到这个子菜单项对应的页面上。

实战演练：

光说不练假把式，咱们来写一个简单的插件，演示一下add_options_page()的用法。

  1. 创建插件文件：

    在wp-content/plugins/目录下创建一个文件夹，比如my-plugin，然后在里面创建一个PHP文件，比如my-plugin.php。

  2. 编写插件代码：

    <?php
/**
 * Plugin Name: My Awesome Plugin
 * Description: A simple plugin to demonstrate add_options_page()
 * Version: 1.0.0
 * Author: Your Name
 */

// 避免直接访问文件
if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

// 添加菜单项
add_action( 'admin_menu', 'my_plugin_add_options_page' );

function my_plugin_add_options_page() {
    add_options_page(
        'My Plugin Settings', // 页面标题
        'My Plugin',         // 菜单标题
        'manage_options',    // 权限
        'my-plugin-settings', // 菜单别名
        'my_plugin_settings_page' // 回调函数
    );
}

// 设置页面内容
function my_plugin_settings_page() {
    ?>
    <div class="wrap">
        <h1>My Plugin Settings</h1>
        <p>Welcome to my plugin settings page!</p>

        <form method="post" action="options.php">
            <?php
                settings_fields( 'my_plugin_options' );
                do_settings_sections( 'my-plugin-settings' );
                submit_button();
            ?>
        </form>
    </div>
    <?php
}

// 注册设置
add_action( 'admin_init', 'my_plugin_register_settings' );

function my_plugin_register_settings() {
    register_setting( 'my_plugin_options', 'my_plugin_option_name' );

    add_settings_section(
        'my_plugin_section',
        'My Plugin Section Title',
        'my_plugin_section_callback',
        'my-plugin-settings'
    );

    add_settings_field(
        'my_plugin_field',
        'My Plugin Field Label',
        'my_plugin_field_callback',
        'my-plugin-settings',
        'my_plugin_section'
    );
}

function my_plugin_section_callback() {
    echo '<p>Introduction to this section.</p>';
}

function my_plugin_field_callback() {
    $option = get_option( 'my_plugin_option_name' );
    ?>
    <input type="text" name="my_plugin_option_name" value="<?php echo esc_attr( $option ); ?>">
    <?php
}

  3. 激活插件：

    登录你的WordPress后台，找到“插件”菜单，激活“My Awesome Plugin”。

  4. 访问设置页面：

    现在，你应该能在“设置”菜单下看到一个名为“My Plugin”的子菜单项。点击它，就能看到你的设置页面了！

代码解释：

  • add_action( 'admin_menu', 'my_plugin_add_options_page' ): 这个钩子会在后台菜单加载时被触发。
  • my_plugin_add_options_page(): 这个函数调用add_options_page()来添加菜单项。
  • my_plugin_settings_page(): 这个函数是设置页面的内容。这里只是一个简单的示例，你可以根据自己的需求添加各种表单元素和逻辑。
  • add_action( 'admin_init', 'my_plugin_register_settings' ): admin_init hook 用于注册设置、添加设置区域和设置字段。
  • register_setting( 'my_plugin_options', 'my_plugin_option_name' ): 注册一个设置，这告诉WordPress保存选项。
  • add_settings_section(): 添加一个设置区域，通常用于组织相关的设置字段。
  • add_settings_field(): 添加一个设置字段，例如文本框、复选框等。
  • settings_fields( 'my_plugin_options' ): 输出隐藏的表单字段，用于验证表单的来源。
  • do_settings_sections( 'my-plugin-settings' ): 输出所有已注册的设置区域和字段。
  • submit_button(): 输出提交按钮。

深入探讨：

  • 权限管理：

    $capability参数非常重要。你需要根据你的插件的功能，选择合适的权限。常用的权限有：

    • 'manage_options': 管理选项，通常是管理员才有的权限。
    • 'edit_posts': 编辑文章的权限。
    • 'edit_pages': 编辑页面的权限。
    • 'read': 阅读权限。

    具体使用哪个权限，取决于你的设置页面需要哪些用户才能访问。

  • 设置API：

    上面的例子中，我们使用了WordPress的设置API来保存设置。这是一个非常强大的工具，可以帮助你轻松地管理设置。

    设置API主要包括以下几个函数：

    • register_setting(): 注册一个设置。
    • add_settings_section(): 添加一个设置区域。
    • add_settings_field(): 添加一个设置字段。
    • settings_fields(): 输出隐藏的表单字段。
    • do_settings_sections(): 输出所有已注册的设置区域和字段。

    使用设置API的好处是，WordPress会自动处理数据的验证、清理和保存。你只需要关注如何显示和处理数据即可。

  • 选项组 (Option Group):

    register_setting() 的第一个参数 my_plugin_options 是一个选项组。 所有与这个选项组关联的设置字段，例如 my_plugin_option_name，都会被保存在同一个选项数组中。 当你调用 get_option( 'my_plugin_option_name' ) 时，WordPress实际上会返回 my_plugin_options 数组中与键 my_plugin_option_name 对应的值。

  • 关于 options.php 的 action 属性:

    注意在 my_plugin_settings_page() 函数中的 <form> 标签，它的 action 属性被设置为 options.php。 这是WordPress内置的一个文件，专门用于处理设置的保存。 当你点击提交按钮时，表单数据会被发送到 options.php，然后WordPress会根据你注册的设置信息，自动保存数据。

  • 安全考虑：

    在处理用户输入时，一定要注意安全。使用esc_attr()函数来转义HTML属性，使用wp_kses_post()函数来过滤用户提交的内容，防止XSS攻击。

    <input type="text" name="my_plugin_option_name" value="<?php echo esc_attr( get_option( 'my_plugin_option_name' ) ); ?>">

更高级的用法：

  • 添加多个设置页面：

    你可以多次调用add_options_page()来添加多个设置页面。

  • 使用自定义模板：

    你可以使用自定义的HTML模板来显示设置页面。

  • 添加AJAX支持：

    你可以使用AJAX来异步保存设置，提高用户体验。

总结：

add_options_page()是WordPress插件开发中非常常用的一个函数，它可以让你轻松地添加自定义的设置页面。掌握了它的用法，你就能更好地控制你的插件的行为，为用户提供更好的体验。

记住，编程就像恋爱，熟能生巧。多写代码，多踩坑，多总结，你也能成为WordPress开发高手！

好了，今天的讲堂就到这里，感谢各位观众老爷的观看！下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注