Свой виджет и блок WordPress: как выбрать и сделать правильно

Если редактору нужно добавлять контент в записи, делайте блок; если администратор сайта настраивает область темы вроде боковой панели или подвала — виджет. В WordPress 6.x эти интерфейсы пересекаются, но не заменяют друг друга: попытка засунуть настройки виджета в блок часто оборачивается неудобным редактором, а старый виджет не становится блоком только потому, что его можно добавить через блок «Виджеты».

Сначала определите, кто и где настраивает контент

Один и тот же компонент может показываться на сайте, но путь до него в админке разный. Блок редактор добавляет в содержание записи или страницы. Виджет привязывают к области темы — например, к боковой панели. В блочной теме области и шаблоны настраивают через редактор сайта; в классической теме обычно работают экран «Внешний вид → Виджеты» и области, объявленные темой.

В WordPress 6.x классический виджет может отображаться в редакторе виджетов как Legacy Widget — блок-обёртка для старого интерфейса. Это не превращает его в самостоятельный блок: внутри остаются поля и поведение исходного виджета.

Область виджетов — участок темы, куда администратор помещает один или несколько виджетов. Тема может не предоставлять боковую панель вовсе; это не ошибка самого виджета.

Виджет: минимальная регистрация без лишней логики

В классической теме виджет регистрируют через API WP_Widget. Пример ниже для WordPress 6.x и PHP 7.4 или новее: он выводит заголовок и короткий текст. Поместите класс в файл плагина, затем зарегистрируйте его. В реальном проекте добавьте проверку входных данных для тех полей, которые принимает виджет.

<?php
class Site_Notice_Widget extends WP_Widget {
    public function __construct() {
        parent::__construct(
            'site_notice_widget',
            'Короткое объявление'
        );
    }

    public function widget( $args, $instance ) {
        $title = isset( $instance['title'] )
            ? sanitize_text_field( $instance['title'] )
            : '';
        $text = isset( $instance['text'] )
            ? sanitize_textarea_field( $instance['text'] )
            : '';

        echo $args['before_widget'];
        if ( '' !== $title ) {
            echo $args['before_title'] . esc_html( $title ) . $args['after_title'];
        }
        if ( '' !== $text ) {
            echo '<p>' . nl2br( esc_html( $text ) ) . '</p>';
        }
        echo $args['after_widget'];
    }

    public function form( $instance ) {
        $title = isset( $instance['title'] )
            ? $instance['title']
            : '';
        $text = isset( $instance['text'] )
            ? $instance['text']
            : '';
        ?>
        <p>
            <label for="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>">Заголовок</label>
            <input class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>">
        </p>
        <p>
            <label for="<?php echo esc_attr( $this->get_field_id( 'text' ) ); ?>">Текст</label>
            <textarea class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'text' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'text' ) ); ?>"><?php echo esc_textarea( $text ); ?></textarea>
        </p>
        <?php
    }

    public function update( $new_instance, $old_instance ) {
        return array(
            'title' => sanitize_text_field( $new_instance['title'] ?? '' ),
            'text'  => sanitize_textarea_field( $new_instance['text'] ?? '' ),
        );
    }
}

add_action( 'widgets_init', function () {
    register_widget( 'Site_Notice_Widget' );
} );

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

Блок: регистрация через метаданные

Для собственного блока в WordPress 6.x удобнее хранить метаданные в block.json, а не собирать параметры регистрации в одном PHP-файле. Сам блок обычно состоит из редакторской части и кода, который выводит результат на сайте; для полноценного блока также нужны клиентские файлы редактора. Когда эти файлы собраны в каталог build, PHP-регистрация выглядит так:

<?php
add_action( 'init', function () {
    register_block_type( __DIR__ . '/build' );
} );

Путь должен вести к каталогу, где лежит созданный при сборке block.json. Если указать исходную папку или не включить сборку в релиз, регистрация не найдёт нужные файлы. Для простого динамического вывода задайте в метаданных серверный файл рендеринга или зарегистрируйте обработчик на PHP; детали зависят от структуры блока, поэтому не копируйте случайный пример с несуществующими полями.

У блока есть своя схема настроек: тип и значения атрибутов должны согласовываться с интерфейсом редактора и тем, что сервер ожидает при выводе. Не храните в атрибуте произвольный HTML, если достаточно строки или выбранного идентификатора. На выводе экранируйте значения по контексту, а не полагайтесь на то, что редактор уже очистил их.

Правильный компонент — не тот, который удалось зарегистрировать. Это тот, который редактору удобно настроить именно в том месте, где он появится, и который не теряет настройки после обновления темы или плагина.

Что ломается чаще всего

• Виджет не появляется. Проверьте активацию плагина, наличие класса в момент вызова register_widget() и то, что тема предоставляет область виджетов.
• Блок есть в редакторе, но пропал на сайте. Проверьте, что каталог сборки попал на сервер, путь регистрации верен, а серверная часть блока подключается без ошибки PHP.
• Поля сохраняют неверный формат. Санитизируйте значения при сохранении и экранируйте при выводе. Это разные этапы: очистка входных данных не заменяет безопасный вывод.
• Обновление перезаписало правки. Не редактируйте файлы ядра или сторонней темы. Размещайте код в плагине либо дочерней теме, которую вы контролируете.
• В редакторе виджетов виден только Legacy Widget. Это ожидаемо для старого виджета. Если нужен полноценный блок с собственными настройками, его придётся разработать отдельно.

Как выбрать и проверить перед запуском

Если компонент нужен только в сайдбаре классической темы, виджет дешевле в разработке и поддержке. Если редактор должен ставить его в разные места контента и настраивать поля прямо в редакторе записи, выбирайте блок. Для блочной темы сначала проверьте, как пользователь будет размещать компонент в шаблоне: привычный экран виджетов может не участвовать в его рабочем процессе.

1. Зафиксируйте место размещения и роль пользователя, который будет менять содержимое. Проверка: понятно, где компонент настраивают — в записи, шаблоне или области темы.
2. Создайте компонент в тестовом окружении на той же версии WordPress, что и рабочий сайт. Проверка: он появляется в ожидаемом разделе админки.
3. Сохраните настройки, обновите страницу редактора и откройте сайт. Проверка: поля сохранились, а вывод совпадает с настройками.
4. Проверьте удалённое или пустое значение и вывод на мобильном экране. Проверка: компонент не показывает пустую оболочку и не ломает разметку темы.
5. Установите плагин на чистую копию сайта. Проверка: компонент работает без файлов и настроек, оставшихся только в вашей среде разработки.

Что делать дальше

После проверки выберите одну тестовую страницу или область темы и попросите редактора изменить настройки без помощи разработчика. Затем проверьте журнал ошибок PHP и разметку на реальном шаблоне. Для блока отдельно проверьте сборку и содержимое релизного архива; для виджета — поведение при смене темы, особенно если области виджетов у тем отличаются.