ブロックの登録

registerBlockType 関数

すべてのブロックの作成は、新しいブロックタイプ定義の登録から始まります。登録には wp-blocks パッケージ の registerBlockType 関数を使用します。関数はブロック名とブロック構成オブジェクトの2つの引数を取ります。

ブロック名

  • Type: String

ブロック名はブロックを一意に識別する固有の文字列です。ブロック名は「namespace/block-name」の形式を取り、namespace はプラグインやテーマの名前になります。

// ブロックを一意の名前で登録
registerBlockType( 'my-plugin/book', {} );

注意: ブロック名には英小文字、数字、ダッシュのみを使うことができます。またブロック名は文字で始まる必要があります。

注意: ブロック名はコメントデリミッタとして <!-- wp:my-plugin/book --> のように使用されます。コアで提供されるブロックはシリアライズの際に名前空間が削除されます。

ブロック構成

  • Type: Object [ { key: value } ]

登録する際、ブロックにプロパティを指定できます。プロパティは構成オブジェクトで定義します。

プロパティの一覧は以下のとおりです。

title

  • Type: String

ブロックの表示タイトル。翻訳関数を使用して翻訳できます。ブロックインサーターはこの名前を表示します。

// データオブジェクト
title: __( 'Book' );

description (オプション)

  • Type: String

ブロックの簡単な説明。翻訳関数を使用して翻訳できます。「設定」サイドバーの「ブロック」タブで表示されます。

description: __( 'Block showing a Book card.' );

category

  • Type: String [ common | formatting | layout | widgets | embed ]

ブロックはユーザーの見やすさ、検索しやすさのためカテゴリーにグループ分けされます。

コアで提供されるカテゴリー一覧:

  • common (一般ブロック)
  • formatting (フォーマット)
  • layout (レイアウト要素
  • widgets (ウィジェット)
  • embed (埋め込み)
// 'widgets' ウィジェットカテゴリーに割り当て
category: 'widgets',

プラグインとテーマは カスタムブロックカテゴリー を登録することもできます。

icon (オプション)

  • Type: String | Object

ブロックを見つけやすくするには icon プロパティを指定します。任意の WordPress Dashicon またはカスタム svg 要素を指定できます。

// ブロックに dashicon を指定
icon: 'book-alt',

// ブロックにカスタム svg を指定
icon: <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>,

注意: カスタム SVG アイコンは自動的に wp.primitives.SVG コンポーネント でラップされ、アクセシビリティ属性 aria-hiddenrolefocusable が追加されます。

オブジェクトもアイコンとして指定できますが、この場合にアイコンは src プロパティに含めてください。

src 以外にオブジェクトは背景色と前景色を設定できます。ここで指定した色はインサーターの中など適切な場面でアイコンの背景色や前景色として使用されます。

icon: {
    // インサーターの中などでアイコンの背景色として使用される色の指定
    background: '#7e70af',
    // アイコンの色の指定。オプションで、指定しなければ視認性の高い色が自動で定義される
    foreground: '#fff',
    // ブロックのアイコンの指定
    src: <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>,
} ,

keywords (オプション)

  • Type: Array

ブロックには、ユーザーが検索する際に見つけやすいよう別名を設定できます。たとえば image ブロックは、photo でも見つけられれるようになります。検索後の配列を指定してください。検索後は翻訳可能です。

// キーワードで別名をつけてブロックを発見しやすくする
// キーワードは翻訳可能。翻訳すればロケールに関わらず動作する
keywords: [ __( 'image' ), __( 'photo' ), __( 'pics' ) ],

styles (オプション)

  • Type: Array

ブロックスタイルを使用してブロックに代替のスタイルを与えられます。ブロックスタイルはブロックのラッパーにクラス名を追加することで動作します。テーマ開発者は該当のクラス名をターゲットに CSS を使用して、選択された際のスタイルのバリエーションを指定できます。

// ブロックスタイルの登録
styles: [
    // デフォルトのスタイルとしてマーク
    {
        name: 'default',
        label: __( 'Rounded' ),
        isDefault: true
    },
    {
        name: 'outline',
        label: __( 'Outline' )
    },
    {
        name: 'squared',
        label: __( 'Squared' )
    },
],

プラグインやテーマは既存のブロックに対して カスタムブロックスタイル を登録することもできます。

attributes (オプション)

  • Type: Object

属性はブロックに必要な構造化データを提供します。シリアライズの際には異なる形式で存在できますが共通インターフェイスの下で一緒に宣言されます。

// ブロックの属性の指定
attributes: {
    cover: {
        type: 'string',
        source: 'attribute',
        selector: 'img',
        attribute: 'src',
    },
    author: {
        type: 'string',
        source: 'html',
        selector: '.book-author',
    },
    pages: {
        type: 'number',
    },
},

example (オプション)

  • Type: Object

example はブロックの構造化したサンプルデータを提供します。このデータを使用してブロックのプレビューを作成します。ユーザーがインスペクターヘルプパネルでマウスオーバーすると、プレビューが表示されます。

example オブジェクトに提供したデータは定義された属性と合致する必要があります。たとえば

example: {
    attributes: {
        cover: 'https://example.com/image.jpg',
        author: 'William Shakespeare',
        pages: 500
    },
},

example が定義されていない場合、プレビューは表示されません。属性が定義されていない場合にもプレビューを表示するには、空の example オブジェクト example: {} を設定します。

また innerBlocks を使用したインナーブロックでブロックプレビューを拡張することもできます。

example: {
    attributes: {
        cover: 'https://example.com/image.jpg',
    },
    innerBlocks: [
        {
            name: 'core/paragraph',
            attributes: {
                /* translators: example text. */
                content: __(
                    'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent et eros eu felis.'
                ),
            },
        },
    ],
},

また viewportWidth を使用してプレビューコンテナの幅をピクセル単位で定義することもできます。

example: {
    attributes: {
        cover: 'https://example.com/image.jpg',
    },
    viewportWidth: 800
},

variations (オプション)

  • Type: Object[]

ブロックスタイルバリエーションの定義方法と同様に、ブロックタイプはユーザーが選択可能なブロックバリエーションを定義できます。違いとしてはこのフィールドはビジュアルな見た目を変更するだけでなく、ブロックが挿入された際の初期カスタム属性とインナーブロックの適用方法を提供します。

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

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

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

  • name (type string) – 機械で識別可能な固有の名前
  • title (type string) – ユーザー向けのバリエーションのタイトル
  • description (オプション, type string) – 詳細なバリエーションの説明
  • icon (オプション, type String | Object) – バリエーションの視覚化を助けるアイコン。ブロックタイプと同じ形でも良い。
  • isDefault (オプション, type boolean) – 現行のバリエーションがデフォルトかどうかを示すフラグ。デフォルトは false
  • attributes (オプション, type Object) – ブロック属性を上書きする値
  • innerBlocks (オプション, type Array[]) – ネストしたブロックの初期構成
  • example (オプション, type Object) – ブロックプレビューの例を提供する構造化データ。undefined を設定するとブロックタイプに表示するプレビューを無効化できる。
  • scope (オプション, type String[]) – バリエーションを適用できるスコープのリスト。指定しない場合はすべての有効なスコープを仮定する。有効なオプション: blockinserter.
  • keywords (オプション, type string[]) – 翻訳可能な語句の配列。ユーザーがバリエーションを検索しやすくする。

またブロックバリーションを定義する際、className 属性を使用して、デフォルトのブロックスタイルバリエーションを上書きすることもきます。

variations: [
    {
        name: 'blue',
        title: __( 'Blue Quote' ),
        isDefault: true,
        attributes: { className: 'is-style-blue-quote' },
        icon: 'format-quote',
    },
],

supports (オプション)

  • Type: Object

supports にはエディター内で使用される機能を操作する、一連のオプションが含まれます。詳細については supports のドキュメント を参照してください。

transforms (オプション)

  • Type: Object

transform は、何をブロックに変換できるのか、またブロックは何に変換できるのかのルールを提供します。ブロックは、別のブロック、ショートコード、正規表現、ファイル、生の DOM ノードから変換できます。利用可能な個々の変換の詳細については ブロック変換 API を参照してください。

parent (オプション)

  • Type: Array

ブロックは、ネストしたコンテンツとして InnerBlocks を使用するブロックの中に挿入することができます。ブロックをネストしたブロックとしてのみ利用可能に制限することが有用な場合もあります。たとえば「Add to Cart (カートに追加)」ブロックは、「Product (商品)」ブロック内でのみ利用可能にすることができます。

parent を設定したブロックは、特定のブロック内にネストした場合のみ利用可能になります。

// ブロックは Columns ブロックにネストする場合のみ利用可能
parent: [ 'core/columns' ],

ブロックコレクション

registerBlockCollection 関数

ブロックをコレクションに追加し、出自の同じすべてのブロックを一緒にグループ化できます。

registerBlockCollection は2つのパラメータを取ります。namespace と、title と icon を含む設定のオブジェクトです。

Namespace

  • Type: String

ブロック名で定義された namespace と合致する必要があります。プラグインやテーマの名前です。

Settings

Title

  • Type: String

コレクション内のすべてのブロックをリストするブロックインサーターセクションにタイトルを表示します。

Icon

  • Type: Object

(オプション) ブロックインサーターのタイトルと一緒に表示するアイコン

// ブロックコレクションの登録
registerBlockCollection( 'my-plugin', { title: 'My Plugin' } );

原文

最終更新日: