Как создать настройку темы WordPress в админке через Customizer API

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

Что такое Customizer API и зачем он нужен в теме WordPress

WordPress Customizer API предоставляет разработчикам удобный интерфейс для добавления настроек темы через раздел «Внешний вид — Настроить». Это современный способ дать пользователю возможность менять цвета, шрифты, лого, тексты и другие параметры темы в реальном времени с предварительным просмотром.

Использование Customizer API позволяет упорядочить настройки, сделать их понятными и интегрированными в стандартный интерфейс WordPress, что повышает удобство и качество темы.

Для добавления настроек мы пишем код в файле functions.php или в отдельном файле, который подключаем к теме.

Основные компоненты Customizer API: секции, настройки и контролы

Для создания настройки темы нужно работать с тремя основными элементами:

• Секция (section) — логический блок в настройках, объединяющий связанные параметры. Например, «Цвета», «Шрифты», «Логотип».
• Настройка (setting) — конкретный параметр, значение которого сохраняется в базе данных, например, цвет заголовка, URL логотипа и т.п.
• Контрол (control) — элемент интерфейса (поле ввода, переключатель, селект и т.д.), с помощью которого пользователь меняет значение настройки.

Все эти элементы регистрируются с помощью методов объекта $wp_customize, который передаётся в коллбэк функцию, зарегистрированную на хук customize_register.

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

Давайте создадим секцию «Цвета», настройку wp_themes_header_color и контрол выбора цвета, который будет менять цвет заголовка сайта.

add_action('customize_register', 'wp_themes_customize_register');
function wp_themes_customize_register($wp_customize) {
    // Добавляем секцию
    $wp_customize->add_section('wp_themes_colors_section', [
        'title' => 'Цвета темы',
        'priority' => 30,
    ]);

    // Добавляем настройку
    $wp_customize->add_setting('wp_themes_header_color', [
        'default' => '#000000',
        'sanitize_callback' => 'sanitize_hex_color',
    ]);

    // Добавляем контрол выбора цвета
    $wp_customize->add_control(new WP_Customize_Color_Control($wp_customize, 'wp_themes_header_color_control', [
        'label' => 'Цвет заголовка',
        'section' => 'wp_themes_colors_section',
        'settings' => 'wp_themes_header_color',
    ]));
}

В коде мы создали секцию, где пользователь увидит настройки цветов, добавили параметр wp_themes_header_color с дефолтным значением и контрол выбора цвета.

Использование настройки в теме: вывод цвета заголовка

Чтобы применить выбранный цвет в теме, нужно вывести его в CSS. Для этого можно использовать динамический вывод стилей в header.php или подключить инлайн-стили через хук wp_head:

add_action('wp_head', 'wp_themes_custom_header_color_style');
function wp_themes_custom_header_color_style() {
    $color = get_theme_mod('wp_themes_header_color', '#000000');
    echo "<style> 
        h1.site-title { color: " . esc_attr($color) . "; } 
    </style>";
}

Теперь заголовок сайта будет менять цвет в соответствии с выбором пользователя в настройках темы.

Добавление текстовой настройки с валидацией

Помимо цветов, часто нужно добавить текстовые поля, например, для ввода контактного телефона или слогана. Пример настройки с валидацией:

add_action('customize_register', 'wp_themes_customize_text_setting');
function wp_themes_customize_text_setting($wp_customize) {
    $wp_customize->add_section('wp_themes_contact_section', [
        'title' => 'Контактные данные',
        'priority' => 40,
    ]);

    $wp_customize->add_setting('wp_themes_phone_number', [
        'default' => '',
        'sanitize_callback' => 'wp_themes_sanitize_phone',
    ]);

    $wp_customize->add_control('wp_themes_phone_number_control', [
        'label' => 'Телефон',
        'section' => 'wp_themes_contact_section',
        'settings' => 'wp_themes_phone_number',
        'type' => 'text',
    ]);
}

function wp_themes_sanitize_phone($phone) {
    // Убираем все кроме цифр, пробелов, плюса, дефиса
    return preg_replace('/[^0-9\s\-\+]/', '', $phone);
}

В этом примере настроена секция «Контактные данные» с текстовым полем для телефона, в котором очищаются все неподходящие символы.

Добавление выбора из списка (селект) и чекбокса

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

add_action('customize_register', 'wp_themes_customize_select_checkbox');
function wp_themes_customize_select_checkbox($wp_customize) {
    $wp_customize->add_section('wp_themes_options_section', [
        'title' => 'Опции темы',
        'priority' => 50,
    ]);

    // Селект
    $wp_customize->add_setting('wp_themes_layout_style', [
        'default' => 'full',
        'sanitize_callback' => 'wp_themes_sanitize_layout',
    ]);

    $wp_customize->add_control('wp_themes_layout_style_control', [
        'label' => 'Стиль макета',
        'section' => 'wp_themes_options_section',
        'settings' => 'wp_themes_layout_style',
        'type' => 'select',
        'choices' => [
            'full' => 'Полная ширина',
            'boxed' => 'В коробке',
        ],
    ]);

    // Чекбокс
    $wp_customize->add_setting('wp_themes_show_author', [
        'default' => true,
        'sanitize_callback' => 'wp_themes_sanitize_checkbox',
    ]);

    $wp_customize->add_control('wp_themes_show_author_control', [
        'label' => 'Показывать автора записи',
        'section' => 'wp_themes_options_section',
        'settings' => 'wp_themes_show_author',
        'type' => 'checkbox',
    ]);
}

function wp_themes_sanitize_layout($input) {
    $valid = ['full', 'boxed'];
    return in_array($input, $valid) ? $input : 'full';
}

function wp_themes_sanitize_checkbox($checked) {
    return ($checked === true || $checked === '1') ? true : false;
}

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

Использование популярных плагинов для расширения возможностей Customizer

Хотя Customizer API мощный сам по себе, для ускорения разработки и улучшения интерфейса можно использовать плагины:

• Kirki — позволяет создавать сложные настройки с минимальным кодом, поддерживает цветовые палитры, иконки, шрифты и многое другое.
• Customizer Custom Controls — добавляет новые типы контролов, например, иконки, переключатели, слайдеры.
• Redux Framework — мощный фреймворк для создания панелей настроек, интегрируемый с Customizer.

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

Советы по безопасности и валидации данных в Customizer

Очень важно всегда использовать функции очистки и проверки данных (sanitize_callback) для настроек, чтобы избежать сохранения вредоносного кода и ошибок. WordPress предоставляет готовые функции, например, sanitize_text_field, sanitize_hex_color, absint и др.

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

Подведение итогов и рекомендации

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

Пишите чистый и структурированный код, используйте встроенные функции WordPress для безопасности и всегда тестируйте настройки в разных сценариях.

Если хотите быстро и удобно расширять настройки, попробуйте интегрировать популярные библиотеки и плагины для Customizer.