バリエーション

ブロックバリエーション 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 フラグを設定すると、インサーターで通常のブロックタイプが上書きされます。これは特定のニーズに合わせてエディター体験を向上する、素晴らしい仕組みです。

例えば「メディアとテキスト」ブロックで、デフォルトで右側に画像を表示するには、次のようなバリエーションを作成できます。

 wp.blocks.registerBlockVariation(
	'core/media-text', 
	{
		name: 'media-text-media-right',
		title: __( 'Media & Text' ),
		isDefault: true,
		attributes: { 
			mediaPosition: 'right'
		}
	}
)

isDefault は、既存のバリエーションが存在しないブロックをオーバーライドする際はうまく機能しますが、他のバリエーションが存在する場合は、問題が発生するかもしれません。

同じブロックの別のバリエーションが isDefault を使用すると、希望したバリエーションがデフォルトにならないかもしれません。エディターは最初に登録された isDefault を持つバリエーションを優先します。

これを解決するには isDefault でバリエーションを登録する前に、他のバリエーションの登録を解除します。この解決策、前述した、バリエーションには常に一意の name をつける推奨を裏付けるものです。一意の名前でなければ、バリエーションを登録解除できません。

isActive プロパティはオプションですが、ブロックが挿入された後にブロックバリエーションに関する情報を表示するために使用したいケースがままあります。例えば、この API は useBlockDisplayInformation フックで使用され、BlockCard や Breadcrumbs コンポーネントのように、その場で適切な情報を取得して表示します。

isActive が設定されていないと、エディターはオリジナルのブロックとバリエーションを区別できず、オリジナルのブロック情報が表示されます。

このプロパティには、関数か文字列の配列（string[]）を使用できます。この関数は blockAttributes と variationAttributes を取り、バリデーションがアクティブかどうかの決定に使用できます。埋め込みブロックでの主な差別化ポイントは providerNameSlug 属性のため、例えば YouTube 埋め込みバリエーションがアクティブかどうかを判断するには、次のようにします。

isActive: ( blockAttributes, variationAttributes ) =>
	blockAttributes.providerNameSlug === variationAttributes.providerNameSlug,

また、string[] を使用して、どの属性を比較するかを省略して指定できます。この場合、それぞれの属性がチェックされ、すべての属性が一致した場合にそのバリエーションがアクティブになります。YouTube 埋め込みバリエーションの同じ例を使用すると、文字列バージョンは次のようになります。

isActive: [ 'providerNameSlug' ]

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現在、依然として注意すべき問題のままです。

原文

最終更新日: 2023年9月9日