WordPress 自定义器完全指南：面板、章节、设置与控件

发布于 作者:

WordPress 自定义器（Customizer）是主题开发中强大的实时预览工具，它让用户能在修改网站外观的同时即时看到效果。本文深入解析自定义器的四大核心对象——面板（Panels）、章节（Sections）、设置（Settings）和控件（Controls），从基础概念到实战代码，带你掌握如何为经典主题添加个性化配置选项。你将学会使用 customize_register 钩子注册自定义选项，理解 theme_mod 与 option 的区别，以及如何通过内置控件类型快速构建级主题设置界面。无论你是想添加颜色选择器、上传图片还是创建自定义 CSS 区域，这份指南都提供了可直接套用的代码示例和佳实践。

一、认识自定义器架构

自定义器采用面向对象设计，核心由 WP_Customize_Manager 类统一管理所有对象。这四个对象层级分明：

  • 设置（Settings）：负责数据的存储、验证和预览，是自定义器的基础
  • 控件（Controls）：用户交互界面，与设置绑定，收集用户输入
  • 章节（Sections）：控件的容器，用于分组组织
  • 面板（Panels）：章节的容器，提供更高层级的分类

php

// 所有自定义操作都从这个钩子开始
add_action( 'customize_register', 'mytheme_customize_register' );

function mytheme_customize_register( $wp_customize ) {
    // $wp_customize 就是 WP_Customize_Manager 实例
    // 你可以在这里添加、获取或移除任何自定义器对象
}

每个对象都有对应的 add_、get_ 和 remove_ 方法：

php

// 面板操作
$wp_customize->add_panel( 'my_panel', $args );
$panel = $wp_customize->get_panel( 'my_panel' );
$wp_customize->remove_panel( 'my_panel' );

// 章节操作
$wp_customize->add_section( 'my_section', $args );
$section = $wp_customize->get_section( 'my_section' );
$wp_customize->remove_section( 'my_section' );

// 设置操作
$wp_customize->add_setting( 'my_setting', $args );
$setting = $wp_customize->get_setting( 'my_setting' );
$wp_customize->remove_setting( 'my_setting' );

// 控件操作
$wp_customize->add_control( 'my_control', $args );
$control = $wp_customize->get_control( 'my_control' );
$wp_customize->remove_control( 'my_control' );

注意：主题通常不应修改核心章节和面板，这些应由插件处理。主题应专注于添加自己的自定义选项。

二、设置（Settings）：数据的核心

设置是自定义器的数据层，负责保存、预览和验证用户输入。添加设置时，以下参数为关键：

php

$wp_customize->add_setting( 'header_color', array(
    'type'                 => 'theme_mod',   // 或 'option'
    'capability'           => 'edit_theme_options',
    'theme_supports'       => '',
    'default'              => '#333333',
    'transport'            => 'refresh',     // 或 'postMessage'
    'sanitize_callback'    => 'sanitize_hex_color',
    'sanitize_js_callback' => '',
) );

设置类型：theme_mod vs option

  • theme_mod：主题专属设置，切换主题后仍保留数据。大多数主题选项应使用此类型
  • option：全局选项，存储于 wp_options 表，跨主题共享。通常由插件使用

php

// 主题推荐用法
$wp_customize->add_setting( 'accent_color', array(
    'default'           => '#f72525',
    'sanitize_callback' => 'sanitize_hex_color',
) );

// 插件用法示例
$wp_customize->add_setting( 'myplugin_options[color]', array(
    'type'              => 'option',
    'capability'        => 'manage_options',
    'default'           => '#ff2525',
    'sanitize_callback' => 'sanitize_hex_color',
) );

获取保存的值

php

function mytheme_custom_css_output() {
    // 获取主题设置值
    $theme_css = get_theme_mod( 'custom_theme_css', '' );
    // 获取插件设置值
    $plugin_css = get_option( 'custom_plugin_css', '' );
    
    echo '<style type="text/css" id="custom-theme-css">' . 
         esc_html( $theme_css ) . '</style>';
}
add_action( 'wp_head', 'mytheme_custom_css_output' );

注意：设置 ID 不能以 widget_、sidebars_widgets[*]、nav_menu[*] 或 nav_menu_item[*] 开头，这些被系统保留。如需使用 “widget”，应放在 ID 末尾，如 homepage_widget。

三、控件（Controls）：用户交互界面

控件是用户实际操作的界面元素，每个控件必须关联一个设置。

基础控件参数

php

$wp_customize->add_control( 'setting_id', array(
    'type'            => 'text',        // 控件类型
    'priority'        => 10,            // 显示顺序
    'section'         => 'colors',      // 所属章节（必需）
    'label'           => __( '标题' ),
    'description'     => __( '描述文字' ),
    'input_attrs'     => array(
        'class'       => 'my-custom-class',
        'style'       => 'border: 1px solid #900',
        'placeholder' => __( '输入提示' ),
    ),
    'active_callback' => 'is_front_page',
) );

内置控件类型

基础 HTML 输入类型：text、hidden、number、range、url、tel、email、search、time、date、datetime、week

特殊控件：

  • checkbox – 复选框
  • textarea – 多行文本
  • radio – 单选按钮（需提供 choices 数组）
  • select – 下拉选择（需提供 choices 数组）
  • dropdown-pages – 页面下拉选择

php

// 文本域控件示例
$wp_customize->add_control( 'custom_theme_css', array(
    'label'   => __( '自定义 CSS' ),
    'type'    => 'textarea',
    'section' => 'custom_css',
) );

// 范围滑块示例
$wp_customize->add_control( 'font_size', array(
    'type'        => 'range',
    'section'     => 'typography',
    'label'       => __( '字体大小' ),
    'input_attrs' => array(
        'min'  => 12,
        'max'  => 48,
        'step' => 2,
    ),
) );

四、核心自定义控件

颜色选择器

php

$wp_customize->add_control( 
    new WP_Customize_Color_Control( 
        $wp_customize, 
        'accent_color', 
        array(
            'label'   => __( '强调色' ),
            'section' => 'colors',
        ) 
    ) 
);

媒体控件（图片、音频、视频）

php

// 图片选择
$wp_customize->add_control( 
    new WP_Customize_Media_Control( 
        $wp_customize, 
        'featured_image', 
        array(
            'label'     => __( '首页特色图片' ),
            'section'   => 'media',
            'mime_type' => 'image',
        ) 
    ) 
);

// 音频选择
$wp_customize->add_control( 
    new WP_Customize_Media_Control( 
        $wp_customize, 
        'background_music', 
        array(
            'label'     => __( '背景音乐' ),
            'section'   => 'media',
            'mime_type' => 'audio',
        ) 
    ) 
);

注意：WP_Customize_Media_Control 保存的是附件 ID，而旧版的 WP_Customize_Upload_Control 保存的是 URL。

裁剪图片控件

WordPress 4.3+ 提供了裁剪图片控件，适合需要特定比例的场景：

php

$wp_customize->add_control( 
    new WP_Customize_Cropped_Image_Control( 
        $wp_customize, 
        'cropped_image', 
        array(
            'label'         => __( '头像' ),
            'section'       => 'media',
            'flex_width'    => false,
            'flex_height'   => false,
            'width'         => 150,
            'height'        => 150,
        ) 
    ) 
);

五、章节（Sections）：控件的容器

当控件较多时，使用章节进行分组管理。

php

// 添加自定义章节
$wp_customize->add_section( 'footer_settings', array(
    'title'           => __( '页脚设置' ),
    'description'     => __( '配置页脚区域的内容' ),
    'panel'           => '',           // 所属面板
    'priority'        => 105,          // 显示优先级
    'capability'      => 'edit_theme_options',
    'theme_supports'  => '',
) );

核心章节优先级参考

章节名称ID优先级
站点标题与副标题title_tagline20
颜色colors40
页眉图片header_image60
背景图片background_image80
菜单（面板）nav_menus100
小工具（面板）widgets110
静态首页static_front_page120
默认(空)160
额外 CSScustom_css200

六、面板（Panels）：高级分组

面板在 WordPress 4.0 引入，用于在更高层级组织章节。

php

$wp_customize->add_panel( 'theme_layout', array(
    'title'       => __( '页面布局' ),
    'description' => '<p>' . __( '配置全局布局选项' ) . '</p>',
    'priority'    => 30,
) );

// 将章节添加到面板
$wp_customize->add_section( 'blog_layout', array(
    'title'       => __( '博客布局' ),
    'panel'       => 'theme_layout',
) );

$wp_customize->add_section( 'page_layout', array(
    'title'       => __( '页面布局' ),
    'panel'       => 'theme_layout',
) );

注意：面板通常用于功能模块（如菜单、小工具），而非简单分组。大多数主题直接使用章节即可，无需面板。

七、自定义控件、章节和面板

当内置控件不满足需求时，可以创建自定义控件类：

php

// 自定义控件类
class MyTheme_Custom_Control extends WP_Customize_Control {
    public $type = 'my_custom_control';
    
    public function render_content() {
        ?>
        <button class="button button-primary" id="my-custom-button">
            <?php _e( '执行操作' ); ?>
        </button>
        <?php
    }
}

// 使用自定义控件
$wp_customize->add_control(
    new MyTheme_Custom_Control(
        $wp_customize,
        'custom_action',
        array(
            'label'   => __( '自定义操作' ),
            'section' => 'custom_section',
        )
    )
);

自定义章节和面板的实现方式类似，通过继承 WP_Customize_Section 或 WP_Customize_Panel 并重写 render_content() 方法。

八、自定义设置类型

默认设置类型（theme_mod 和 option）无法满足所有场景，可以创建自定义类型：

php

// 指定自定义类型
$wp_customize->add_setting( 'nav_menu_order', array(
    'type'    => 'nav_menu',  // 自定义类型
    'default' => array(),
) );

然后通过钩子处理保存和预览逻辑：

php

// 自定义保存逻辑
function mytheme_custom_update_handler( $value, $setting ) {
    // 处理保存逻辑
    // $value 是控件提交的值
    // $setting 是当前设置对象
    update_option( 'my_custom_option', $value );
}
add_action( 'customize_update_nav_menu', 'mytheme_custom_update_handler', 10, 2 );

// 自定义预览逻辑
function mytheme_custom_preview_handler( $setting ) {
    // 处理预览逻辑
    $preview_value = $setting->post_value();
    // 使用 $preview_value 修改预览输出
}
add_action( 'customize_preview_nav_menu', 'mytheme_custom_preview_handler', 10, 2 );

九、自定义器 UI 设计规范

创建自定义控件时，应遵循 WordPress 后台设计规范：

  • 白色背景用于可操作元素（输入框、按钮）
  • #eee 背景用于视觉分割
  • 1px #ddd 边框分隔导航元素
  • 4px 边框用于悬停状态，颜色为 #0073aa
  • 主文本颜色 #555d66，悬停状态 #0073aa
  • 元素间距 15px

php

// 符合规范的按钮示例
public function render_content() {
    ?>
    <button class="button button-primary">
        <?php _e( '保存设置' ); ?>
    </button>
    <?php
}

总结

WordPress 自定义器是主题开发不可或缺的工具，其四层架构（设置→控件→章节→面板）提供了灵活的配置能力。记住几个关键点：

  1. 设置是数据基础，theme_mod 是主题的类型
  2. 控件是用户界面，合理选择内置类型可节省大量时间
  3. 章节用于组织控件，合理分组提升用户体验
  4. 面板仅用于大型功能模块，避免过度使用
  5. 始终使用 sanitize_callback 确保数据安全

从简单的颜色选项开始，逐步扩展至复杂的媒体控件，自定义器能让你的主题既强大又易用。实践这些代码示例，你将快速掌握 WordPress 主题定制化的精髓。