手札

WordPress主题自定义设置开发指南

WordPress主题的自定义设置功能允许用户在不修改代码的情况下调整主题的外观和行为。以下是开发主题自定义设置的完整方法。

一、使用WordPress定制器(Theme Customizer)

WordPress定制器是添加主题设置的标准方式，提供实时预览功能。

1. 基本设置结构

function mytheme_customize_register($wp_customize) {
    // 所有自定义设置代码将放在这里
}
add_action('customize_register', 'mytheme_customize_register');

2. 添加设置选项

文本输入框

$wp_customize->add_setting('header_text', array(
    'default' => '欢迎来到我的网站',
    'transport' => 'refresh', // 或'postMessage'用于实时更新
));

$wp_customize->add_control('header_text', array(
    'label' => '页眉文本',
    'section' => 'title_tagline', // 默认的"站点身份"部分
    'type' => 'text',
));

颜色选择器

$wp_customize->add_setting('primary_color', array(
    'default' => '#1e73be',
    'transport' => 'postMessage',
    'sanitize_callback' => 'sanitize_hex_color',
));

$wp_customize->add_control(new WP_Customize_Color_Control(
    $wp_customize,
    'primary_color',
    array(
        'label' => '主色调',
        'section' => 'colors', // 默认的"颜色"部分
    )
));

图片上传

$wp_customize->add_setting('logo_image', array(
    'default' => '',
    'transport' => 'refresh',
));

$wp_customize->add_control(new WP_Customize_Image_Control(
    $wp_customize,
    'logo_image',
    array(
        'label' => '上传Logo',
        'section' => 'title_tagline',
        'settings' => 'logo_image',
    )
));

下拉选择框

$wp_customize->add_setting('layout_style', array(
    'default' => 'right-sidebar',
    'transport' => 'refresh',
));

$wp_customize->add_control('layout_style', array(
    'label' => '布局风格',
    'section' => 'mytheme_layout',
    'type' => 'select',
    'choices' => array(
        'full-width' => '全宽布局',
        'left-sidebar' => '左侧边栏',
        'right-sidebar' => '右侧边栏',
    ),
));

3. 创建自定义部分和面板

// 添加面板
$wp_customize->add_panel('mytheme_options', array(
    'title' => '主题选项',
    'priority' => 160,
));

// 添加部分到面板
$wp_customize->add_section('mytheme_layout', array(
    'title' => '布局设置',
    'panel' => 'mytheme_options',
    'priority' => 10,
));

$wp_customize->add_section('mytheme_footer', array(
    'title' => '页脚设置',
    'panel' => 'mytheme_options',
    'priority' => 20,
));

二、使用主题选项页面

对于更复杂的设置，可以创建专用的主题选项页面。

1. 创建选项页面

function mytheme_options_page() {
    add_theme_page(
        '主题选项', // 页面标题
        '主题选项', // 菜单标题
        'edit_theme_options', // 权限
        'mytheme-options', // 菜单slug
        'mytheme_options_page_html' // 回调函数
    );
}
add_action('admin_menu', 'mytheme_options_page');

2. 创建选项页面内容

function mytheme_options_page_html() {
    // 检查用户权限
    if (!current_user_can('edit_theme_options')) {
        return;
    }
    ?>
    <div class="wrap">
        <h1><?php echo esc_html(get_admin_page_title()); ?></h1>
        <form action="options.php" method="post">
            <?php
            // 输出安全字段
            settings_fields('mytheme_options');
            // 输出设置部分
            do_settings_sections('mytheme-options');
            // 提交按钮
            submit_button('保存设置');
            ?>
        </form>
    </div>
    <?php
}

3. 注册设置和字段

function mytheme_settings_init() {
    // 注册一个设置组
    register_setting('mytheme_options', 'mytheme_options', array(
        'sanitize_callback' => 'mytheme_options_validate',
    ));

    // 添加设置部分
    add_settings_section(
        'mytheme_section_general',
        '常规设置',
        'mytheme_section_general_cb',
        'mytheme-options'
    );

    // 添加字段
    add_settings_field(
        'mytheme_field_footer_text',
        '页脚文本',
        'mytheme_field_footer_text_cb',
        'mytheme-options',
        'mytheme_section_general'
    );
}
add_action('admin_init', 'mytheme_settings_init');

4. 字段回调函数

function mytheme_field_footer_text_cb() {
    $options = get_option('mytheme_options');
    ?>
    <input type="text" name="mytheme_options[footer_text]" 
           value="<?php echo esc_attr($options['footer_text'] ?? ''); ?>">
    <?php
}

function mytheme_section_general_cb() {
    echo '<p>主题的常规设置选项</p>';
}

function mytheme_options_validate($input) {
    $output = array();
    if (isset($input['footer_text'])) {
        $output['footer_text'] = sanitize_text_field($input['footer_text']);
    }
    return $output;
}

三、在前端使用设置值

1. 获取定制器设置

$header_text = get_theme_mod('header_text', '默认文本');
$primary_color = get_theme_mod('primary_color', '#1e73be');

2. 获取选项页面设置

$options = get_option('mytheme_options');
$footer_text = $options['footer_text'] ?? '默认页脚文本';

3. 动态输出CSS

function mytheme_customizer_css() {
    ?>
    <style type="text/css">
        .site-header {
            color: <?php echo sanitize_hex_color(get_theme_mod('header_text_color', '#333333')); ?>;
        }
        .primary-bg {
            background-color: <?php echo sanitize_hex_color(get_theme_mod('primary_color', '#1e73be')); ?>;
        }
    </style>
    <?php
}
add_action('wp_head', 'mytheme_customizer_css');

四、高级自定义设置

1. 使用Kirki框架

Kirki框架是一个强大的WordPress定制器框架，可以简化复杂控件的创建。

// 安装Kirki后
Kirki::add_field('mytheme_config', array(
    'type' => 'typography',
    'settings' => 'body_typography',
    'label' => esc_html__('正文排版', 'mytheme'),
    'section' => 'mytheme_typography',
    'default' => array(
        'font-family' => 'Roboto',
        'font-size' => '16px',
    ),
    'output' => array(
        array(
            'element' => 'body',
        ),
    ),
));

2. 添加图片选择器

$wp_customize->add_setting('header_background', array(
    'default' => '',
    'transport' => 'refresh',
));

$wp_customize->add_control(new WP_Customize_Image_Control(
    $wp_customize,
    'header_background',
    array(
        'label' => '页眉背景图',
        'section' => 'mytheme_header',
    )
));

3. 添加开关控件

$wp_customize->add_setting('show_breadcrumbs', array(
    'default' => true,
    'transport' => 'refresh',
));

$wp_customize->add_control('show_breadcrumbs', array(
    'label' => '显示面包屑导航',
    'section' => 'mytheme_navigation',
    'type' => 'checkbox',
));

通过以上方法，可以创建出用户友好、功能完善的主题自定义设置系统，让用户能够轻松个性化wordpress主题而无需编写代码。