非推奨にするブロック
ブロックの静的なマークアップや属性を更新する際、開発者は古いバージョンを使用した既存の投稿に注意する必要があります。適切にアップグレードするには以下のどちらかの戦略を選択する必要があります。
- 既存のブロックはそのままにして、新しいブロックを異なる名前で作成する。
- ブロックの「deprecated (非推奨)」バージョンを提供する。ユーザーはブロックエディターで投稿を開き、更新されたブロックを使用して編集できます。
ブロックは複数の非推奨バージョンをもつことができます。パースしたブロックが不正の場合、または、isEligible プロパティ関数で true を返して非推奨を宣言する場合、非推奨プロセス (deprecation) が実行されます。
非推奨プロセスは、ブロックタイプの deprecated プロパティに以下の形式の非推奨プロセスオブジェクトの配列として定義します。
attributes(Object): ブロックの非推奨形式の attributes 定義。supports(Object): ブロックの非推奨形式の supports 定義。save(Function): ブロックの非推奨形式の save の実装。migrate(Function、オプション): 古い属性と内部ブロックを指定すると、新しい属性、または、ブロックと互換性のある[ attributes, innerBlocks ]のタブル配列を返す関数。isEligible(Function、オプション): パースされたブロックの属性と内部ブロックを指定すると、ブロックが妥当 (valid) であっても、非推奨プロセスがブロック移行を処理できる場合に true を返す関数。ブロックが不正 (invalid) の場合にはこの関数は呼ばれません。この関数が特に有用なケースはブロックが非推奨となっても技術的には妥当 (valid) で、属性や内部ブロックの更新が必要な場合です。
重要な点として attributes、supports、save は自動で現行バージョンから継承されないことに注意してください。これはブロックのパースとシリアライゼーションに影響を与えるためです。移行中に処理されるためには非推奨オブジェクトで定義する必要があります。
例:
ESNext
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>;
},
}
]
} );
ES5
var el = wp.element.createElement,
registerBlockType = wp.blocks.registerBlockType,
attributes = {
text: {
type: 'string',
default: 'some random value',
}
};
registerBlockType( 'gutenberg/block-with-deprecated-version', {
// ... other block properties go here
attributes: attributes,
save: function( props ) {
return el( 'div', {}, props.attributes.text );
},
deprecated: [
{
attributes: attributes,
save: function( props ) {
return el( 'p', {}, props.attributes.text );
},
}
]
} );
上の例ではブロックのマークアップを更新し a の代わりに div を使用しています。
属性の変更
場合によっては属性の集合を更新して、古い属性の名前を変更したり変更する必要があります。
例:
ESNext
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.content }</div>;
},
deprecated: [
{
attributes: {
text: {
type: 'string',
default: 'some random value',
}
},
migrate( { text } ) {
return {
content: text
};
},
save( props ) {
return <p>{ props.attributes.text }</p>;
},
}
]
} );
ES5
var el = wp.element.createElement,
registerBlockType = wp.blocks.registerBlockType;
registerBlockType( 'gutenberg/block-with-deprecated-version', {
// ... other block properties go here
attributes: {
content: {
type: 'string',
default: 'some random value',
}
},
save: function( props ) {
return el( 'div', {}, props.attributes.content );
},
deprecated: [
{
attributes: {
text: {
type: 'string',
default: 'some random value',
}
},
migrate: function( attributes ) {
return {
content: attributes.text
};
},
save: function( props ) {
return el( 'p', {}, props.attributes.text );
},
}
]
} );
上の例ではブロックのマークアップを p から div に変更し、text 属性を content 属性に変更しています。
innerBlock の変更
ブロックの移行の際に、innerBlock を追加したり削除する場合もあります。 例: ブロックの title 属性を段落 innerBlock に変更する。
例:
ESNext
const { registerBlockType } = wp.blocks;
const { omit } = lodash;
registerBlockType( 'gutenberg/block-with-deprecated-version', {
// ... block properties go here
save( props ) {
return <p>{ props.attributes.title }</p>;
},
deprecated: [
{
attributes: {
title: {
type: 'string',
source: 'html',
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>;
},
}
]
} );
ES5
var el = wp.element.createElement,
registerBlockType = wp.blocks.registerBlockType,
omit = lodash.omit;
registerBlockType( 'gutenberg/block-with-deprecated-version', {
// ... block properties go here
deprecated: [
{
attributes: {
title: {
type: 'string',
source: 'html',
selector: 'p',
},
},
migrate: function( attributes, innerBlocks ) {
return [
omit( attributes, 'title' ),
[
createBlock( 'core/paragraph', {
content: attributes.title,
fontSize: 'large',
} ),
].concat( innerBlocks ),
];
},
save: function( props ) {
return el( 'p', {}, props.attributes.title );
},
}
]
} );
上の例でブロックは title 属性の代わりにタイトルをもつ段落 innerBlock に更新しています。
ここまでブロックの非推奨プロセスの例を挙げましたが、実際の使用例については コアブロックライブラリー 内の非推奨を調べてください。コアブロックはリリース全体で更新されていて、簡単なものや複雑なものなど、さまざまな非推奨プロセスがあります。
最終更新日: