バリエーション

ブロックバリエーション 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' },
} );

PHP でのブロックバリエーションの登録

ブロックバリエーションは get_block_type_variations フィルターフックを使用して PHP からでも登録できます。この方法は特に、登録された投稿タイプやタクソノミ、その他の WordPress データに基づいて動的にバリエーションを生成する必要がある場合に便利です。

以下は core/image ブロックにカスタムバリエーションを登録する方法の例です。

function my_custom_image_variation( $variations, $block_type ) {
	// 画像ブロックのバリエーションのみを変更する
    if ( 'core/image' !== $block_type->name ) {
        return $variations;
    }

    // カスタムバリエーションを追加する
    $variations[] = array(
		'name'        => 'wide-image',
		'title'       => __( 'Wide image', 'textdomain' ),
		'description' => __( 'A wide image', 'textdomain' ),
		'scope'       => array( 'inserter' ),
		'isDefault'   => false,
		'attributes'  => array(
			'align' => 'wide', // リンクタイプをカスタムとして識別する
		),
    );

    return $variations;
}
add_filter( 'get_block_type_variations', 'my_custom_image_variation', 10, 2 );

get_block_type_variations フィルターは、ブロックタイプのバリエーションが要求されたときに呼び出されます。このフィルターは2つのパラメータを受け取ります。

• $variations: 現在ブロックタイプに登録されているバリエーションの配列
• $block_type: 完全なブロックタイプのオブジェクト

注意: PHP で登録されたバリエーションは、JavaScript で registerBlockVariation() を使用して登録されたバリエーションとマージされます。

この詳細についてはブログ記事「PHP でブロックのバリエーションを登録する方法」をチェックしてください。

ブロックバリエーションの削除

ブロックバリエーションはまた、簡単に削除できます。それには 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[] を使用することが推奨されます。

原文