ブロックの登録

registerBlockType 関数

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

Block Name

  • Type: String

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

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

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

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

Block Configuration

  • 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: {} を設定します。

It’s also possible to extend the block preview with inner blocks via innerBlocks. For example:

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.'
            ),
        },
    },
},

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' },
    },
],

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

  • 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.

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

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

transforms (オプション)

  • Type: Object

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

parent (オプション)

  • Type: Array

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

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

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

supports (オプション)

anchor や className などいくつかの ブロックサポート は、save から返される要素に追加の props を加えて属性を適用します。 div などのデフォルトの HTML タグ要素であればこれは自動的に動作します。しかし save の戻り値がカスタムコンポーネント要素の場合、属性が永続化されるようカスタムコンポーネントがこれらの props を処理する必要があります。

  • Type: Object

オプションのブロック拡張サポート機能。次のオプションがサポートされます。

  • align (デフォルト false): このプロパティはブロックの配置を変更するブロックコントロールを追加する。重要: ダイナミックブロックとは、まだ、動作しない。
// ブロックの配置のサポートを追加 (left (左寄せ), center (中央寄せ), right (右寄せ), wide (幅広), full (全幅)).
align: true,
// どの配置オプションを表示するかを選択
align: [ 'left', 'right', 'full' ],

align サポートを使用するとブロック属性定義が拡張され、string タイプの align 属性が含まれます。 デフォルトではブロックに配置は割り当てられません。 ブロックにデフォルトの配置を適用するには、デフォルト値と共に align 属性を指定します。たとえば

attributes: {
    ...
    align: {
        type: 'string',
        default: 'right'
    },
    ...
}
  • alignWide (デフォルト true): このプロパティを使用するとテーマの 幅広揃え を有効化できます。単一ブロックに対してこの機能を無効化するにはこのフラグに false を設定してください。
// 幅広揃えサポートを除去
alignWide: false,
  • defaultStylePicker (デフォルト true): スタイルピッカーの表示の際、ユーザーがブロックタイプのデフォルトスタイルを選択できるようドロップダウンが表示されます。ドロップダウンを表示したくない場合にはこのプロパティを false に設定してください。
// デフォルトのスタイルピッカーを除去
defaultStylePicker: false,
  • anchor (デフォルト false): アンカーを使用するとページ上の特定のブロックに直接リンクできます。このプロパティはブロックの ID を定義するフィールドとダイレクトリンクをコピーするボタンをを追加します。
// アンカーリンクサポートを追加
anchor: true,
  • customClassName (デフォルト true): このプロパティはブロックのラッパーのカスタム classsName を定義するフィールドを追加します。
// カスタム className サポートを除去
customClassName: false,
  • className (デフォルト true): デフォルトでは保存したマークアップの root 要素にクラス .wp-block-your-block-name が追加されます。この結果、テーマやプラグインがブロックのスタイリングにあたって利用可能な一貫した機構が実現します。何らかの理由によりこのクラスをマークアップに負荷したくない場合、この機能を無効化できます。
// className 生成サポートを除去
className: false,
  • html (デフォルト true): デフォルトではブロックのマークアップは個別に編集できます。この動きを止めるには html に false を設定してください。
// HTML モードサポートを除去
html: false,
  • inserter (デフォルト true): デフォルトではすべてのブロックはインサーターに表示されます。ブロックをインサーターには表示せず、プログラム的にのみ挿入可能にするには inserter に false を設定してください。
// このブロックをインサーターに表示しない
inserter: false,
  • multiple (デフォルト true): 非 multiple ブロックは各投稿に1回だけ挿入できます。たとえば組み込みの「続きを読む」ブロックは、編集中の投稿にすでに存在する場合は挿入できません。非 multiple ブロックのアイコンクリックできないよう自動的にグレイアウトされ、複数インスタンスの作成を回避します。
// ブロックは投稿ごとに1度だけ使用できる
multiple: false,
  • reusable (デフォルト true): ブロックを再利用可能なブロックに変換する機能を無効化したい場合があります。デフォルトではすべてのブロックは再利用可能ブロックに変換できます。reusable サポートを false に設定すると、再利用可能ブロックするに変換するオプションが表示されません。
// 再利用可能ブロックへの変換を許可しない
reusable: false,

ブロックコレクション

registerBlockCollection 関数

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

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

Namespace

  • Type: String

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

Settings

Title

  • Type: String

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

Icon

  • Type: Object

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

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

最終更新日: