Свой виджет и блок WordPress: частые ошибки и решения

Добавить один и тот же элемент на сайт можно через виджет WordPress или блок редактора — но это не взаимозаменяемые способы. Виджет подходит для областей виджетов, например боковой панели; блок можно вставлять в записи и страницы. Если выбрать не тот механизм или смешать их без причины, вы получите лишние настройки, проблемы с переносом данных и поддержку двух интерфейсов вместо одного. Ниже — разбор для WordPress 6.5 и новее: блоки и виджеты настраиваются в редакторе сайта, а код примеров использует официальные API ядра.

Сначала выберите, где пользователь будет размещать элемент

В WordPress 5.8 появился редактор блоков для виджетов: в областях виджетов можно размещать блоки. Это не означает, что старый PHP-виджет автоматически стал блоком для записей. Классический виджет наследуется от WP_Widget; блок регистрируется через Block API и может появляться в редакторе записи, страницы или сайта.

Динамический блок¹ не хранит готовую HTML-разметку как единственный результат: WordPress вызывает PHP-функцию при выводе. Это удобно, если содержимое должно обновляться без повторного сохранения каждой записи.

Главная ошибка — начинать с вопроса «как написать виджет». Сначала определите место размещения и жизненный цикл данных: кто их вводит, где они хранятся и когда меняются.

Типичные ошибки собственного блока

Регистрируют блок вручную, а метаданные дублируют

В WordPress 6.5+ практичный базовый вариант — описать блок в block.json и зарегистрировать его в PHP через register_block_type(), указав каталог с файлом. Так имя, скрипты и поддерживаемые свойства остаются в одном описании. Если часть параметров задана и в PHP, и в метаданных, изменения легко внести только в одно место — и получить не тот редакторский интерфейс или отсутствие скрипта.

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

Сохраняют пользовательские данные как доверенную HTML-разметку

Содержимое блока или виджета может вводить пользователь с правами, отличными от администратора. Перед выводом в HTML применяйте подходящую функцию экранирования WordPress: например, текст — через esc_html(), значение атрибута — через esc_attr(), URL — через esc_url(). Не экранируйте всё одной функцией: контекст вывода важен.

Для многострочного текста, разрешённого HTML или сложной разметки сначала определите, какие теги нужны, а затем используйте соответствующую очистку и вывод. Иначе можно либо открыть путь для небезопасной разметки, либо удалить допустимое форматирование.

Путают сохранённую разметку с выводом при каждом запросе

Статический блок сохраняет содержимое в записи. Если его HTML изменится в новой версии, редактор может показать предупреждение о несовпадении сохранённой разметки. Для данных, которые должны быть актуальны на момент просмотра — например, для текущего списка записей, — рассмотрите динамический блок с серверным рендерингом. Но динамический вывод добавляет работу на стороне сервера и требует аккуратно проверять входные атрибуты.

Типичные ошибки собственного виджета

Используют методы старого учебника без проверки версии

Классический виджет должен наследоваться от WP_Widget, а экземпляр регистрируется на событии widgets_init. В коде ниже оставлены только точки входа: логику отображения и форму настроек добавляйте по требованиям проекта. Для редактора блоков этот класс сам по себе не создаёт блок.

<?php
add_action( 'widgets_init', 'site_register_notice_widget' );

function site_register_notice_widget() {
    register_widget( 'Site_Notice_Widget' );
}

class Site_Notice_Widget extends WP_Widget {
    public function __construct() {
        parent::__construct(
            'site_notice_widget',
            'Информационный виджет'
        );
    }
}

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

Забывают, что данные виджета переживают смену кода

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

Как выбирать и проверять подход

1. Зафиксируйте место вставки. Если редактор должен размещать элемент в тексте записи, делайте блок. Если он нужен только в области виджетов темы — рассмотрите WP_Widget. Проверка: сценарий использования можно описать одним предложением без «и ещё пусть будет везде».
2. Определите источник данных. Решите, сохраняется ли текст вместе с записью, в настройках виджета или вычисляется при просмотре. Проверка: после повторного открытия редактора введённые параметры остаются на месте.
3. Выберите статический или динамический вывод блока. Меняющиеся данные обычно требуют серверного вывода; неизменяемое содержимое записи часто достаточно сохранить в блоке. Проверка: изменение данных отображается именно тогда, когда этого ждёт редактор.
4. Проверьте два контекста. Посмотрите элемент в редакторе и на публичной странице, с пустыми и заполненными значениями. Проверка: нет предупреждения о повреждённом блоке, пустые поля не ломают разметку, вывод безопасен.
5. Проверьте обновление и удаление. Обновите плагин или тему на копии сайта, затем удалите тестовый экземпляр. Проверка: старые настройки не пропали неожиданно, а удаление не оставило критически важный контент в неожиданном состоянии.

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

• Блок не появляется. Проверьте, что PHP-код регистрации выполняется, путь ведёт к каталогу блока, а сборка создала файлы из метаданных.
• В редакторе есть блок, на сайте пусто. Для динамического блока проверьте серверную функцию вывода и входные атрибуты; для статического — что разметка действительно сохраняется в записи.
• После правки блок показывает предупреждение. Сравните текущую сохранённую разметку с ожидаемой редактором. Если формат блока изменился, предусмотрите совместимость или миграцию данных, а не отключайте проверку вслепую.
• Старый виджет исчез из области. Проверьте регистрацию класса, его идентификатор и изменения структуры настроек. Тестируйте на копии сайта до выпуска.

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

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

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

¹ Динамический блок — блок, для которого WordPress формирует разметку на сервере при отображении страницы, а не полагается только на HTML, сохранённый в записи.