开发WordPress插件：如何用Settings API创建含代码文本框的表单

嘿，我懂你想做一个类似Insert Headers and Footers的插件——就是一个简单的设置页面，带个能插入代码的文本框和保存按钮对吧？结合你提到的需求，我给你拆解下具体实现步骤，一步步来：

1. 先注册后台菜单与设置页面 #

首先得在WordPress后台添加一个专属菜单项，关联到我们的设置页面。你可以在插件主文件里加入这段代码：

// 添加后台菜单
add_action('admin_menu', 'my_custom_code_menu');
function my_custom_code_menu() {
    add_options_page(
        '自定义代码设置', // 页面标题
        '自定义代码',     // 后台菜单显示名称
        'manage_options', // 访问权限（仅管理员可操作）
        'my-custom-code', // 菜单唯一标识slug
        'my_custom_code_settings_page' // 渲染页面的回调函数
    );
}

2. 配置Settings API核心逻辑 #

接下来要用到Settings API的三个核心函数：注册设置项、添加设置区域、渲染代码输入框，同时处理输入的安全验证：

// 初始化设置项
add_action('admin_init', 'my_custom_code_settings_init');
function my_custom_code_settings_init() {
    // 注册设置：关联选项组、存储键名、安全验证回调
    register_setting('my_custom_code_group', 'my_custom_code', array(
        'sanitize_callback' => 'my_custom_code_sanitize',
        'default' => ''
    ));

    // 添加设置区域（用来包裹字段，可加描述）
    add_settings_section(
        'my_custom_code_section', // 区域ID
        '插入自定义代码',          // 区域标题
        'my_custom_code_section_desc', // 区域描述回调
        'my-custom-code' // 关联的页面slug
    );

    // 添加代码输入字段
    add_settings_field(
        'my_custom_code_field', // 字段ID
        '代码输入框',            // 字段标签
        'my_custom_code_field_render', // 渲染字段的回调
        'my-custom-code', // 关联的页面slug
        'my_custom_code_section' // 关联的区域ID
    );
}

// 设置区域的描述文本（给用户提示）
function my_custom_code_section_desc() {
    echo '<p>在这里输入需要插入到网站的代码（比如JS、CSS、HTML片段），保存后即可生效。</p>';
}

// 渲染代码输入框（用textarea适配多行代码）
function my_custom_code_field_render() {
    // 获取已保存的代码值
    $saved_code = get_option('my_custom_code');
    // 渲染textarea，添加code类让WordPress自动应用代码字体样式
    echo '<textarea id="my_custom_code" name="my_custom_code" rows="15" cols="80" class="code">' . esc_textarea($saved_code) . '</textarea>';
}

// 安全验证输入的代码（保留合法HTML/代码，同时过滤恶意内容）
function my_custom_code_sanitize($input) {
    // wp_kses_post适合保留文章级别的HTML/代码，若需要更宽松规则可自定义
    return wp_kses_post($input);
}

// 渲染完整的设置页面
function my_custom_code_settings_page() {
    // 检查用户权限
    if (!current_user_can('manage_options')) {
        wp_die('你没有权限访问此页面。');
    }
    ?>
    <div class="wrap">
        <h1><?php echo esc_html(get_admin_page_title()); ?></h1>
        <form action="options.php" method="post">
            <?php
            // 输出Settings API所需的安全隐藏字段
            settings_fields('my_custom_code_group');
            // 渲染所有设置区域和字段
            do_settings_sections('my-custom-code');
            // 输出WordPress自带的保存按钮
            submit_button('保存更改');
            ?>
        </form>
    </div>
    <?php
}

3. 关键细节说明 #

• sanitize_callback：这是保证安全的核心，wp_kses_post会保留合法的HTML标签和代码结构，同时过滤恶意脚本，既不破坏用户输入的代码又保证网站安全。
• class="code"：WordPress后台自带这个样式类，会自动给文本框应用等宽字体，让输入体验更贴近代码编辑器。
• settings_fields与do_settings_sections：这两个函数帮我们省去了手写表单验证、隐藏字段的麻烦，完全遵循WordPress的安全规范。

4. 可选：优化代码框样式（更贴近专业编辑器） #

如果想让输入框看起来更舒服，可以再加一段自定义样式：

add_action('admin_enqueue_scripts', 'my_custom_code_admin_styles');
function my_custom_code_admin_styles($hook) {
    // 只在我们的设置页面加载样式，避免影响其他后台页面
    if ($hook !== 'settings_page_my-custom-code') {
        return;
    }
    wp_add_inline_style('wp-admin', '
        #my_custom_code {
            background-color: #f8f9fa;
            padding: 12px;
            border-radius: 4px;
            border: 1px solid #ccd0d4;
        }
    ');
}

这样你就得到了一个和Insert Headers and Footers结构一致的插件：后台有专属设置页面，一个适配多行代码的输入框，点击「保存更改」即可把代码存入数据库。后续只需要再添加一个钩子函数（比如wp_head或wp_footer），把保存的代码输出到网站对应位置就行。

内容的提问来源于stack exchange，提问作者user5405574