バリエーション
Topics
ブロックバリエーション 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 は useBlockDisplayInformation
フックで使用され、BlockCard
や Breadcrumbs
コンポーネントのように、その場で適切な情報を取得して表示します。
isActive
が設定されていないと、エディターはオリジナルのブロックとバリエーションを区別できず、オリジナルのブロック情報が表示されます。
このプロパティには、関数か文字列の配列(string[]
)を使用できます。この関数は blockAttributes
と variationAttributes
を取り、バリデーションがアクティブかどうかの決定に使用できます。埋め込みブロックでの主な差別化ポイントは providerNameSlug
属性のため、例えば YouTube 埋め込みバリエーションがアクティブかどうかを判断するには、次のようにします。
isActive: ( blockAttributes, variationAttributes ) =>
blockAttributes.providerNameSlug === variationAttributes.providerNameSlug,
また、string[]
を使用して、どの属性を比較するかを省略して指定できます。この場合、それぞれの属性がチェックされ、すべての属性が一致した場合にそのバリエーションがアクティブになります。YouTube 埋め込みバリエーションの同じ例を使用すると、文字列バージョンは次のようになります。
isActive: [ 'providerNameSlug' ]
isActive を使用する際の注意点
isActive
プロパティは、特定のブロックに複数のバリエーションが存在し、isActive
チェックが十分にスコープを絞っていないと、偽陽性を返すことがあります。次の例を考えます。
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' ]
}
);
両方のバリエーションの isActive
チェックでは textColor
がテストされますが、それぞれのバリエーションでは vivid-red
が使用されます。paragraph-red
バリエーションが最初に登録されるため、paragraph-red-grey
バリエーションがエディタに挿入されると、タイトルは Red/Grey Paragraph
ではなく、Red Paragraph
になります。エディターは一致するものを見つけるとすぐにチェックをやめます。
API をどのように改善するかについて議論が行われてきましたが、WordPress 6.3現在、依然として注意すべき問題のままです。
最終更新日: