バリエーション

ブロックは、ブロックバリエーション API を使用して、共通の機能を共有する自身の類似バージョンを作成できます。各ブロックバリエーションは、初期属性やインナーブロックの設定により他と区別されます。ブロックが挿入されると、これらの属性やインナーブロックが適用されます。

この API を理解する一番良い方法は、例として embed ブロックを考えることでしょう。埋め込みブロックの数多くの既存のバリエーション (WordPress、YouTube、など) は、編集、保存など同じ機能を共有しますが、使用の際に必要なプロバイダーを定義する providerNameSlug 属性値が異なります。

デフォルトではインサーター内に、通常のブロックタイプ項目に加えてすべてのバリエーションが表示されます。リストされた任意のバリエーションに isDefault フラグを設定すると、インサーター内の標準のブロックタイプを上書きします。

variations: [
    {
        name: 'wordpress',
        isDefault: true,
        title: __( 'WordPress' ),
        description: __( 'Code is poetry!' ),
        icon: WordPressIcon,
        attributes: { providerNameSlug: 'wordpress' },
    },
    {
        name: 'google',
        title: __( 'Google' ),
        icon: GoogleIcon,
        attributes: { providerNameSlug: 'google' },
    },
    {
        name: 'twitter',
        title: __( 'Twitter' ),
        icon: TwitterIcon,
        attributes: { providerNameSlug: 'twitter' },
        keywords: [ __('tweet') ],
    },
],

ブロックタイプのバリエーションを記述するオブジェクトには次のフィールドを指定できます。

  • name (type string) – 機械で識別可能な固有の名前
  • title (type string) – ユーザー向けのバリエーションのタイトル
  • description (オプション, type string) – 詳細なバリエーションの説明
  • category (オプション, type string) – カテゴリーの分類。検索インターフェース内で、ブロックタイプのカテゴリーごとの配置に使用される。
  • icon (オプション, type String | Object) – バリエーションの視覚化を助けるアイコン。ブロックタイプと同じ形でも良い。
  • isDefault (オプション, type boolean) – 現行のバリエーションがデフォルトかどうかを示すフラグ。デフォルトは false
  • attributes (オプション, type Object) – ブロック属性を上書きする値
  • innerBlocks (オプション, type Array[]) – ネストしたブロックの初期構成
  • example (オプション, type Object) – ブロックプレビューの例を提供する構造化データ。undefined を設定するとブロックタイプに表示するプレビューを無効化できる。
  • scope (オプション, type WPBlockVariationScope[]) – バリエーションを適用できるスコープのリスト。指定しない場合のデフォルトは block と inserter。利用可能なオプション:
    • inserter – ブロックバリエーションはインサーターに表示される。
    • block – 特定のブロックバリエーションをフィルタリングするためにブロックで使用される。Columns ブロックと Query Loop ブロックにこのバリエーションがあり、experimental BlockVariationPickerコンポーネントに渡される。このコンポーネントはバリエーションの表示やその中から1つを選択する機能を処理する、
    • transform – ブロックバリエーションはブロックバリエーション変換のコンポーネント内で表示される。
  • keywords (オプション, type string[]) – 翻訳可能な語句の配列。ユーザーがバリエーションを検索しやすくする。
  • isActive (オプション, type Function|string[]) – 関数、または、ブロック属性の配列。関数の場合、ブロックの属性とバリエーションの属性を取り、バリエーションが有効かどうかを決定する。ただしこの関数は、すべてのブロックの属性に基づいて動的に合致するものを探そうとはしません。これは多くの場合、意味のない属性があるためです。たとえば embed ブロックでは providerNameSlug 属性の値のみに注目します。また簡単に、どの属性を比較すべきか伝えるために string[] も使えます。すべてが合致するなら、各属性も合致し、バリエーションも有効です。

ブロックスタイルとブロックバリエーションの主な違いとして、ブロックスタイルはブロックに CSS クラスを適用するのみ、すなわち、代替のスタイルを適用するのみの点が異なります。初期属性やインナーブロックを適用したければ、ブロックバリエーションのテリトリーとなります。

またブロックバリエーションを定義する際、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
    },
],

ヒント: isActive プロパティの設定は、ブロック作成後にブロックバリエーションからの情報を使用する場合に有用です。たとえば、BlockCard や Breadcrumbs コンポーネントのように、この API は useBlockDisplayInformation ブック内で使用され、その場で適切な情報を取得し、表示します。

ブロックバリエーションはブロックの登録の際に、上で見たような variations キーと適切なバリエーションの配列を渡すことで宣言できます。また、ブロックの登録後に、block variation を登録、登録解除する方法もあります。

ブロックバリエーションを追加するには、wp.blocks.registerBlockVariation() を使用してください。

例:

wp.blocks.registerBlockVariation( 'core/embed', {
    name: 'custom',
    attributes: { providerNameSlug: 'custom' },
} );

ブロックバリエーションを削除するには、wp.blocks.unregisterBlockVariation() を使用してください。

例:

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

原文

最終更新日: