Как создать настройки темы в WordPress с примерами кода

В этой статье разберём, как создать полноценную панель настроек для своей темы WordPress с помощью встроенного Settings API. Это позволит вашим пользователям удобно менять параметры темы через админку без необходимости редактировать файлы напрямую.

Что такое Settings API и зачем он нужен

Settings API — это набор функций WordPress, предназначенных для создания интерфейсов настройки и сохранения данных в базе. Он обеспечивает безопасность, валидацию и удобство, избавляя от необходимости самостоятельно писать обработчики форм.

Использование Settings API — лучший способ создать настройки темы, так как:

• Обеспечивает автоматическую защиту от CSRF;
• Поддерживает валидацию и очистку данных;
• Интегрируется с административным интерфейсом WordPress;
• Позволяет создавать секции, поля и страницы настроек.

Ниже на примере кода покажу, как реализовать страницу настроек с тремя параметрами: цвет фона, текст приветствия и включение/отключение отображения виджета.

Создание страницы настроек темы в админке WordPress

Первым шагом добавим меню в админку и зарегистрируем настройки. Для этого используем хук admin_menu и функцию add_theme_page:

function wpaction_add_theme_settings_page() {
    add_theme_page(
        'Настройки темы WPAction',
        'Настройки темы',
        'manage_options',
        'wpaction-theme-settings',
        'wpaction_render_theme_settings_page'
    );
}
add_action('admin_menu', 'wpaction_add_theme_settings_page');

Здесь мы создаём пункт меню «Настройки темы» в разделе «Внешний вид».

Далее зарегистрируем настройки и поля через хук admin_init:

function wpaction_register_theme_settings() {
    register_setting('wpaction_theme_options_group', 'wpaction_theme_options', 'wpaction_validate_theme_options');

    add_settings_section(
        'wpaction_section_main',
        'Основные настройки',
        'wpaction_section_main_cb',
        'wpaction-theme-settings'
    );

    add_settings_field(
        'background_color',
        'Цвет фона',
        'wpaction_background_color_cb',
        'wpaction-theme-settings',
        'wpaction_section_main'
    );

    add_settings_field(
        'welcome_text',
        'Текст приветствия',
        'wpaction_welcome_text_cb',
        'wpaction-theme-settings',
        'wpaction_section_main'
    );

    add_settings_field(
        'show_widget',
        'Показывать виджет',
        'wpaction_show_widget_cb',
        'wpaction-theme-settings',
        'wpaction_section_main'
    );
}
add_action('admin_init', 'wpaction_register_theme_settings');

В этом коде мы создаём группу настроек, секцию и три поля. Теперь опишем функции обратного вызова для секции и полей.

Описание секции настроек

Функция, которая выводит описание секции:

function wpaction_section_main_cb() {
    echo '<p>Настройте внешний вид вашей темы и основные параметры.</p>';
}

Функции обратного вызова для полей

Для каждого поля создадим функцию вывода HTML формы:

function wpaction_background_color_cb() {
    $options = get_option('wpaction_theme_options');
    $color = isset($options['background_color']) ? esc_attr($options['background_color']) : '#ffffff';
    echo '<input type="color" name="wpaction_theme_options[background_color]" value="'. $color .'" />';
}

function wpaction_welcome_text_cb() {
    $options = get_option('wpaction_theme_options');
    $text = isset($options['welcome_text']) ? esc_attr($options['welcome_text']) : '';
    echo '<input type="text" name="wpaction_theme_options[welcome_text]" value="'. $text .'" class="regular-text" />';
}

function wpaction_show_widget_cb() {
    $options = get_option('wpaction_theme_options');
    $checked = !empty($options['show_widget']) ? 'checked' : '';
    echo '<input type="checkbox" name="wpaction_theme_options[show_widget]" '. $checked .' /> Показывать виджет на главной странице';
}

Валидация и очистка данных настроек

Для безопасности и корректной работы важно валидировать и очищать данные перед сохранением. Напишем функцию валидации:

function wpaction_validate_theme_options($input) {
    $output = array();

    // Проверяем цвет — должен быть в формате HEX
    if (isset($input['background_color']) && preg_match('/^#[a-f0-9]{6}$/i', $input['background_color'])) {
        $output['background_color'] = $input['background_color'];
    } else {
        add_settings_error('wpaction_theme_options', 'invalid_color', 'Введите корректный цвет в формате HEX, например #ffffff');
    }

    // Очищаем текст приветствия
    if (isset($input['welcome_text'])) {
        $output['welcome_text'] = sanitize_text_field($input['welcome_text']);
    }

    // Чекбокс — булево значение
    $output['show_widget'] = !empty($input['show_widget']) ? 1 : 0;

    return $output;
}

Вывод страницы настроек в админке

Функция вывода HTML формы настроек:

function wpaction_render_theme_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки темы WPAction</h1>
        <form action="options.php" method="post">
            <?php
            settings_fields('wpaction_theme_options_group');
            do_settings_sections('wpaction-theme-settings');
            submit_button('Сохранить настройки');
            ?>
        </form>
    </div>
    <?php
}

Пример использования настроек в теме

Как применить полученные настройки в шаблоне темы, например, в header.php:

$options = get_option('wpaction_theme_options');
$bg_color = isset($options['background_color']) ? $options['background_color'] : '#ffffff';
$welcome = isset($options['welcome_text']) ? $options['welcome_text'] : 'Добро пожаловать!';
$show_widget = !empty($options['show_widget']);

?>
<style>
    body { background-color: <?php echo esc_attr($bg_color); ?>; }
</style>

<div class="welcome-message"><?php echo esc_html($welcome); ?></div>

<?php if ($show_widget): ?>
    <div class="custom-widget">Здесь ваш виджет</div>
<?php endif; ?>

Рекомендации по улучшению и расширению панели настроек

1. Можно добавить больше полей: выпадающие списки, радиокнопки, загрузку изображений через wp_media и т.д.

2. Используйте кастомные стили и скрипты для улучшения UX панели настроек.

3. Рассмотрите возможность интеграции с Customizer API для живого предпросмотра изменений.

4. Для сложных настроек можно сделать отдельные страницы или вкладки с табами.

5. Используйте gettext-функции (__(), _e()) для перевода названий и описаний.

Полезные плагины для управления настройками темы

Если не хотите писать настройки вручную, можно использовать готовые плагины:

• Redux Framework — мощный фреймворк для создания панелей настроек с множеством типов полей;
• Kirki — интегрируется с Customizer API, позволяет быстро создавать удобный интерфейс;
• OptionTree — классический плагин для добавления опций в темы;
• Carbon Fields — современный инструмент для создания настроек, мета-полей и кастомных блоков.

Использование этих плагинов может значительно сэкономить время разработки и обеспечить гибкость.