WordPress选项与设置API使用

wen PHP项目 2026-07-22 1

本文目录导读：

WordPress选项与设置API使用

WordPress选项（Options）
WordPress设置API
选项 vs 设置API - 选择指南
高级技巧
常见陷阱与最佳实践

在WordPress开发中，选项（Options）和设置API（Settings API）是管理站点配置数据的重要机制，下面我会详细介绍它们的核心概念、区别和最佳实践。

WordPress选项（Options）

什么是选项？

WordPress的选项是存储在wp_options表中的键值对数据
用于存储全局配置信息（如站点标题、时区等）
可以存储字符串、数组、对象等复杂数据类型

常用函数

添加/更新选项

// 添加选项（如果不存在）
add_option('my_plugin_setting', 'default_value');
// 更新选项（存在则更新，不存在则创建）
update_option('my_plugin_setting', 'new_value');
// 更新数组选项
$settings = array(
    'color' => 'blue',
    'size' => 'large'
);
update_option('my_plugin_settings', $settings);

获取选项

// 获取单个选项
$value = get_option('my_plugin_setting', 'default_value');
// 获取数组选项
$settings = get_option('my_plugin_settings', array());
echo $settings['color']; // 输出: blue

删除选项

delete_option('my_plugin_setting');

自动加载（Autoload）

选项可以设置自动加载,影响性能：

// 设置自动加载为yes（默认）
update_option('my_setting', 'value', true); // 第三个参数：自动加载
// 或使用'yes'/'no'
update_option('my_setting', 'value', 'no');

最佳实践：只有频繁使用的小型数据才设置自动加载为yes。

WordPress设置API

设置API提供了一套标准化的方式创建管理页面、注册设置、渲染输入字段和校验数据。

工作流程

注册设置：定义要管理的选项
添加设置章节：组织表单的视觉分组
添加设置字段：实际的输入控件
渲染设置页面：布局与UI
输入验证：保存前的数据清洗

完整示例：创建插件设置页面

class MyPluginSettings {
    public function __construct() {
        add_action('admin_menu', array($this, 'add_admin_menu'));
        add_action('admin_init', array($this, 'register_settings'));
    }
    // 1. 添加菜单页面
    public function add_admin_menu() {
        add_options_page(
            '我的插件设置', // 页面标题
            '我的插件',     // 菜单名称
            'manage_options', // 权限
            'my-plugin',    // 菜单别名
            array($this, 'render_settings_page') // 回调函数
        );
    }
    // 2. 注册设置、章节和字段
    public function register_settings() {
        // 注册设置（第三个参数是验证回调）
        register_setting(
            'my_plugin_settings_group', // 设置组（用于表单的option_page字段）
            'my_plugin_settings',       // 选项名称（数据库中的键名）
            array(
                'type' => 'array',
                'sanitize_callback' => array($this, 'validate_settings'),
                'default' => array(
                    'text_field' => '',
                    'checkbox_field' => false
                )
            )
        );
        // 添加设置章节
        add_settings_section(
            'my_plugin_main_section', // ID
            '主要设置',               // 标题
            array($this, 'render_section_description'), // 章节描述回调
            'my-plugin' // 页面别名
        );
        // 添加文本字段
        add_settings_field(
            'text_field', // ID
            '文本输入',   // 标签
            array($this, 'render_text_field'), // 渲染回调
            'my-plugin', // 页面别名
            'my_plugin_main_section', // 章节ID
            array(
                'label_for' => 'text_field',
                'class' => 'regular-text'
            )
        );
        // 添加复选框
        add_settings_field(
            'checkbox_field',
            '启用选项',
            array($this, 'render_checkbox_field'),
            'my-plugin',
            'my_plugin_main_section',
            array('label_for' => 'checkbox_field')
        );
    }
    // 3. 渲染设置页面
    public function render_settings_page() {
        ?>
        <div class="wrap">
            <h1><?php echo esc_html(get_admin_page_title()); ?></h1>
            <form action="options.php" method="post">
                <?php
                settings_fields('my_plugin_settings_group'); // 输出安全字段
                do_settings_sections('my-plugin'); // 输出所有章节和字段
                submit_button('保存设置');
                ?>
            </form>
        </div>
        <?php
    }
    // 4. 章节描述
    public function render_section_description() {
        echo '<p>配置插件的主要参数</p>';
    }
    // 5. 渲染文本字段
    public function render_text_field($args) {
        $options = get_option('my_plugin_settings');
        ?>
        <input 
            type="text" 
            id="<?php echo esc_attr($args['label_for']); ?>"
            name="my_plugin_settings[text_field]" 
            value="<?php echo isset($options['text_field']) ? esc_attr($options['text_field']) : ''; ?>"
            class="<?php echo esc_attr($args['class']); ?>"
        >
        <p class="description">输入一些文本内容</p>
        <?php
    }
    // 6. 渲染复选框
    public function render_checkbox_field($args) {
        $options = get_option('my_plugin_settings');
        $checked = isset($options['checkbox_field']) ? $options['checkbox_field'] : false;
        ?>
        <label for="<?php echo esc_attr($args['label_for']); ?>">
            <input 
                type="checkbox" 
                id="<?php echo esc_attr($args['label_for']); ?>"
                name="my_plugin_settings[checkbox_field]" 
                value="1"
                <?php checked(1, $checked); ?>
            >
            勾选启用此功能
        </label>
        <?php
    }
    // 7. 验证和清理输入
    public function validate_settings($input) {
        $valid = array();
        // 验证文本字段
        $valid['text_field'] = sanitize_text_field($input['text_field']);
        // 验证复选框
        $valid['checkbox_field'] = isset($input['checkbox_field']) ? 1 : 0;
        return $valid;
    }
}
// 初始化
new MyPluginSettings();

选项 vs 设置API - 选择指南

特性	选项（Options）	设置API
复杂度	简单直接	更规范、功能完整
验证	需要手动实现	内置验证回调
UI生成	完全自定义	提供标准化UI组件
表单安全	需自己处理nonce	自动处理nonce/安全
适用场景	非UI的配置、简单存储	后台设置页面
数据组织	松散键值对	分组、章节化

使用建议

什么时候用选项（Options）？

存储非用户界面相关的数据（如缓存、API密钥）
快速存储少量数据
自定义、复杂的UI场景

什么时候用设置API？

创建标准的管理设置页面
需要规范化的数据验证
需要多字段、多分组的复杂配置
希望利用WordPress内置的安全机制

高级技巧

使用瞬态（Transients）缓存选项

// 存储临时数据（自动过期）
set_transient('my_temp_data', $data, HOUR_IN_SECONDS);
// 获取
$data = get_transient('my_temp_data');
// 删除
delete_transient('my_temp_data');

网络选项（多站点）

// 网络级别选项
get_site_option('my_network_setting');
update_site_option('my_network_setting', $value);

选项自动加载优化

// 批量获取自动加载选项
$all_options = wp_load_alloptions();
// 单个不自动加载
update_option('heavy_data', $data, false); // 第三个参数false

常见陷阱与最佳实践

✅ 正确做法

使用register_setting()的sanitize_callback进行数据验证
使用settings_fields()和do_settings_sections()生成安全的表单
为选项名称添加插件前缀（如myplugin_）避免冲突
删除卸载时的选项数据

❌ 错误做法

直接在主题functions.php中硬编码选项名
不进行数据验证直接保存用户输入
在插件激活钩子中存储大量自动加载选项
频繁调用get_option()获取不改变的数据

对于简单的数据存储，直接使用Options函数即可；对于需要管理后台界面的配置，一定要使用Settings API，它提供了安全、标准化的解决方案，在实际开发中，两者经常结合使用，但建议优先考虑Settings API,因为它提供了更好的架构和安全性。