API настройки WordPress: Полное руководство по настройке темы в 2026 году

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

Customizer API – это мощный интерфейс ядра WordPress, позволяющий владельцам сайтов и разработчикам создавать пользовательские настройки темы, которые отображаются в режиме реального времени. Благодаря postMessage и get_theme_mod() администраторы могут менять цвета, шрифты, логотипы и сразу видеть результат без перезагрузки страницы.

Для веб‑разработчиков это значит меньше времени на написание отдельной панели опций и больше гибкости в построении UI, совместимого с ядром.

Регистрация секций, настроек и контролов

Добавление секции

Секция – логический блок в Customizer, в который группируются связанные настройки. Регистрация происходит в functions.php через хук customize_register:

function mytheme_customize_register( $wp_customize ) {
    $wp_customize->add_section( 'mytheme_header_section', array(
        'title'      => __( 'Шапка сайта', 'mytheme' ),
        'priority'   => 30,
        'panel'      => 'mytheme_main_panel', // если нужен панельный контейнер
    ) );
}
add_action( 'customize_register', 'mytheme_customize_register' );

Регистрация настройки

Настройка хранит значение, которое пользователь задает в контроле. Она может иметь default, sanitize_callback и тип хранения (theme_mod или option).

$wp_customize->add_setting( 'mytheme_header_bg_color', array(
    'default'           => '#ffffff',
    'sanitize_callback' => 'sanitize_hex_color',
    'transport'         => 'postMessage', // для live preview
) );

Добавление контролов (color, image, text)

Контрол – визуальный элемент UI. WordPress уже поставляет готовые классы: WP_Customize_Color_Control, WP_Customize_Image_Control и WP_Customize_Control для текстовых полей.

// Цветовой контрол
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'mytheme_header_bg_color_control', array(
    'label'    => __( 'Цвет фона шапки', 'mytheme' ),
    'section'  => 'mytheme_header_section',
    'settings' => 'mytheme_header_bg_color',
) ) );

// Контрол изображения (логотип)
$wp_customize->add_setting( 'mytheme_logo', array(
    'sanitize_callback' => 'esc_url_raw',
    'transport'         => 'refresh',
) );
$wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'mytheme_logo_control', array(
    'label'    => __( 'Логотип сайта', 'mytheme' ),
    'section'  => 'mytheme_header_section',
    'settings' => 'mytheme_logo',
) ) );

// Текстовый контрол (слоган)
$wp_customize->add_setting( 'mytheme_tagline', array(
    'default'           => '',
    'sanitize_callback' => 'sanitize_text_field',
    'transport'         => 'postMessage',
) );
$wp_customize->add_control( 'mytheme_tagline_control', array(
    'label'    => __( 'Слоган сайта', 'mytheme' ),
    'section'  => 'mytheme_header_section',
    'type'     => 'text',
    'settings' => 'mytheme_tagline',
) );

Live preview: как обеспечить мгновенный просмотр

JavaScript‑часть (postMessage)

Для мгновенного обновления без перезагрузки необходимо подключить файл customizer.js через customize_preview_init и использовать объект wp.customize:

function mytheme_customizer_live_preview() {
    wp_enqueue_script( 'mytheme-customizer', get_template_directory_uri() . '/js/customizer.js', array( 'jquery', 'customize-preview' ), null, true );
}
add_action( 'customize_preview_init', 'mytheme_customizer_live_preview' );

Содержимое customizer.js:

( function( $ ) {
    wp.customize( 'mytheme_header_bg_color', function( value ) {
        value.bind( function( newColor ) {
            $( '.site-header' ).css( 'background-color', newColor );
        } );
    } );
    wp.customize( 'mytheme_tagline', function( value ) {
        value.bind( function( newText ) {
            $( '.site-tagline' ).text( newText );
        } );
    } );
} )( jQuery );

PHP‑часть (get_theme_mod)

В шаблонах темы выводятся значения через get_theme_mod(). При transport => 'postMessage' функция будет возвращать актуальное значение, а при refresh – только после полной перезагрузки.

<header class="site-header" style="background-color: ">
    <div class="site-branding">
        <?php if ( $logo = get_theme_mod( 'mytheme_logo' ) ) : ?>
            <img src="<?php echo esc_url( $logo ); ?>" alt="<?php bloginfo( 'name' ); ?>" class="site-logo">
        <?php endif; ?>
        <h1 class="site-title"><?php bloginfo( 'name' ); ?></h1>
        <p class="site-tagline"><?php echo esc_html( get_theme_mod( 'mytheme_tagline' ) ); ?></p>
    </div>
</header>

Полный пример темы: от регистрации до вывода

functions.php

Ниже собран полный набор функций, который можно скопировать в functions.php новой темы.

style.css и шаблоны

В style.css задайте базовые стили, а в header.php используйте полученные модификации (см. пример выше). Не забудьте объявить тему в шапке файла style.css – это требуется для правильного отображения Customizer.

Лучшие практики и распространённые ошибки

Сериализация данных

Не храните массивы в theme_mod без сериализации – WordPress автоматически сериализует, но лучше использовать json_encode/json_decode и соответствующий sanitize_callback. Это избавит от проблем при миграции.

Кеширование и производительность

Если в теме много get_theme_mod(), включите кеширование через WP_Object_Cache или используйте static переменные в функции‑обёртке. При работе с большим количеством изображений проверьте, что размер изображений оптимизирован – см. статью Как настроить PHP‑воркеры WordPress на VPS для деталей.

Также рекомендуется добавить проверку is_customize_preview() в шаблоны, чтобы не выполнять тяжёлые запросы в режиме превью.

Если хотите расширить возможности, посмотрите Шорткоды WordPress: полное руководство – они отлично сочетаются с Customizer, позволяя менять контент прямо из панели.

Для более глубокой интеграции AJAX‑запросов в кастомайзер можно воспользоваться подходом из Как добавить AJAX в WordPress. Это особенно полезно, когда нужно динамически подгружать превью шрифтов или градиентов.

И, конечно, не забывайте про SEO. Правильно настроенный Customizer не влияет на индексацию, но чистый код и быстрый рендеринг помогают достичь позиций, описанных в SEO WordPress для новичков: 6 шагов к топу.