ブロックAPIリファレンス - 登録（Registration） - 《WordPress開発者リソース》日本語

registerBlockType
- Block Name
- Block configuration
Block collections
registerBlockCollection
- Settings
  - Title
  - Icon

registerBlockType

Type: Function

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

Block Name

Type: String

ブロックの名前は、ブロックを識別するユニークな文字列です。名前はnamespace/block-nameの形式で構成する必要があり、namespaceはプラグインまたはテーマの名前です。

// Registering my block with a unique name
registerBlockType( 'my-plugin/book', {} );

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

注: この名前は、コメント区切りとしてで使用されます。コアが提供するブロックは、シリアライズ時にnamespaceを含みません。

Block configuration

Type: Object [ { key: value } ]

ブロックを正常に登録するには、いくつかのプロパティを指定する必要があります。これらは、以下を含む設定オブジェクトを通じて定義されます:

title

Type: String

これは、ブロックの表示タイトルであり、私たちの翻訳関数を使用して翻訳できます。タイトルは、インサータやエディタの他の領域に表示されます。

// Our data object
title: __( 'Book' );

注: ブロックのタイトルをUIで読みやすく、アクセス可能に保つために、非常に長いタイトルは避けるようにしてください。

description (optional)

Type: String

これは、ブロックの短い説明であり、私たちの翻訳関数を使用して翻訳できます。これは、設定サイドバーのブロックタブに表示されます。

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

icon (optional)

Type: String | Object

アイコンプロパティは、ブロックを識別しやすくするために指定する必要があります。これらは、WordPressのDashiconsのいずれか、またはカスタムsvg要素です。

// Specifying a dashicon for the block
icon: 'book-alt',
// Specifying a custom svg for the block
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: {
   // Specifying a background color to appear with the icon e.g.: in the inserter.
   background: '#7e70af',
   // Specifying a color for the icon (optional: if not set, a readable color will be automatically defined)
   foreground: '#fff',
   // Specifying an icon for the block
   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 (optional)

Type: Array

時々、ブロックには、ユーザーが検索中にそれを発見するのを助けるエイリアスがあるかもしれません。たとえば、imageブロックはphotoによっても発見されることを望むかもしれません。これを行うには、用語の配列を提供します（翻訳可能です）。

// Make it easier to discover a block with keyword aliases.
// These can be localised so your keywords work across locales.
keywords: [ __( 'image' ), __( 'photo' ), __( 'pics' ) ],

styles (optional)

Type: Array

ブロックスタイルは、ブロックに代替スタイルを提供するために使用できます。これは、ブロックのラッパーにクラス名を追加することによって機能します。CSSを使用して、テーマ開発者は、選択された場合にブロックスタイルのクラス名をターゲットにできます。

// Register block styles.
styles: [
   // Mark style as default.
   {
   name: 'default',
   label: __( 'Rounded' ),
   isDefault: true
   },
   {
   name: 'outline',
   label: __( 'Outline' )
   },
   {
   name: 'squared',
   label: __( 'Squared' )
   },
],

プラグインとテーマも、既存のブロックのためにカスタムブロックスタイルを登録できます。

attributes (optional)

Type: Object

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

// Specifying my block attributes
attributes: {
   cover: {
   type: 'string',
   source: 'attribute',
   selector: 'img',
   attribute: 'src',
   },
   author: {
   type: 'string',
   source: 'html',
   selector: '.book-author',
   },
   pages: {
   type: 'number',
   },
},

参照: Attributes。

example (optional)

Type: Object

例は、ブロックのための構造化された例データを提供します。このデータは、ユーザーがブロックにマウスを乗せたときにインスペクターヘルプパネルに表示されるブロックのプレビューを構築するために使用されます。また、ブロックが選択されたときにスタイルパネルにも表示されます。

例オブジェクトで提供されるデータは、定義された属性と一致する必要があります。たとえば:

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

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


``````bash
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 (optional)

Type: Object[]
Since: WordPress 5.9.0

ブロックのスタイルが宣言できるのと同様に、ブロックタイプは、ユーザーが選択できるブロックのバリエーションを定義できます。違いは、視覚的な外観を変更するだけでなく、このフィールドは、ブロックが挿入されるときに初期のカスタム属性と内部ブロックを適用する方法を提供します。詳細については、Block Variations APIを参照してください。

supports (optional)

Type: Object

supportsには、エディタで使用される機能を制御するためのオプションのセットが含まれています。詳細については、supportsドキュメントを参照してください。

transforms (optional)

Type: Object

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

parent (optional)

Type: Array

ブロックは、InnerBlocksを使用してネストされたコンテンツとして挿入できます。時には、ブロックを制限して、ネストされたブロックとしてのみ利用可能にすることが有用です。たとえば、「カートに追加」ブロックを「製品」ブロック内でのみ利用可能にしたい場合があります。


``````bash
// Only allow this block when it is nested in a Columns block
parent: [ 'core/columns' ],
`

ancestor (optional)

Type: Array
Since: WordPress 6.0.0


``````bash
// Only allow this block when it is nested at any level in a Columns block.
ancestor: [ 'core/columns' ],
`

allowedBlocks (optional)

Type: Array
Since: WordPress 6.5.0


``````bash
// Only allow the Columns block to be nested as direct child of this block
allowedBlocks: [ 'core/columns' ],
`

blockHooks (optional)

Type: Object
Since: WordPress 6.4.0

Block Hooksは、ブロックが指定されたブロックタイプのすべてのインスタンスの隣に自動的に挿入されることを可能にするAPIです。相対的な位置も「フックされた」ブロックによって指定されます。つまり、ブロックは、指定されたブロックタイプの前または後、またはその最初または最後の子として挿入されることを選択できます（すなわち、子ブロックのリストにそれぞれ追加または挿入されます）。フックされたブロックは、フロントエンドとエディタの両方に表示されます（ユーザーによるカスタマイズを可能にするため）。

キーはフックするブロックの名前（string）であり、値はフックする位置（string）です。許可されるターゲット値は次のとおりです:

before – ターゲットブロックの前に注入します。
after – ターゲットブロックの後に注入します。
firstChild – ターゲットコンテナブロックの最初の内部ブロックの前に注入します。
lastChild – ターゲットコンテナブロックの最後の内部ブロックの後に注入します。

{
   blockHooks: {
   'core/verse': 'before',
   'core/spacer': 'after',
   'core/column': 'firstChild',
   'core/group': 'lastChild',
   }
}

Block Hooks機能は、静的ブロックベースのテンプレート、テンプレートパーツ、およびパターンでのみ機能するように設計されていることを強調することが重要です。パターンについては、テーマが提供するもの、Block Pattern Directoryからのもの、またはregister_block_patternへの呼び出しからのものが含まれます。

Block Hooksは、ユーザーによって作成された投稿コンテンツやパターン、同期パターン、またはユーザーによって変更されたテーマテンプレートやテンプレートパーツでは機能しません。

Block collections

registerBlockCollection

Type: Function

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

 <a name="namespace"></a>
### Namespace
- **Type:** `````String

これは、ブロック名で宣言されたnamespaceと一致する必要があります。プラグインまたはテーマの名前です。

Settings

Title

Type: String

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

Icon

Type: Object

（オプション）ブロックインサータ内のタイトルの横に表示するアイコン。

// Registering a block collection
registerBlockCollection( 'my-plugin', { title: 'My Plugin' } );

登録（Registration）