При обновлении разметки и атрибутов статических блоков авторам блоков необходимо учитывать существующие сообщения, использующие старые версии своего блока. Чтобы обеспечить хороший путь обновления, вы можете выбрать одну из следующих стратегий:
- Не объявляйте блок устаревшим и создайте новый (с другим именем)
- Предоставьте «устаревшую» версию блока, позволяющую пользователям, открывающим эти блоки в Гутенберге, редактировать их с помощью обновленного блока.
У блока может быть несколько устаревших версий. Устаревание будет предпринято, если проанализированный блок окажется недействительным или если определено устаревание, для которого его функция свойства isEligible
возвращает значение true.
Устаревание определяется в типе блока как его свойство deprecated
, массив объектов устаревания, где каждый объект принимает форму:
attributes
(Объект): Определение атрибутов устаревшей формы блока.support
(Объект): Поддерживает определение устаревшей формы блока.save
(Функция): Сохранить реализацию устаревшей формы блока.migrate
(функция, необязательная): функция, которая, учитывая атрибуты и внутренние блоки анализируемого блока, должна возвращать либо атрибуты, совместимые с устаревшим блоком, либо массив кортежей[ attributes, innerBlocks ]
.isEligible
(функция, необязательная): функция, которая, учитывая атрибуты и внутренние блоки проанализированного блока, возвращает true, если устаревание может обрабатывать миграцию блока. Это особенно полезно в тех случаях, когда блок технически действителен даже после того, как он объявлен устаревшим, и требует обновления его атрибутов или внутренних блоков.
Важно отметить, что attributes
, support
и save
не наследуются автоматически от текущей версии, поскольку они могут повлиять на синтаксический анализ и сериализацию блока, поэтому они должны быть определены в устаревшем объекте, чтобы их можно было обрабатывать во время миграции.
Пример:
ESNСледующий
const { registerBlockType } = wp.blocks; const attributes = { text: { type: 'string', default: 'some random value', } };
registerBlockType( 'gutenberg/block-with-deprecated-version', {
// ... other block properties go here
attributes,
save( props ) { return <div>{ props.attributes.text }</div>; },
deprecated: [ { attributes,
save( props ) { return <p>{ props.attributes.text }</p>; }, } ] } );
В приведенном выше примере мы обновили разметку блока, чтобы использовать div
вместо p
.
Изменение набора атрибутов
Иногда вам нужно обновить набор атрибутов, чтобы переименовать или изменить старые атрибуты.
Пример:
ESNСледующий
const { registerBlockType } = wp.blocks;
registerBlockType( 'gutenberg/block-with-deprecated-version', {
// ... other block properties go here
attributes: { content: { type: 'string', default: 'some random value', } },
save( props ) { return <div>{ props.attributes.text }</div>; },
deprecated: [ { attributes: { text: { type: 'string', default: 'some random value', } },
migrate( { text } ) { return { content: text }; },
save( props ) { return <p>{ props.attributes.text }</p>; }, } ] } );
В приведенном выше примере мы обновили разметку блока, чтобы использовать div
вместо p
, и переименовали атрибут text
в content
.
Изменение внутренних блоков
Могут возникнуть ситуации, когда при переносе блока нам может потребоваться добавить или удалить innerBlocks.
Например: блок хочет перенести атрибут заголовка в абзац innerBlock.
Пример:
ESNСледующий
const { registerBlockType } = wp.blocks;
registerBlockType( 'gutenberg/block-with-deprecated-version', {
// ... block properties go here
save( props ) { return <p>{ props.attributes.title }</p>; },
deprecated: [ { attributes: { title: { type: 'array', source: 'children', selector: 'p', }, },
migrate( attributes, innerBlocks ) { return [ omit( attributes, 'title' ), [ createBlock( 'core/paragraph', { content: attributes.title, fontSize: 'large', } ), ...innerBlocks, ], ]; },
save( props ) { return <p>{ props.attributes.title }</p>; }, } ] } );
В приведенном выше примере мы обновили блок, чтобы использовать внутренний блок абзаца с заголовком вместо атрибута заголовка.
Выше приведены примеры устаревания блоков. Чтобы увидеть больше реальных примеров, проверьте наличие устаревания в библиотеке основных блоков. Основные блоки были обновлены в разных выпусках и содержат простые и сложные устаревшие элементы.