WordPress Customizer 自定义器控件类型

当然可以!在 WordPress Customizer 中,除了基础的 textemail 控件外,还支持多种内置控件类型(Control Types)。下面为你整理 常用控件类型 + 完整代码示例,你可以直接复制到主题的 functions.php 中使用。


✅ 前提:所有代码都挂载到 customize_register 钩子

add_action( 'customize_register', 'mytheme_add_customizer_controls' );
function mytheme_add_customizer_controls( $wp_customize ) {
    // 在这里添加你的 Panel / Section / Settings / Controls
}

📌 1. 文本输入框(Text)

$wp_customize->add_setting( 'mytheme_text', array(
    'default'           => '默认文字',
    'sanitize_callback' => 'sanitize_text_field',
) );

$wp_customize->add_control( 'mytheme_text_control', array(
    'label'    => '普通文本',
    'section'  => 'title_tagline', // 或你自己的 section
    'settings' => 'mytheme_text',
    'type'     => 'text',
) );

📌 2. 多行文本(Textarea)

$wp_customize->add_setting( 'mytheme_textarea', array(
    'default'           => '默认段落内容...',
    'sanitize_callback' => 'wp_kses_post', // 允许基本 HTML
) );

$wp_customize->add_control( 'mytheme_textarea_control', array(
    'label'    => '多行文本(支持简单 HTML)',
    'section'  => 'title_tagline',
    'settings' => 'mytheme_textarea',
    'type'     => 'textarea',
) );

📌 3. 电子邮件(Email)

$wp_customize->add_setting( 'mytheme_email', array(
    'default'           => '',
    'sanitize_callback' => 'sanitize_email',
) );

$wp_customize->add_control( 'mytheme_email_control', array(
    'label'    => '邮箱地址',
    'section'  => 'title_tagline',
    'settings' => 'mytheme_email',
    'type'     => 'email',
) );

📌 4. URL 地址

$wp_customize->add_setting( 'mytheme_url', array(
    'default'           => '',
    'sanitize_callback' => 'esc_url_raw',
) );

$wp_customize->add_control( 'mytheme_url_control', array(
    'label'    => '网站链接',
    'section'  => 'title_tagline',
    'settings' => 'mytheme_url',
    'type'     => 'url',
) );

📌 5. 数字输入(Number)

$wp_customize->add_setting( 'mytheme_number', array(
    'default'           => 10,
    'sanitize_callback' => 'absint', // 只允许正整数
) );

$wp_customize->add_control( 'mytheme_number_control', array(
    'label'       => '数量(1-100)',
    'section'     => 'title_tagline',
    'settings'    => 'mytheme_number',
    'type'        => 'number',
    'input_attrs' => array(
        'min'  => 1,
        'max'  => 100,
        'step' => 1,
    ),
) );

📌 6. 开关(Checkbox)

$wp_customize->add_setting( 'mytheme_show_banner', array(
    'default'           => true,
    'sanitize_callback' => 'rest_sanitize_boolean',
) );

$wp_customize->add_control( 'mytheme_show_banner_control', array(
    'label'    => '显示横幅?',
    'section'  => 'title_tagline',
    'settings' => 'mytheme_show_banner',
    'type'     => 'checkbox',
) );

前端使用:if ( get_theme_mod( 'mytheme_show_banner' ) ) { ... }


📌 7. 下拉选择(Select)

$wp_customize->add_setting( 'mytheme_layout', array(
    'default'           => 'full-width',
    'sanitize_callback' => 'sanitize_key',
) );

$wp_customize->add_control( 'mytheme_layout_control', array(
    'label'    => '页面布局',
    'section'  => 'title_tagline',
    'settings' => 'mytheme_layout',
    'type'     => 'select',
    'choices'  => array(
        'full-width' => '全宽',
        'sidebar'    => '带侧边栏',
        'narrow'     => '窄屏',
    ),
) );

前端使用:$layout = get_theme_mod( 'mytheme_layout', 'full-width' );


📌 8. 单选按钮(Radio)

$wp_customize->add_setting( 'mytheme_color_scheme', array(
    'default'           => 'light',
    'sanitize_callback' => 'sanitize_key',
) );

$wp_customize->add_control( 'mytheme_color_scheme_control', array(
    'label'    => '配色方案',
    'section'  => 'title_tagline',
    'settings' => 'mytheme_color_scheme',
    'type'     => 'radio',
    'choices'  => array(
        'light' => '浅色',
        'dark'  => '深色',
        'auto'  => '自动(跟随系统)',
    ),
) );

📌 9. 颜色选择器(Color Picker)

$wp_customize->add_setting( 'mytheme_accent_color', array(
    'default'           => '#0073aa',
    'sanitize_callback' => 'sanitize_hex_color',
) );

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'mytheme_accent_color_control', array(
    'label'    => '强调色',
    'section'  => 'colors', // WordPress 内置的颜色 section
    'settings' => 'mytheme_accent_color',
) ) );

注意:颜色控件需使用 WP_Customize_Color_Control 类(不是字符串 'type' => 'color')。


📌 10. 图片上传(Image Upload)

$wp_customize->add_setting( 'mytheme_logo_image', array(
    'default'           => '',
    'sanitize_callback' => 'esc_url_raw',
) );

$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'mytheme_logo_image_control', array(
    'label'      => '自定义 Logo 图片',
    'section'    => 'title_tagline',
    'settings'   => 'mytheme_logo_image',
    'mime_type'  => 'image', // 仅限图片
) ) );

前端显示:

$logo = get_theme_mod( 'mytheme_logo_image' );
if ( $logo ) echo '<img src="' . esc_url( $logo ) . '" alt="Logo">';

📌 11. 文件上传(通用媒体)

'mime_type' => 'image' 改为 'mime_type' => '' 即可上传任意媒体(PDF、视频等)。


📌 12. 日期选择器(Date)(WordPress 4.7+)

$wp_customize->add_setting( 'mytheme_event_date', array(
    'default'           => date('Y-m-d'),
    'sanitize_callback' => 'sanitize_text_field',
) );

$wp_customize->add_control( 'mytheme_event_date_control', array(
    'label'    => '活动日期',
    'section'  => 'title_tagline',
    'settings' => 'mytheme_event_date',
    'type'     => 'date',
) );

🔧 小贴士

功能 说明
Sanitize 回调 务必设置,防止 XSS 或无效数据
默认值 通过 get_theme_mod( 'key', '默认值' ) 获取
Section 归属 可用内置 section(如 title_tagline, colors, static_front_page)或自定义 section
实时预览 设置 'transport' => 'postMessage' 并配合 JS 实现无刷新预览

🎁 附加:创建自定义 Panel(面板)来组织多个 Section

// 添加 Panel
$wp_customize->add_panel( 'mytheme_panel', array(
    'title'       => '我的主题设置',
    'priority'    => 150,
) );

// 添加 Section 并归属到 Panel
$wp_customize->add_section( 'mytheme_contact_section', array(
    'title' => '联系信息',
    'panel' => 'mytheme_panel', // 关键!
) );

 

收藏
评论
打赏
WordPress Customizer 自定义器
上一篇
没有了
下一篇

0 条评论

像素鱼丸
84051 阅读
139 发布
3 收藏
动态
Mirage 主题 v2.54.0 发布
Botcan 插件 v2.7.1 发布,支持 AI 生成文章特色图片
MirageV 主题 v2.6.4 发布
Mighty 企业主题 v1.10.0 发布
MirageV 主题 v2.6.0 发布
BotV 插件 v1.7.0 发布
FishV 主题 v1.14 发布
MirageV-App 小程序 v1.2.2 发布
生成中...
真诚赞赏,手留余香
登录
注册
重置密码