バリエーション
ブロックは、ブロックバリエーション 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
(typestring
) – 機械で識別可能な固有の名前title
(typestring
) – ユーザー向けのバリエーションのタイトルdescription
(オプション, typestring
) – 詳細なバリエーションの説明category
(オプション, typestring
) – カテゴリーの分類。検索インターフェース内で、ブロックタイプのカテゴリーごとの配置に使用される。icon
(オプション, typeString
|Object
) – バリエーションの視覚化を助けるアイコン。ブロックタイプと同じ形でも良い。isDefault
(オプション, typeboolean
) – 現行のバリエーションがデフォルトかどうかを示すフラグ。デフォルトはfalse
attributes
(オプション, typeObject
) – ブロック属性を上書きする値innerBlocks
(オプション, typeArray[]
) – ネストしたブロックの初期構成example
(オプション, typeObject
) – ブロックプレビューの例を提供する構造化データ。undefined
を設定するとブロックタイプに表示するプレビューを無効化できる。scope
(オプション, typeWPBlockVariationScope[]
) – バリエーションを適用できるスコープのリスト。指定しない場合のデフォルトはblock
とinserter
。利用可能なオプション:inserter
– ブロックバリエーションはインサーターに表示される。block
– 特定のブロックバリエーションをフィルタリングするためにブロックで使用される。Columns
ブロックとQuery Loop
ブロックにこのバリエーションがあり、experimental BlockVariationPickerコンポーネントに渡される。このコンポーネントはバリエーションの表示やその中から1つを選択する機能を処理する、transform
– ブロックバリエーションはブロックバリエーション変換のコンポーネント内で表示される。
keywords
(オプション, typestring[]
) – 翻訳可能な語句の配列。ユーザーがバリエーションを検索しやすくする。isActive
(オプション, typeFunction|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' );
最終更新日: