Устаревание блоков Gutenberg: обновление без нарушения контента

Резюме

Обновление блока Gutenberg часто ломает существующие записи, использующие старую версию. В этой статье показано, как использовать свойство deprecated в block.json для обеспечения обратной совместимости. Вы узнаете точные шаги по захвату текущей разметки блока, определению одной или нескольких устаревших версий и правильному отображению атрибутов. Мы рассмотрим как статические, так и динамические блоки с практическими примерами. Статья также оспаривает предположение, что устаревание всегда является лучшим подходом, обсуждая, когда чистый разрыв может быть предпочтительнее. К концу вы сможете уверенно обновлять свои блоки, не нарушая контент пользователей.

Сценарий разрушающего изменения

Шесть месяцев назад вы запустили кастомный блок отзывов. Он выводит простой <div> с цитатой и именем автора. Теперь ваш клиент хочет новый дизайн: автор должен быть над цитатой с другим CSS-классом. Вы обновляете функцию save блока и render_callback. Вы тестируете на новом посте — выглядит отлично. Затем вы переходите к старому посту, использующему блок. Катастрофа: текст цитаты пропал, автор не на своем месте, стили сбиты. Вы только что сломали каждую страницу, использующую блок.

Это классическая проблема «разрушающего изменения» в разработке блоков Gutenberg. Блоки по сути являются структурами данных, объединенными с разметкой. Когда вы меняете разметку, редактор не может автоматически сопоставить старый контент с новой структурой. Результатом является либо ошибка валидации (блок становится недействительным), либо — что хуже — молчаливое повреждение, при котором блок отображается некорректно.

Что такое устаревание блоков?

Устаревание блоков — это встроенный механизм Gutenberg для обработки изменений версий. Определив массив deprecated в вашем block.json, вы сообщаете редактору: «Если вы встретите блок, соответствующий одной из этих старых версий, преобразуйте его в текущую версию». Каждая запись устаревшей версии указывает предыдущие attributes, supports и функцию save (или render_callback). Когда редактор загружает старый блок, он перебирает массив устаревших версий по порядку и применяет первое подходящее преобразование.

Эта функция часто недоиспользуется, потому что разработчики предполагают, что им никогда не придется менять разметку блока. Но в реальных проектах требования меняются. Если вы пропустите устаревание, вы либо заставите пользователей удалять и повторно вставлять блоки (плохой опыт), либо будете поддерживать две отдельные версии блока (беспорядочно). Официальное руководство разработчика WordPress охватывает это в Block Editor Handbook, но практических пошаговых инструкций не хватает.

Шаг 1: Захват текущего состояния

Прежде чем вносить изменения, запишите точный вывод save (или render_callback для динамических блоков) и attributes, которые ваш блок использует в данный момент. Думайте об этом как о создании снимка. Для статических блоков сохраните JSX, возвращаемый функцией save. Для динамических блоков сохраните PHP-разметку, генерируемую render_callback.

Создайте новый файл в вашем плагине с именем deprecated.js (или аналогично) и сохраните там старую функцию save. Альтернативно, храните устаревшие версии непосредственно в основном JavaScript-файле блока. Ключевой момент — сохранить этот код точно таким, каким он был при первом развертывании блока.

Шаг 2: Определение устаревших версий

В вашем block.json добавьте массив deprecated. Каждая запись — это объект, который может включать:

• attributes (объект): Предыдущие определения атрибутов.
• supports (объект): Любые предыдущие настройки поддержки, которые изменились.
• save (функция или строка): Предыдущая функция save. Для блоков только на JavaScript вы импортируете старую функцию. Для динамических блоков, отображаемых через PHP, вы можете использовать migrate и render_callback вместо этого.
• migrate (функция): Функция, которая сопоставляет старые атрибуты с новыми (опционально).

Пример:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className="testimonial-legacy"><p className="quote">{attributes.quote}</p><p className="author">{attributes.author}</p></div>"
  }
]

Примечание: Функция save в block.json обычно определяется на JavaScript. Если вы используете внешний скрипт, вам нужно подключить его и указать имя функции. Альтернативно, вы можете встроить функцию как строку (хотя это не рекомендуется для сложных блоков).

Шаг 3: Сопоставление атрибутов

Часто вы меняете не только разметку, но и имена атрибутов или источники. Например, вы можете перейти от хранения автора как простой строки к полю форматированного текста. В таких случаях используйте свойство migrate для преобразования старых атрибутов в новые.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

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

Шаг 4: Тестирование с реальным контентом

После определения устаревшей версии тщательно протестируйте. Создайте новый пост, вставьте старый блок (вы можете смоделировать это, вставив сериализованный код блока из существующего поста) и убедитесь, что он преобразуется в новую версию без ошибок валидации. Также протестируйте редактирование и сохранение преобразованного блока. Повторите для нескольких устаревших версий, если они у вас есть.

Для динамических блоков процесс аналогичен, но с особенностью: функция save для динамического блока обычно возвращает null (блок отображается через PHP). В устаревшей записи вы можете либо установить save в предыдущую статическую разметку, которая использовалась до перехода на динамическое отображение, либо использовать render_callback в PHP, который обрабатывает как старую, так и новую структуры атрибутов. Это сложнее, но выполнимо.

Предостережения и компромиссы

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

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

Наконец, устаревание не обрабатывает контент, который был отредактирован с использованием общесайтового изменения стилей (например, через theme.json). Если внешний вид вашего блока зависел от глобальных стилей, которые с тех пор изменились, устаревание не скорректирует это. Возможно, вам потребуется добавить скрипт миграции, который запускается при сохранении или через хук обновления плагина.

Когда устаревание не является ответом

Большинство руководств представляют устаревание как обязательное. В реальности есть ситуации, когда чистый разрыв лучше. Если ваш блок новый и используется лишь в нескольких постах, ручное обновление этих нескольких экземпляров может быть быстрее, чем написание и тестирование кода устаревания. Аналогично, если базовая модель данных блока принципиально иная (например, вы объединяете два блока в один), устаревание может быть недостаточно гибким. В этом случае напишите одноразовый скрипт миграции, который запускается при обновлении плагина и преобразует старые блоки в новый формат.

Еще один контраргумент: устаревание не должно использоваться как замена хорошего дизайна. Если вы ожидаете частых изменений, проектируйте блок с учетом версионирования с самого начала — например, сохраняя атрибут version и используя условное отображение. Этот подход, описанный в Beyond Basic Blocks, легче, чем устаревание, но требует предвидения.

Заключение

Устаревание блоков — это важный инструмент для любого серьезного разработчика Gutenberg. Он позволяет развивать блоки без нарушения контента пользователей. Ключевые шаги: захват текущего состояния, определение устаревшей версии в block.json, сопоставление атрибутов при необходимости и тестирование с реальным контентом. Но помните, что устаревание связано с затратами на обслуживание. Иногда чистый разрыв или версионированный дизайн блока более прагматичны. Используйте устаревание стратегически, а не автоматически, и ваши блоки останутся надежными при многих обновлениях.

Для более широкого взгляда на создание поддерживаемых плагинов см. Building Robust WordPress Plugins. А если вы новичок в разработке блоков, Beyond Basic Blocks поможет вам начать.