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

  • Не объявляйте блок устаревшим и создайте новый (с другим именем)
  • Предоставьте «устаревшую» версию блока, позволяющую пользователям, открывающим эти блоки в Гутенберге, редактировать их с помощью обновленного блока.

У блока может быть несколько устаревших версий. Устаревание будет предпринято, если проанализированный блок окажется недействительным или если определено устаревание, для которого его функция свойства 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>;
            },
        }
    ]
} );

В приведенном выше примере мы обновили блок, чтобы использовать внутренний блок абзаца с заголовком вместо атрибута заголовка.

Выше приведены примеры устаревания блоков. Чтобы увидеть больше реальных примеров, проверьте наличие устаревания в библиотеке основных блоков. Основные блоки были обновлены в разных выпусках и содержат простые и сложные устаревшие элементы.