登録
ブロック登録 API リファレンス
注意: このページで説明した関数は、クライアントサイドの JavaScript でのみブロックを登録できます。しかし、サーバー上の PHP も含め、新しいブロックタイプを登録する推奨の方法は、メタデータファイル block.json です。メタデータファイルの完全な情報については、メタデータのドキュメントを参照してください。
WordPress ブロックエディターの「はじめてのブロックの作り方」を学習してください。このチュートリアルでは開発環境のセットアップ、ツール、新しい開発モデルの学習等、ブロックの作成を始めるために必要なすべてがカバーされます。
registerBlockType 関数
- Type:
Function
すべてのブロックの作成は、新しいブロックタイプ定義の登録から始まります。登録には 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' );
注意: UIで読みやすく、アクセスしやすいブロックタイトルにするには、長過ぎるタイトルは避けてください。
description (オプション)
- Type:
String
ブロックの簡単な説明。翻訳関数を使用して翻訳できます。「設定」サイドバーの「ブロック」タブで表示されます。
description: __( 'Block showing a Book card.' );
category
- Type:
String[ text | media | design | widgets | theme | embed ]
ブロックはユーザーの見やすさ、検索しやすさのためカテゴリーにグループ分けされます。
コアで提供されるカテゴリー一覧:
- text (テキスト)
- media (メディア)
- design (デザイン)
- widgets (ウィジェット)
- theme (テーマ)
- 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-hidden、role、focusable が追加されます。
オブジェクトもアイコンとして指定できますが、この場合にアイコンは 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[] - Since:
WordPress 5.9.0
ブロックタイプは、ブロックスタイルの宣言方法と同様に、ユーザーが選択可能なブロックバリエーションを定義できます。違いはビジュアルな見た目だけを変更するのではなく、このフィールドは、ブロックが挿入された際の初期カスタム属性とインナーブロックの適用方法を提供します。詳細については ブロックバリエーション API を参照してください。
supports (オプション)
- Type:
Object
supports にはエディター内で使用される機能を操作する、一連のオプションが含まれます。詳細については supports のドキュメント を参照してください。
transforms (オプション)
- Type:
Object
transform は、何をブロックに変換できるのか、またブロックは何に変換できるのかのルールを提供します。ブロックは、別のブロック、ショートコード、正規表現、ファイル、生の DOM ノードから変換できます。利用可能な個々の変換の詳細については ブロック変換 API を参照してください。
parent (オプション)
- Type:
Array
ブロックは、ネストしたコンテンツとして InnerBlocks を使用するブロックの中に挿入することができます。ブロックをネストしたブロックとしてのみ利用可能に制限することが有用な場合もあります。たとえば「Add to Cart (カートに追加)」ブロックは、「Product (商品)」ブロック内でのみ利用可能にすることができます。
parent を設定したブロックは、特定のブロック内にネストした場合のみ利用可能になります。
// ブロックは Columns ブロックにネストする場合のみ利用可能
parent: [ 'core/columns' ],
ancestor (オプション)
- Type:
Array - Since:
WordPress 6.0.0
ancestor プロパティを使用すると、指定されたブロックタイプの中で、祖先ブロックサブツリーの任意の位置でブロックを利用できます。例えば、「’Comment Content’ ブロックは、’Column’ ブロックが ‘Comment Template’ ブロック内のどこかにある場合に限り、’Column’ ブロック内に配置できる」等の制限が可能です。parent プロパティと比較すると ancestor を指定したブロックはサブツリーの任意の場所に配置できますが、parent を指定したブロックは直接の子としてのみ配置できます。
// このブロックは Columns ブロック内の任意のレベルで入れ子の場合のみ利用可能
ancestor: [ 'core/columns' ],
allowedBlocks (オプション)
- Type:
Array - Since:
WordPress 6.5.0
allowedBlocks プロパティを設定することで、ブロックの直接の子としてネストできるブロックタイプを制限できます。
// このブロックの直接の子としてネストされるブロックを、カラム (Columns) ブロックのみを許可する。
allowedBlocks: [ 'core/columns' ],
blockHooks (オプション)
- Type:
Object - Since:
WordPress 6.4.0
ブロックフックは指定されたブロックタイプのすべてのインスタンスの隣、「フックされた」ブロックによって指定された相対位置に、自動的にブロックを挿入する API です。つまり、選択によりブロックを、指定されたブロックタイプの前または後、または、最初の子または最後の子 (子ブロックのリストの先頭、または末尾) に挿入できます。フックされたブロックは、フロントエンドとエディターの両方に表示されます (ユーザーによるカスタマイズが可能です)。
キーはフックするブロックの名前 (string)、値はフックする位置 (string) です。指定可能な値は以下です。
before– ターゲットブロックの前に挿入after– ターゲットブロックの後に挿入firstChild– ターゲットのコンテナブロックの最初のインナーブロックの前に挿入lastChild– ターゲットのコンテナブロックの最後のインナーブロックの後に挿入
{
blockHooks: {
'core/verse': 'before',
'core/spacer': 'after',
'core/column': 'firstChild',
'core/group': 'lastChild',
}
}
重要な点のため強調しますが、ブロックフック機能は、静的な ブロックベースのテンプレート、テンプレートパーツ、パターンにのみ対応するように設計されています。このパターンに含まれるものは、テーマや、ブロックパターンディレクトリ、そして register_block_pattern 呼び出しから提供されたものです。
ブロックフックは、投稿コンテンツや、ユーザーが作成したパターン (同期パターンなど)、ユーザーが変更したテーマのテンプレートやテンプレートパーツでは機能しません。
ブロックコレクション
registerBlockCollection 関数
ブロックをコレクションに追加し、出自の同じすべてのブロックを一緒にグループ化できます。
registerBlockCollection は2つのパラメータを取ります。namespace と、title と icon を含む設定のオブジェクトです。
Namespace
- Type:
String
ブロック名で定義された namespace と合致する必要があります。プラグインやテーマの名前です。
Settings
Title
- Type:
String
コレクション内のすべてのブロックをリストするブロックインサーターセクションにタイトルを表示します。
Icon
- Type:
Object
(オプション) ブロックインサーターのタイトルと一緒に表示するアイコン
// ブロックコレクションの登録
registerBlockCollection( 'my-plugin', { title: 'My Plugin' } );
最終更新日: