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 自定义器
上一篇
Sasha 主题
下一篇

0 条评论

像素鱼丸
88368 阅读
140 发布
3 收藏
动态
Mirage 主题 v2.56.0 发布
MirageV 主题 v2.6.4 发布
BotV 插件 v1.7.0 发布
MirageV 主题 v2.6.0 发布
FishV 主题 v1.14 发布
MirageV-App 小程序 v1.2.2 发布
LandV 企业主题 v2.6.0 发布
FishV 主题 v1.21.0 发布
生成中...
真诚赞赏,手留余香
登录
注册
重置密码