探究 WordPress `add_settings_section()` 和 `add_settings_field()` 函数源码：如何注册设置页面中的区域和字段。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位代码界的英雄好汉，今天咱们聊聊 WordPress 后台设置页面里那些“门门道道”—— add_settings_section() 和 add_settings_field() 这俩哥们。别看名字挺长，其实是 WordPress 选项 API 里的重要成员，专门负责帮你把设置项安排得井井有条。

“设置页面”是个啥？

首先，咱们得搞清楚“设置页面”是干嘛的。想象一下，你的插件或者主题需要用户自定义一些东西，比如颜色、字体、广告代码啥的。总不能让用户直接改代码吧？那得多吓人！所以，我们需要一个友好的界面，让用户通过简单的选项就能控制这些设置。这就是设置页面存在的意义。

WordPress 本身就有很多设置页面，比如“常规”、“阅读”、“撰写”等等。你也可以为自己的插件或主题创建自定义的设置页面。

选项 API：管理设置的利器

WordPress 提供了选项 API 来简化设置的管理。它负责：

存储设置： 把用户的设置值保存在 wp_options 表里，这样下次用户访问网站的时候，设置还能生效。
显示设置： 在设置页面上渲染表单，让用户可以修改设置。
验证和清理设置： 确保用户输入的数据是有效的，并且清理掉不必要的数据。

add_settings_section() 和 add_settings_field() 就是选项 API 的重要组成部分，负责组织和显示设置。

add_settings_section()：区域划分小能手

add_settings_section() 函数的作用是在设置页面上创建一个区域（Section）。你可以把它想象成一个容器，用来存放相关的设置项。比如，你可以创建一个“外观设置”区域，里面放颜色、字体等相关的设置项。

函数原型：

add_settings_section(
    string   $id,          // 区域的唯一 ID
    string   $title,       // 区域的标题
    callable $callback,    // 显示区域描述的回调函数
    string   $page          // 设置页面的 slug
);

$id： 这个是区域的身份证号，必须是唯一的。以后要引用这个区域的时候，就靠它了。建议使用插件或主题的前缀，避免冲突。比如 my_plugin_appearance_section。
$title： 区域的标题，会显示在设置页面上。比如 "外观设置"。
$callback： 这是一个回调函数，用来显示区域的描述信息。你可以放一些文字，告诉用户这个区域是用来干什么的。如果不需要描述，可以传一个空字符串或者 __return_false()。
$page： 设置页面的 slug。这个 slug 是你在创建设置页面的时候定义的。比如，如果你的设置页面 slug 是 my-plugin-settings，那么这里就填 my-plugin-settings。

代码示例：

function my_plugin_register_settings() {
    add_settings_section(
        'my_plugin_appearance_section',
        '外观设置',
        'my_plugin_appearance_section_callback',
        'my-plugin-settings'
    );
}
add_action( 'admin_init', 'my_plugin_register_settings' );

function my_plugin_appearance_section_callback() {
    echo '<p>在这里您可以自定义插件的外观。</p>';
}

这段代码的意思是：

定义了一个函数 my_plugin_register_settings()，用来注册设置区域。
使用 add_settings_section() 创建了一个 ID 为 my_plugin_appearance_section，标题为 "外观设置" 的区域，并将它添加到 my-plugin-settings 这个设置页面上。
my_plugin_appearance_section_callback() 函数用来显示区域的描述信息。

add_settings_field()：字段添加好帮手

add_settings_field() 函数的作用是在设置区域里添加一个设置项（Field）。你可以把它想象成一个输入框、下拉列表、复选框等等，用来让用户输入或选择设置值。

函数原型：

add_settings_field(
    string   $id,              // 字段的唯一 ID
    string   $title,           // 字段的标题
    callable $callback,        // 显示字段的回调函数
    string   $page,            // 设置页面的 slug
    string   $section = 'default', // 字段所属的区域 ID
    array    $args = array()      // 传递给回调函数的参数
);

$id： 字段的身份证号，必须是唯一的。建议使用插件或主题的前缀，避免冲突。比如 my_plugin_color_setting。
$title： 字段的标题，会显示在设置页面上。比如 "颜色"。
$callback： 这是一个回调函数，用来显示字段的表单元素。你可以在这里输出一个输入框、下拉列表、复选框等等。
$page： 设置页面的 slug。和 add_settings_section() 里的 $page 参数一样。
$section： 字段所属的区域 ID。就是你用 add_settings_section() 创建的区域的 ID。如果不指定，默认会添加到 "default" 区域。
$args： 一个数组，用来传递给回调函数 $callback 的参数。你可以用它来传递一些额外的信息，比如字段的描述、默认值等等。

代码示例：

function my_plugin_register_settings() {
    add_settings_section(
        'my_plugin_appearance_section',
        '外观设置',
        'my_plugin_appearance_section_callback',
        'my-plugin-settings'
    );

    add_settings_field(
        'my_plugin_color_setting',
        '颜色',
        'my_plugin_color_setting_callback',
        'my-plugin-settings',
        'my_plugin_appearance_section',
        array( 'label_for' => 'my_plugin_color_setting' )
    );

    register_setting( 'my-plugin-settings', 'my_plugin_color_setting' ); // 注册设置
}
add_action( 'admin_init', 'my_plugin_register_settings' );

function my_plugin_color_setting_callback( $args ) {
    $value = get_option( 'my_plugin_color_setting' );
    printf(
        '<input type="text" id="%s" name="%s" value="%s" />',
        esc_attr( $args['label_for'] ),
        esc_attr( 'my_plugin_color_setting' ),
        esc_attr( $value )
    );
}

function my_plugin_appearance_section_callback() {
    echo '<p>在这里您可以自定义插件的外观。</p>';
}

这段代码的意思是：

在 my_plugin_register_settings() 函数中，除了注册区域之外，还使用 add_settings_field() 创建了一个 ID 为 my_plugin_color_setting，标题为 "颜色" 的字段，并将它添加到 my_plugin_appearance_section 这个区域里。
my_plugin_color_setting_callback() 函数用来显示字段的表单元素，这里是一个文本输入框。
register_setting( 'my-plugin-settings', 'my_plugin_color_setting' ) 这个函数非常重要！它告诉 WordPress 你要注册一个设置，并且指定了设置页面的 slug 和设置的名称。 一定要注册设置，否则设置值无法保存！

重点： register_setting() 函数

register_setting() 函数是选项 API 的核心函数之一，它负责注册设置，告诉 WordPress 你要管理哪些设置。

函数原型：

register_setting(
    string $option_group,  // 设置组的名称
    string $option_name,   // 设置的名称
    array  $args = array()   // 额外的参数
);

$option_group： 设置组的名称。通常和设置页面的 slug 相同。
$option_name： 设置的名称。就是你在 add_settings_field() 中定义的字段的 ID。
$args： 一个数组，用来传递一些额外的参数，比如设置的验证和清理函数。

重要提示：

一定要在 admin_init 钩子上调用 add_settings_section()、add_settings_field() 和 register_setting() 函数。
$id 必须是唯一的，建议使用插件或主题的前缀。
回调函数 $callback 必须存在，并且能够正确地显示表单元素。
register_setting() 函数是必须的，否则设置值无法保存。

一个完整的例子：

咱们来创建一个完整的例子，实现一个简单的插件设置页面，包含一个文本输入框和一个复选框。

<?php
/**
 * Plugin Name: My Awesome Plugin
 * Description: A simple plugin with a settings page.
 * Version: 1.0.0
 */

// 创建设置页面
function my_plugin_add_settings_page() {
    add_options_page(
        'My Plugin Settings',
        'My Plugin',
        'manage_options',
        'my-plugin-settings',
        'my_plugin_settings_page_content'
    );
}
add_action( 'admin_menu', 'my_plugin_add_settings_page' );

// 设置页面的内容
function my_plugin_settings_page_content() {
    ?>
    <div class="wrap">
        <h1>My Plugin Settings</h1>
        <form method="post" action="options.php">
            <?php
                settings_fields( 'my-plugin-settings' );
                do_settings_sections( 'my-plugin-settings' );
                submit_button();
            ?>
        </form>
    </div>
    <?php
}

// 注册设置
function my_plugin_register_settings() {
    // 添加设置区域
    add_settings_section(
        'my_plugin_general_section',
        'General Settings',
        'my_plugin_general_section_callback',
        'my-plugin-settings'
    );

    // 添加文本输入框字段
    add_settings_field(
        'my_plugin_text_setting',
        'Text Setting',
        'my_plugin_text_setting_callback',
        'my-plugin-settings',
        'my_plugin_general_section',
        array( 'label_for' => 'my_plugin_text_setting' )
    );

    // 添加复选框字段
    add_settings_field(
        'my_plugin_checkbox_setting',
        'Checkbox Setting',
        'my_plugin_checkbox_setting_callback',
        'my-plugin-settings',
        'my_plugin_general_section',
        array( 'label_for' => 'my_plugin_checkbox_setting' )
    );

    // 注册设置
    register_setting( 'my-plugin-settings', 'my_plugin_text_setting', 'my_plugin_sanitize_text_setting' );
    register_setting( 'my-plugin-settings', 'my_plugin_checkbox_setting' );
}
add_action( 'admin_init', 'my_plugin_register_settings' );

// 设置区域的描述
function my_plugin_general_section_callback() {
    echo '<p>Configure the general settings for the plugin.</p>';
}

// 文本输入框字段的回调函数
function my_plugin_text_setting_callback( $args ) {
    $value = get_option( 'my_plugin_text_setting' );
    printf(
        '<input type="text" id="%s" name="%s" value="%s" />',
        esc_attr( $args['label_for'] ),
        esc_attr( 'my_plugin_text_setting' ),
        esc_attr( $value )
    );
}

// 复选框字段的回调函数
function my_plugin_checkbox_setting_callback( $args ) {
    $value = get_option( 'my_plugin_checkbox_setting' );
    printf(
        '<input type="checkbox" id="%s" name="%s" value="1" %s />',
        esc_attr( $args['label_for'] ),
        esc_attr( 'my_plugin_checkbox_setting' ),
        checked( $value, 1, false )
    );
}

// 清理文本输入框的值
function my_plugin_sanitize_text_setting( $input ) {
    // 可以添加一些验证逻辑，比如检查输入是否为空
    $sanitized_input = sanitize_text_field( $input );
    return $sanitized_input;
}

代码解释：

my_plugin_add_settings_page()： 创建了一个名为 "My Plugin" 的设置页面，并将其添加到 WordPress 后台的 "设置" 菜单下。
my_plugin_settings_page_content()： 定义了设置页面的内容。settings_fields() 函数用于输出隐藏的表单字段，do_settings_sections() 函数用于输出设置区域。 submit_button()函数用于生成提交按钮。
my_plugin_register_settings()： 注册设置区域和字段。
- 创建了一个名为 "General Settings" 的区域。
- 创建了一个文本输入框字段和一个复选框字段，并将它们添加到 "General Settings" 区域里。
- 使用 register_setting() 函数注册了这两个设置。
my_plugin_general_section_callback()： 显示 "General Settings" 区域的描述信息.
my_plugin_text_setting_callback() 和 my_plugin_checkbox_setting_callback()： 分别显示文本输入框和复选框的表单元素。
my_plugin_sanitize_text_setting()： 清理文本输入框的值。 sanitize_text_field() 函数用于移除 HTML 标签和转义特殊字符，防止 XSS 攻击。

总结：

add_settings_section() 和 add_settings_field() 就像是设置页面上的建筑师，帮你规划好设置的布局和结构。而 register_setting() 则是设置的守护者，确保你的设置能够被正确地保存和加载。掌握了这三个函数，你就可以轻松地创建出功能强大的自定义设置页面，让你的插件或主题更加易于使用和配置。

希望这次讲座能帮到大家。代码之路漫漫，咱们一起加油！

发表回复 取消回复

发表回复取消回复