使用 WordPress 的 Setting API 是在插件或主题中创建和管理设置页面的标准方式。它提供了一种结构化、安全的方式来保存和获取用户配置的选项。

✅ 一、Setting API 简介

WordPress 的 Setting API 允许你：

• 创建设置页面（Settings Page）
• 注册设置字段（Settings Field）
• 验证和保存设置数据
• 使用表单提交来更新设置

✅ 二、基本步骤

1. 注册设置（register_setting）

function my_plugin_register_settings() {
    register_setting( 'my-plugin-settings-group', 'my_plugin_option_name' );
}
add_action( 'admin_init', 'my_plugin_register_settings' );

• my-plugin-settings-group：设置组名称，用于分组
• my_plugin_option_name：存储的选项名（通常与数据库中的 option_name 对应）

2. 添加设置页面（add_settings_section）

function my_plugin_add_settings_section() {
    add_settings_section(
        'my-plugin-main-section', // ID
        'My Plugin Settings',     // 标题
        'my_plugin_section_callback', // 回调函数（可选）
        'my-plugin'               // 页面 slug
    );
}
add_action( 'admin_init', 'my_plugin_add_settings_section' );

3. 添加设置字段（add_settings_field）

function my_plugin_add_settings_field() {
    add_settings_field(
        'my_plugin_field_id',       // ID
        'My Plugin Field',          // 标题
        'my_plugin_field_callback', // 回调函数
        'my-plugin',                // 页面 slug
        'my-plugin-main-section'    // section ID
    );
}
add_action( 'admin_init', 'my_plugin_add_settings_field' );

4. 回调函数（回调函数）

a. 设置字段显示内容

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

b. 设置部分说明（可选）

function my_plugin_section_callback() {
    echo '<p>这是我的插件设置部分。</p>';
}

5. 创建设置页面（settings page）

function my_plugin_settings_page() {
    add_options_page(
        'My Plugin Settings',      // 页面标题
        'My Plugin',               // 菜单标题
        'manage_options',          // 权限
        'my-plugin',               // 页面 slug
        'my_plugin_render_settings_page'
    );
}
add_action('admin_menu', 'my_plugin_settings_page');
function my_plugin_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>My Plugin Settings</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields('my-plugin-settings-group'); // 输出隐藏的 nonce
            do_settings_sections('my-plugin');           // 输出所有设置段
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

✅ 三、完整示例代码

// 注册设置
function my_plugin_register_settings() {
    register_setting( 'my-plugin-settings-group', 'my_plugin_option_name' );
}
add_action( 'admin_init', 'my_plugin_register_settings' );
// 添加设置段
function my_plugin_add_settings_section() {
    add_settings_section(
        'my-plugin-main-section',
        'My Plugin Settings',
        'my_plugin_section_callback',
        'my-plugin'
    );
}
add_action( 'admin_init', 'my_plugin_add_settings_section' );
// 添加设置字段
function my_plugin_add_settings_field() {
    add_settings_field(
        'my_plugin_field_id',
        'My Plugin Field',
        'my_plugin_field_callback',
        'my-plugin',
        'my-plugin-main-section'
    );
}
add_action( 'admin_init', 'my_plugin_add_settings_field' );
// 设置部分回调
function my_plugin_section_callback() {
    echo '<p>这是我的插件设置部分。</p>';
}
// 设置字段回调
function my_plugin_field_callback() {
    $option = get_option('my_plugin_option_name');
    echo "<input type='text' name='my_plugin_option_name' value='" . esc_attr($option) . "' />";
}
// 添加设置页面
function my_plugin_settings_page() {
    add_options_page(
        'My Plugin Settings',
        'My Plugin',
        'manage_options',
        'my-plugin',
        'my_plugin_render_settings_page'
    );
}
add_action('admin_menu', 'my_plugin_settings_page');
function my_plugin_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>My Plugin Settings</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields('my-plugin-settings-group');
            do_settings_sections('my-plugin');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

✅ 四、获取设置值

$my_option = get_option('my_plugin_option_name');
echo esc_html($my_option);

✅ 五、验证和过滤设置值（可选）

你可以通过 register_setting 的第三个参数添加一个验证回调函数：

register_setting(
    'my-plugin-settings-group',
    'my_plugin_option_name',
    'my_plugin_validate_callback'
);
function my_plugin_validate_callback($input) {
    return sanitize_text_field($input); // 或其他验证逻辑
}

✅ 六、注意事项

• 所有设置都保存在 WordPress 的 wp_options 表中。
• 使用 settings_fields() 和 do_settings_sections() 来生成表单结构。
• 设置页面建议使用 add_options_page() 创建，这样会出现在“设置”菜单下。

✅ 七、进阶功能

• 多个设置组（groups）
• 多个设置页面
• 自定义字段类型（如 checkbox, select, textarea）
• 使用 sanitize_callback 过滤输入

如果你需要更复杂的设置（比如多选项卡、多组设置），可以使用 add_settings_section() 和 add_settings_field() 多次调用。

📦 总结

如果你需要我帮你写一个完整的插件结构或者处理某个特定字段类型（比如 Checkbox、Select 等），也可以告诉我 😊