ブロックバリエーション API を使用すると、ブロックの複数のバージョン (バリエーション) を定義できます。ブロックバリエーションは元のブロックと比べて、初期属性やインナーブロックのセットが異なります。ブロックバリエーションをエディターに挿入すると、これらの属性やインナーブロックが適用されます。
バリエーションは、既存のブロックに似たブロックを、まったく新規にゼロから作成するのではなく、反復して作成する優れた方法です。
この API の理解のために「埋め込み」ブロックを考えます。このブロックには埋め込み可能なコンテンツの種類 (WordPress、Youtube など) ごとに、多数のバリエーションがあります。それぞれの埋め込みブロックバリエーションは、編集、保存などの基本的な機能を共有します。名前と説明情報の他に、大きな違いが providerNameSlug
属性です。以下は、埋め込みブロックバリエーションの簡略化した例です。完全な仕様についてはソースコードを参照してください。
variations: [
{
name: 'wordpress',
title: 'WordPress',
description: __( 'Embed a WordPress post.' ),
attributes: { providerNameSlug: 'wordpress' },
},
{
name: 'youtube',
title: 'YouTube',
description: __( 'Embed a YouTube video.' ),
attributes: { providerNameSlug: 'youtube' },
},
],
ブロックバリエーションの定義
ブロックバリエーションは、以下のフィールドを含むオブジェクトによって定義されます。
name
(タイプstring
) – 機械で識別可能な、一意の名前。title
(オプション、タイプstring
) – 人間が読める、バリエーションのタイトル。description
(オプション、タイプstring
) – 人間が読める、バリエーションの説明。category
(オプション、タイプstring
) – カテゴリーの分類。検索インターフェース内で、ブロックタイプのカテゴリーごとの配置に使用される。keywords
(オプション、タイプstring[]
) – 翻訳可能なタームの配列。ユーザーがバリエーションを検索しやすくする。icon
(オプション、タイプstring
|Object
) – バリエーションの視覚化を助けるアイコン。ブロックタイプと同じ形でも良い。attributes
(オプション、タイプObject
) – ブロック属性を上書きする値。innerBlocks
(オプション、タイプArray[]
) – ネストしたブロックの初期構成。example
(オプション、タイプObject
) – ブロックプレビューの構造化データを提供する。プレビューを無効化するには、undefined
を設定する。詳細については ブロック登録 API を参照してください。scope
(オプション、タイプWPBlockVariationScope[]
) – デフォルトはblock
とinserter
。バリエーションが適用可能なスコープのリスト。指定可能なオプション:block
– 特定のブロックバリエーションをフィルタリングするためにブロックで使用される。Columns
ブロックとQuery
ブロックにそのようなバリエーションがあり、実験的な BlockVariationPicker コンポーネントに渡される。このコンポーネントはバリエーションの表示を処理し、ユーザーはその中から1つを選択できる。inserter
– ブロックバリエーションはインサーターに表示される。transform
– ブロックバリエーションはブロックバリエーション変換のコンポーネント内で表示される。
isDefault
(オプション、タイプboolean
) – デフォルトはfalse
。現行のバリエーションがデフォルトかどうかを示す (詳細は後述)。isActive
(オプション、タイプFunction|string[]
) – 関数、またはブロック属性の配列。ブロックが選択された際、バリエーションがアクティブかどうかの決定に使用される。関数はblockAttributes
とvariationAttributes
を取る (詳細は後述)。
メモ: 技術的には一意の name
を付けずにブロックバリエーションを作成できますが、これは推奨されません。一意な名前をつけることで、エディターはバリエーションを他のバリエーションから区別できます。また、必要に応じてバリエーションを登録解除でき、これは isDefault
設定にも関連します (詳細は後述)。
ブロックバリエーションの作成
ブロックバリエーションはブロックの登録時に宣言できます。上の例のように variations
キーに適切なバリエーションオブジェクトの配列を指定します。詳細については ブロック登録 API を参照してください。
コアブロックのような既存ブロックにバリエーションを作成するには、wp.blocks.registerBlockVariation()
を使用します。この関数はブロックの名前と、バリエーションを定義するオブジェクトを取ります。
wp.blocks.registerBlockVariation( 'core/embed', {
name: 'custom-embed',
attributes: { providerNameSlug: 'custom' },
} );
ブロックバリエーションの削除
ブロックバリエーションはまた、簡単に削除できます。それには wp.blocks.unregisterBlockVariation()
を使用します。この関数はブロックの名前と、登録を解除するバリエーションの name
を取ります。
wp.blocks.unregisterBlockVariation( 'core/embed', 'youtube' );
ブロックバリエーションとブロックスタイルの比較
ブロックスタイルとブロックバリエーションの主な違いですが、ブロックスタイルはブロックに CSS クラスを適用するだけです。これはブロックにスタイルを適用する代替の方法です。詳細はブロックスタイル API を参照してください。
一方、初期属性やインナーブロックを適用したければ、ブロックバリエーションの領域になります。また、ブロックバリエーションを定義する際に className
属性を使用することで、デフォルトのブロックスタイルを上書きできます。
variations: [
{
name: 'blue',
title: __( 'Blue Quote' ),
isDefault: true,
attributes: {
color: 'blue',
className: 'is-style-blue-quote'
},
icon: 'format-quote',
isActive: ( blockAttributes, variationAttributes ) =>
blockAttributes.color === variationAttributes.color
},
],
isDefault の使用
デフォルトでは、すべてのバリエーションは元のブロックタイプのアイテムと共に、インサーターに表示されます。しかし、リストされる任意のバリエーションに isDefault
フラグを設定すると、インサーターで通常のブロックタイプが上書きされます。これは特定のニーズに合わせてエディター体験を向上する、素晴らしい仕組みです。
例えば「メディアとテキスト」ブロックで、デフォルトで右側に画像を表示するには、次のようなバリエーションを作成できます。
wp.blocks.registerBlockVariation( 'core/media-text', {
name: 'media-text-media-right',
title: __( 'Media & Text' ),
isDefault: true,
attributes: {
mediaPosition: 'right',
},
} );
isDefault を使用する際の注意点
isDefault
は、既存のバリエーションが存在しないブロックをオーバーライドする際はうまく機能しますが、他のバリエーションが存在する場合は、問題が発生するかもしれません。
同じブロックの別のバリエーションが isDefault
を使用すると、希望したバリエーションがデフォルトにならないかもしれません。エディターは最初に登録された isDefault
を持つバリエーションを優先します。
これを解決するには isDefault
でバリエーションを登録する前に、他のバリエーションの登録を解除します。この解決策は前述した推奨「バリエーションには常に一意の name
をつける」を裏付けるものです。一意の名前でなければ、バリエーションを登録解除できません。
isActive の使用
isActive
プロパティはオプションですが、推奨です。この API はブロックエディターで使用され、どのバリエーションがアクティブかをチェックし、エディターでバリエーションのインスタンスが選択されたときに、正しいバリエーションのタイトル、アイコン、説明を表示します。
isActive
が設定されていなければ、エディターはオリジナルのブロックとバリエーションのインスタンスを区別できず、オリジナルのブロック情報が表示されます。
このプロパティには文字列の配列 (string[]
)、または関数を設定できますが、可能な限り、文字列配列のバージョンを使用することを推奨します。
string[]
バージョンを使用して、ブロックインスタンスのどの属性を与えられたバリエーションと比較すればよいかを宣言します。それぞれの属性がチェックされ、すべてが一致した場合にバリエーションが有効になります。
例として、コアの埋め込みブロックでは、providerNameSlug
属性が埋め込みプロバイダの決定に使用されます (例えば、’youtube’ や ‘twitter’)。バリエーションは次のように宣言します。
const variations = [
{
name: 'twitter',
title: 'Twitter',
icon: embedTwitterIcon,
keywords: [ 'tweet', __( 'social' ) ],
description: __( 'Embed a tweet.' ),
patterns: [ /^https?:\/\/(www\.)?twitter\.com\/.+/i ],
attributes: { providerNameSlug: 'twitter', responsive: true },
},
{
name: 'youtube',
title: 'YouTube',
icon: embedYouTubeIcon,
keywords: [ __( 'music' ), __( 'video' ) ],
description: __( 'Embed a YouTube video.' ),
patterns: [
/^https?:\/\/((m|www)\.)?youtube\.com\/.+/i,
/^https?:\/\/youtu\.be\/.+/i,
],
attributes: { providerNameSlug: 'youtube', responsive: true },
},
// ...
];
isActive
プロパティは次のようになります。
isActive: [ 'providerNameSlug' ];
これにより、providerNameSlug
のブロックインスタンスの値が、バリエーションの宣言で宣言された値 (上のコードスニペットの値) と比較され、どの埋め込みバリエーションがアクティブかを決定します。
WordPress 6.6.0
からはネストしたオブジェクトパスもサポートされます。例えば、属性として query
オブジェクトを持つブロックバリエーションを考えます。そのオブジェクトの postType
プロパティだけで (その他のプロパティは無視して)、バリエーションがアクティブかどうかを決定できるなら
isActive: [ 'query.postType' ];
このプロパティの関数バージョンは、ブロックインスタンスの blockAttributes
を第1引数、バリエーションに対して宣言された variationAttributes
を第2引数として受け取ります。これらの引数を比較して、このバリエーションがこのブロックインスタンスに対してアクティブかどうかを示す true
または false
を返すことで、バリエーションがアクティブかどうかを決定できます。
埋め込みブロックの同じ例を使用すると、関数バージョンは次のようになります。
isActive: ( blockAttributes, variationAttributes ) =>
blockAttributes.providerNameSlug === variationAttributes.providerNameSlug,
isActive マッチの詳細度
注意: WordPress 6.6.0
以降で改良された処理です。
与えられたブロックインスタンスに対して、isActive
チェックがマッチする複数のバリエーションがあり、それらすべてが文字列配列である場合、最も高い 詳細度 (specificity) を持つバリエーションが選択されます。次の例を考えます。
wp.blocks.registerBlockVariation( 'core/paragraph', {
name: 'paragraph-red',
title: 'Red Paragraph',
attributes: {
textColor: 'vivid-red',
},
isActive: [ 'textColor' ],
} );
wp.blocks.registerBlockVariation( 'core/paragraph', {
name: 'paragraph-red-grey',
title: 'Red/Grey Paragraph',
attributes: {
textColor: 'vivid-red',
backgroundColor: 'cyan-bluish-gray',
},
isActive: [ 'textColor', 'backgroundColor' ],
} );
あるブロックインスタンスに textColor: vivid-red
と backgroundColor: cyan-bluish-gray
の属性があれば、上の両方のバリエーションの isActive
条件にマッチします。このケースでは、より 詳細 (specific) なマッチがアクティブバリエーションと判断され、その詳細度は各 isActive
配列の長さとして計算されます。つまり、Red/Grey Paragraph
がアクティブバリエーションとして表示されます。
注意: isActive
プロパティが string[]
ではなく、関数の場合、バリエーションのマッチにおいて特異性を決定できません。このとき、最初にマッチしたバリエーションがアクティブなバリエーションとして決定されます。この理由により、一般には isActive
プロパティに function
ではなく string[]
を使用することが推奨されます。