ブロックのバリエーションの定義

ブロックのバリエーションは、以下のフィールドを含むオブジェクトによって定義されます：

  • 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 ブロックにはそのようなバリエーションがあり、実験的ブロックバリエーションピッカーコンポーネントに渡されます。このコンポーネントはバリエーションの表示を処理し、ユーザーがその中から1つを選択できるようにします。
    • inserter – ブロックバリエーションがインサーターに表示されます。
    • transform – ブロックバリエーションがバリエーション変換のコンポーネントに表示されます。
  • isDefault (オプション、タイプ boolean) – デフォルトは false です。現在のバリエーションがデフォルトであるかどうかを示します（詳細は以下）。

  • isActive (オプション、タイプ Function|string[]) – ブロックが選択されたときにバリエーションがアクティブかどうかを判断するために使用される関数またはブロック属性の配列。関数は blockAttributes と variationAttributes を受け入れます（詳細は以下）。

    一意の name なしでブロックバリエーションを技術的に作成することは可能ですが、これは 推奨されません。一意の name により、エディターはあなたのバリエーションと他に存在する可能性のあるバリエーションを区別できます。また、必要に応じてバリエーションを登録解除でき、isDefault 設定に影響を与えます（詳細は以下）。

ブロックバリエーションの作成

ブロックの登録中に、variations キーを適切なバリエーションオブジェクトの配列で提供することにより、ブロックバリエーションを宣言できます。詳細については、ブロック登録APIを参照してください。

既存のブロック（コアブロックなど）のバリエーションを作成するには、wp.blocks.registerBlockVariation() を使用します。この関数は、ブロックの名前とバリエーションを定義するオブジェクトを受け入れます。 

  1. wp.blocks.registerBlockVariation( 'core/embed', {
  2.    name: 'custom-embed',
  3.    attributes: { providerNameSlug: 'custom' },
  4. } );

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

ブロックバリエーションは簡単に削除することもできます。そのためには、wp.blocks.unregisterBlockVariation() を使用します。この関数は、ブロックの名前と登録解除すべきバリエーションの name を受け入れます。 

  1. wp.blocks.unregisterBlockVariation( 'core/embed', 'youtube' );

ブロックバリエーションとブロックスタイルの違い

ブロックスタイルとブロックバリエーションの主な違いは、ブロックスタイルは単にブロックにCSSクラスを適用するだけで、代替的な方法でスタイリングできることです。詳細については、ブロックスタイルAPIを参照してください。

初期属性や内部ブロックを適用したい場合、これはブロックバリエーションの領域に該当します。また、ブロックバリエーションを定義する際に className 属性を使用してデフォルトのブロックスタイルを上書きすることも可能です。 

  1. variations: [
  2.    {
  3.    name: 'blue',
  4.    title: __( 'Blue Quote' ),
  5.    isDefault: true,
  6.    attributes: {
  7.    color: 'blue',
  8.    className: 'is-style-blue-quote'
  9.    },
  10.    icon: 'format-quote',
  11.    isActive: ( blockAttributes, variationAttributes ) =>
  12.    blockAttributes.color === variationAttributes.color
  13.    },
  14. ],

isDefaultの使用

デフォルトでは、すべてのバリエーションは元のブロックタイプアイテムに加えてインサーターに表示されます。ただし、リストされた任意のバリエーションに isDefault フラグを設定すると、インサーター内の通常のブロックタイプを上書きします。これは、エディターの体験を特定のニーズに合わせてキュレーションするための優れたツールです。

たとえば、メディア＆テキストブロックをデフォルトで右側に画像を表示するようにしたい場合、次のようなバリエーションを作成できます： 

  1. wp.blocks.registerBlockVariation( 'core/media-text', {
  2.    name: 'media-text-media-right',
  3.    title: __( 'Media & Text' ),
  4.    isDefault: true,
  5.    attributes: {
  6.    mediaPosition: 'right',
  7.    },
  8. } );

isDefaultを使用する際の注意点

isDefault は、既存のバリエーションのないブロックを上書きする際に非常に効果的ですが、他のバリエーションが存在する場合には問題が発生することがあります。

同じブロックの別のバリエーションが isDefault を使用している場合、あなたのバリエーションが必ずしもデフォルトになるわけではありません。エディターは isDefault を持つ最初に登録されたバリエーションを尊重しますが、それはあなたのものではないかもしれません。

解決策は、isDefault であなたのバリエーションを登録する前に他のバリエーションを登録解除することです。この注意点は、常に一意の name を持つバリエーションを提供することを推奨することを強調しています。そうしないと、バリエーションを登録解除できなくなります。

isActiveの使用

isActive プロパティはオプションですが、推奨されます。このAPIはブロックエディターによって使用され、バリエーションのインスタンスがエディターで選択されたときに、どのバリエーションがアクティブであるかを確認し、正しいバリエーションのタイトル、アイコン、説明を表示します。

isActive が設定されていない場合、エディターは元のブロックのインスタンスとあなたのバリエーションを区別できず、元のブロック情報が表示されます。

プロパティは、文字列の配列（string[]）または関数のいずれかに設定できます。可能な限り文字列配列バージョンを使用することを推奨します。

string[] バージョンは、ブロックインスタンスの属性のうち、どれが指定されたバリエーションのものと比較されるべきかを宣言するために使用されます。各属性がチェックされ、すべてが一致すればバリエーションがアクティブになります。

たとえば、コアの埋め込みブロックでは、providerNameSlug 属性が埋め込みプロバイダー（例：‘youtube’ または ‘twitter’）を決定するために使用されます。バリエーションは次のように宣言できます： 

  1. const variations = [
  2.    {
  3.    name: 'twitter',
  4.    title: 'Twitter',
  5.    icon: embedTwitterIcon,
  6.    keywords: [ 'tweet', __( 'social' ) ],
  7.    description: __( 'Embed a tweet.' ),
  8.    patterns: [ /^https?:\/\/(www\.)?twitter\.com\/.+/i ],
  9.    attributes: { providerNameSlug: 'twitter', responsive: true },
  10.    },
  11.    {
  12.    name: 'youtube',
  13.    title: 'YouTube',
  14.    icon: embedYouTubeIcon,
  15.    keywords: [ __( 'music' ), __( 'video' ) ],
  16.    description: __( 'Embed a YouTube video.' ),
  17.    patterns: [
  18.    /^https?:\/\/((m|www)\.)?youtube\.com\/.+/i,
  19.    /^https?:\/\/youtu\.be\/.+/i,
  20.    ],
  21.    attributes: { providerNameSlug: 'youtube', responsive: true },
  22.    },
  23.    // ...
  24. ];

isActive プロパティは次のようになります： 

  1. isActive: [ 'providerNameSlug' ];

これにより、providerNameSlug のブロックインスタンス値が、バリエーションの宣言で宣言された値（上記のコードスニペットの値）と比較され、どの埋め込みバリエーションがアクティブかが決定されます。

ネストされたオブジェクトパスも、WordPress 6.6.0 以降サポートされています。たとえば、query オブジェクトを属性として持つブロックバリエーションを考えてみてください。そのオブジェクトの postType プロパティに基づいて、バリエーションがアクティブかどうかを判断することが可能です（他のすべてのプロパティは無視します）： 

  1. isActive: [ 'query.postType' ];

このプロパティの関数バージョンは、ブロックインスタンスの blockAttributes を最初の引数として、バリエーションのために宣言された variationAttributes を第二の引数として受け入れます。これらの引数は、比較して true または false を返すことによって、バリエーションがアクティブかどうかを判断するために使用できます（このブロックインスタンスに対してこのバリエーションが非アクティブであることを示します）。

埋め込みブロックの同じ例を使用すると、関数バージョンは次のようになります： 

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

isActiveマッチの特異性

注：WordPress 6.6.0 以降の改善された処理。

isActive チェックが特定のブロックインスタンスに一致する複数のバリエーションがあり、すべてが文字列配列である場合、特異性が最も高いバリエーションが選択されます。次の例を考えてみてください： 

  1. wp.blocks.registerBlockVariation( 'core/paragraph', {
  2.    name: 'paragraph-red',
  3.    title: 'Red Paragraph',
  4.    attributes: {
  5.    textColor: 'vivid-red',
  6.    },
  7.    isActive: [ 'textColor' ],
  8. } );
  10. wp.blocks.registerBlockVariation( 'core/paragraph', {
  11.    name: 'paragraph-red-grey',
  12.    title: 'Red/Grey Paragraph',
  13.    attributes: {
  14.    textColor: 'vivid-red',
  15.    backgroundColor: 'cyan-bluish-gray',
  16.    },
  17.    isActive: [ 'textColor', 'backgroundColor' ],
  18. } );

ブロックインスタンスが textColor: vivid-red と backgroundColor: cyan-bluish-gray 属性を持っている場合、両方のバリエーションの isActive 基準がそのブロックインスタンスに一致します。この場合、より 特異的 な一致がアクティブなバリエーションとして決定され、特異性は各 isActive 配列の長さとして計算されます。これにより、Red/Grey Paragraph がアクティブなバリエーションとして表示されます。

特異性は、isActive プロパティが関数である場合、一致するバリエーションに対して決定できません。この場合、最初に一致したバリエーションがアクティブなバリエーションとして決定されます。このため、isActive プロパティに対して string[] を使用することが一般的に推奨されます。