block.json のメタデータ

WordPress 5.8のリリースから、PHP (サーバーサイド) と JavaScript (クライアントサイド) の両方でブロックタイプを登録する正規の方法として、block.json メタデータファイルの使用が推奨されています。以下は、通知ブロックを作成するプラグインのメタデータを定義する block.json ファイルの例です。

例:

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "my-plugin/notice",
	"title": "Notice",
	"category": "text",
	"parent": [ "core/group" ],
	"icon": "star",
	"description": "Shows warning, error or success notices...",
	"keywords": [ "alert", "message" ],
	"version": "1.0.3",
	"textdomain": "my-plugin",
	"attributes": {
		"message": {
			"type": "string",
			"source": "html",
			"selector": ".message"
		}
	},
	"providesContext": {
		"my-plugin/message": "message"
	},
	"usesContext": [ "groupId" ],
	"selectors": {
		"root": ".wp-block-my-plugin-notice"
	},
	"supports": {
		"align": true
	},
	"styles": [
		{ "name": "default", "label": "Default", "isDefault": true },
		{ "name": "other", "label": "Other" }
	],
	"example": {
		"attributes": {
			"message": "This is a notice!"
		}
	},
	"variations": [
		{
			"name": "example",
			"title": "Example",
			"attributes": {
				"message": "This is an example!"
			}
		}
	],
	"editorScript": "file:./index.js",
	"script": "file:./script.js",
	"viewScript": [ "file:./view.js", "example-shared-view-script" ],
	"editorStyle": "file:./index.css",
	"style": [ "file:./style.css", "example-shared-style" ],
	"viewStyle": [ "file:./view.css", "example-view-style" ],
	"render": "file:./render.php"
}

メタデータファイルを使用する利点

ブロック定義は、JSON として格納されたブロックタイプを処理する際に、JavaScript や PHP などの言語間でのコードの共有を可能にします。さらに、メタデータファイル block.json を使用したブロックの登録には、以下のような複数のメリットがあります。

まずパフォーマンスの観点では、テーマが遅延ロードアセットをサポートする場合、block.json で登録されたブロックは、標準でアセットのエンキューが最適化されます。style や script プロパティにリストされたフロントエンドの CSS や JavaScript アセットは、ブロックがページ上に存在するときにのみエンキューされ、結果的にページサイズが小さくなります。

さらに、ブロックタイプ REST API エンドポイントでは、サーバー上で登録されたブロックしか一覧できないため、サーバーサイドでブロックを登録することが推奨されます。block.jsonファイルを使用すると、この登録が簡単になります。

WordPress プラグインディレクトリは、block.json ファイルを検出し、プラグインに含まれるブロックをハイライトし、そのメタデータを抽出できます。ブロックディレクトリに自分のブロックを登録する場合は、ブロックディレクトリが認識できるよう、プラグインに含まれるすべてのブロックに block.json ファイルを含めてください。

定義されたスキーマ定義ファイルを使用することで、開発効率が向上します。これに対応するエディタでは、ツールチップやオートコンプリート、スキーマの検証などの支援機能を提供できます。スキーマを使用するには、block.jsonの先頭に以下を追加します。

"$schema": "https://schemas.wp.org/trunk/block.json"

メタデータを使用してブロックを登録する方法については、ブロックの登録を確認してください。

ブロック API

このセクションでは、block.json ファイルに追加可能な、ブロックタイプの振る舞いとメタデータを定義するすべてのプロパティを紹介します。

API version

• 型: number
• オプション
• ローカライズ: 不可
• プロパティ: apiVersion
• デフォルト: 1

{ "apiVersion": 3 }

ブロックが使用する Block API のバージョン。最新のバージョンは 3 で、WordPress 6.3 で導入されました。

詳細については API バージョンのドキュメント を参照してください。

Name

• 型: string
• 必須
• ローカライズ: 不可
• プロパティ: name

{ "name": "core/heading" }

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

注意: ブロック名には、英数小文字、ダッシュ (-)、プラグイン固有の名前空間プレフィックスを表す最大1つのスラッシュ (/) のみを含められます。文字で始める必要があります。

注意: この名前はまた、コメントデリミッタとしても <!-- wp:my-plugin/book --> のように使用されます。なお、core 名前空間のブロックタイプは、シリアライズされる際に名前空間を含みません。

Title

• 型: string
• 必須
• ローカライズ: 可能
• プロパティ: title

{ "title": "Heading" }

ブロックの表示タイトルです。翻訳関数で翻訳できます。ブロックインサーターやエディターの他の領域は、このタイトルを表示します。

注意: UIで読みやすく、アクセスしやすいブロックタイトルにするには、長過ぎるタイトルは避けてください。

Category

• 型: string
• オプション
• ローカライズ: 不可
• プロパティ: category

{ "category": "text" }

ブロックは、ユーザーの視認性と検索のしやすさのため、カテゴリーにグループ分けできます。

コアの提供するカテゴリーは以下です。

• text
• media
• design
• widgets
• theme
• embed

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

実装は、未知のカテゴリーを予想し、合理的なフォールバック (例: text カテゴリー) を提供する必要があります。

Parent

• 型: string[]
• オプション
• ローカライズ: 不可
• プロパティ: parent

{ "parent": [ "my-block/product" ] }

parent を設定すると、ブロックは、指定したブロック内にネストされた場合のみ利用可能になります。たとえば、「カートに追加」ブロックを、「商品」ブロック内でのみ利用可能にすることができます。

Ancestor

• 型: string[]
• オプション
• ローカライズ: 不可
• プロパティ: ancestor
• Since: WordPress 6.0.0

{ "ancestor": [ "my-block/product" ] }

ancestor プロパティは、指定されたブロックタイプの中で、祖先ブロックサブツリーの任意の位置において、ブロックを利用可能にします。例えば、Column ブロックが Comment Template ブロック内のどこかにいる限り、Comment Content ブロックを Column ブロックの中に配置できます。parent プロパティと比較すると、 ancestor を指定したブロックはサブツリーのどこにでも配置できますが、 parent を指定したブロックは直接の子である必要があります。

Allowed Blocks

• 型: string[]
• オプション
• ローカライズ: 不可
• プロパティ: allowedBlocks
• Since: WordPress 6.5.0

{ "allowedBlocks": [ "my-block/product" ] }

allowedBlocks は、あるブロックの直接の子にできるブロックタイプを指定します。例えばリストブロックは、リスト項目ブロックのみを子として許可します。

Icon

• 型: string
• オプション
• ローカライズ: 不可
• プロパティ: icon

{ "icon": "smile" }

ブロックを識別しやすくするために icon プロパティを指定してください。任意の WordPress’ Dashicons を指定できます。またスラッグは 非 js コンテキストでのフォールバックとなります。

注意: このプロパティはまた、クライアントサイドで、SVG 要素のソースで上書きすることもできます。加えて、このプロパティは背景色や前景色を含むオブジェクトとして、 JavaScript で定義できます。この色は、たとえばインサーター内で表示される場合にアイコンと一緒に使用されます。カスタム SVG アイコンは自動で wp.primitives.SVG コンポーネントにラップされ、アクセシビリティ属性 (aria-hidden、role、focusable) が追加されます。

Description

• 型: string
• オプション
• ローカライズ: 可能
• プロパティ: description

{
	"description": "Introduce new sections and organize content to help visitors"
}

ブロックの簡潔な説明です。翻訳関数で翻訳できます。ブロックインスペクターで表示されます。

Keywords

• 型: string[]
• オプション
• ローカライズ: 可能
• プロパティ: keywords
• デフォルト: []

{ "keywords": [ "keyword1", "keyword2" ] }

ブロックは、検索性の向上のため別名を持つことができます。たとえば、画像ブロックを「写真」でも検索できるようになります。語句は何個でも配列内に指定でき、翻訳の対象です。

Version

• 型: string
• オプション
• ローカライズ: 不可
• プロパティ: version
• Since: WordPress 5.8.0

{ "version": "1.0.3" }

ブロックの現在のバージョン番号。例: 1.0、1.0.3。プラグインのバージョン管理と同様です。このフィールドは、ブロックアセットでキャッシュの無効化の制御に使用される場合があり、ブロック作者がこれを省略すると、代わりにインストールされたWordPressのバージョンが使用されます。

Text Domain

• 型: string
• オプション
• ローカライズ: 不可
• プロパティ: textdomain
• Since: WordPress 5.7.0

{ "textdomain": "my-plugin" }

プラグインブロックの gettext テキストドメイン。詳細については「プラグインの国際化」の「テキストドメイン」セクションを参照してください。

Attributes

• 型: object
• オプション
• ローカライズ: 不可
• プロパティ: attributes
• デフォルト: {}

{
	"attributes": {
		"cover": {
			"type": "string",
			"source": "attribute",
			"selector": "img",
			"attribute": "src"
		},
		"author": {
			"type": "string",
			"source": "html",
			"selector": ".book-author"
		}
	}
}

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

詳細については、属性のドキュメント を参照してください。

Provides Context

• 型: object
• オプション
• ローカライズ: 不可
• プロパティ: providesContext
• デフォルト: {}

このタイプのブロックの子孫ブロックによる、利用可能なアクセスのために提供されるコンテキスト。形式は、コンテキスト名をブロック自身の属性とマップするオブジェクト。

詳細については ブロックコンテキストのドキュメント を参照してください。

{
	"providesContext": {
		"my-plugin/recordId": "recordId"
	}
}

Context

• 型: string[]
• オプション
• ローカライズ: 不可
• プロパティ: usesContext
• デフォルト: []

先祖のプロバイダから継承するコンテキスト値の名前の配列

詳細については ブロックコンテキストのドキュメント を参照してください。

{
	"usesContext": [ "message" ]
}

Selectors

• 型: object
• オプション
• ローカライズ: 不可
• プロパティ: selectors
• デフォルト: {}
• Since: WordPress 6.3.0

theme.json (グローバルスタイル) スタイルシートのブロックスタイルを生成する際に使用される、root、フィーチャー、サブフィーチャーをキーとする任意のカスタム CSS セレクタ。 カスタムセレクタを提供することで、どのブロック要素にどのスタイルを適用するかを細かく制御できます。例えば、typoraphy スタイルは内部の見出しだけに適用し、color は外部のブロックラッパー全体に適用するなど。

詳細についてはセレクタのドキュメントを参照してください。

{
	"selectors": {
		"root": ".my-custom-block-selector",
		"color": {
			"text": ".my-custom-block-selector p"
		},
		"typography": {
			"root": ".my-custom-block-selector > h2",
			"text-decoration": ".my-custom-block-selector > h2 span"
		}
	}
}

Supports

• 型: object
• オプション
• ローカライズ: 不可
• プロパティ: supports
• デフォルト: {}

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

Block Styles

• 型: array
• オプション
• ローカライズ: 可能 (label のみ)
• プロパティ: styles
• デフォルト: []

{
	"styles": [
		{ "name": "default", "label": "Default", "isDefault": true },
		{ "name": "other", "label": "Other" }
	]
}

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

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

Example

• 型: object
• オプション
• ローカライズ: 不可
• プロパティ: example

{
	"example": {
		"attributes": {
			"message": "This is a notice!"
		}
	}
}

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

詳細については ドキュメントの「example (オプション)」セクション を参照してください。

Variations

• 型: object[]
• 型: object[]|WPDefinedPath (詳細)
• オプション
• ローカライズ: 可 (title, description, keywords それぞれのバリエーションのみ)
• プロパティ: variations
• Since: WordPress 5.9.0

{
	"variations": [
		{
			"name": "example",
			"title": "Example",
			"attributes": {
				"level": 2,
				"message": "This is an example!"
			},
			"scope": [ "block" ],
			"isActive": [ "level" ]
		}
	]
}

ブロックバリエーションは、あるブロックに類似のバージョンを持たせられる API ですが、これらのバージョンはすべて、共通の機能を共有します。各ブロックバリエーションは、いくつかの初期属性やインナーブロックの設定により、他のブロックと区別されます。ブロックを挿入すると、これらの属性やインナーブロックが適用されます。

注: JavaScriptでは、isActiveプロパティに関数を、icon に React 要素を指定できます。block.json ファイルでは、どちらも文字列のみをサポートします。

Version 6.7からは block.json 内で PHP ファイルを指定して、サーバー側でブロックバリエーションのリストを生成できるようになりました。

{ "variations": "file:./variations.php" }

この PHP ファイルはブロックバリエーションを含む配列を return することを期待されています。PHP ファイルから返るバリエーション内の文字列は、自動的にローカライズされません。代わりにいつもの __() 関数を使用してください。

例:

<?php
// Generate variations for a Social Icon kind of block.

return array(
	array(
		'isDefault'  => true,
		'name'       => 'wordpress',
		'title'      => 'WordPress',
		'icon'       => 'wordpress',
		'attributes' => array(
			'service' => 'wordpress',
		),
		'isActive'   => array( 'service' )
	),
	array(
		'name'       => 'mail',
		'title'      => __( 'Mail' ),
		'keywords'   => array(
			__( 'email' ),
			__( 'e-mail' )
		),
		'icon'       => 'mail',
		'attributes' => array(
			'service' => 'mail',
		),
		'isActive'   => array( 'mail' )
	),
);

詳細はドキュメントのバリエーション を参照してください。

Block Hooks

• 型: object
• オプション
• プロパティ: blockHooks
• Since: WordPress 6.4.0

{
	"blockHooks": {
		"my-plugin/banner": "after"
	}
}

ブロックフックは指定されたブロックタイプのすべてのインスタンスの隣、「フックされた」ブロックによって指定された相対位置に、自動的にブロックを挿入する API です。つまり、選択によりブロックを、指定されたブロックタイプの前または後、または、最初の子または最後の子 (子ブロックのリストの先頭、または末尾) に挿入できます。フックされたブロックは、フロントエンドとエディターの両方に表示されます (ユーザーによるカスタマイズが可能です)。

キーはフックするブロックの名前 (string)、値はフックする位置 (string) です。利用可能な設定については、ブロックフックのドキュメント を参照してください。

Editor script

• 型: WPDefinedAsset|WPDefinedAsset[] (詳細)
• オプション
• ローカライズ: 不可
• プロパティ: editorScript

{ "editorScript": "file:./index.js" }

ブロックタイプのエディタースクリプト定義。エディターのコンテキスト内でのみエンキューされます。

渡せるものは、wp_register_script 関数で登録されたスクリプトハンドル、block.json ファイルからの JavaScript ファイルへの相対パス、または2つを混ぜ合わせたリストです (詳細)。

注意: WordPress 6.1.0 からは、エディタースクリプトの配列を渡すオプションもあります。

Script

• 型: WPDefinedAsset|WPDefinedAsset[] (詳細)
• オプション
• ローカライズ: 不可
• プロパティ: script

{ "script": "file:./script.js" }

ブロックタイプフロントエンド、および、エディタースクリプト定義。エディター内、および、サイトのフロントエンドでコンテンツが表示される際の両方でエンキューされます。

渡せるものは、wp_register_script 関数で登録されたスクリプトハンドル、block.json ファイルからの JavaScript ファイルへの相対パス、または2つを混ぜ合わせたリストです (詳細)。

注意: スクリプトの配列を渡すオプションもあります。 WordPress 6.1.0 以降。

View script

• 型: WPDefinedAsset|WPDefinedAsset[] (詳細)
• オプション
• ローカライズ: 不可
• プロパティ: viewScript
• Since: WordPress 5.9.0

{ "viewScript": [ "file:./view.js", "example-shared-view-script" ] }

ブロックタイプフロントエンド定義。サイトのフロントでコンテンツを表示するときのみ、エンキューされます。

渡せるものは、wp_register_script 関数で登録されたスクリプトハンドル、block.json ファイルからの JavaScript ファイルへの相対パス、または2つを混ぜ合わせたリストです (詳細)。

注意: ビュースクリプトの配列を渡すオプションもあります。 WordPress 6.1.0 以降。

View script module

• 型: WPDefinedAsset|WPDefinedAsset[] (詳細)
• オプション
• ローカライズ: 不可
• プロパティ: viewScriptModule
• Since: WordPress 6.5.0

{ "viewScriptModule": [ "file:./view.js", "example-shared-script-module-id" ] }

ブロックタイプのフロントエンドスクリプトモジュール定義。サイトのフロントでコンテンツを表示するときにのみエンキューされます。

渡せるものは、wp_register_script_module 関数で登録したスクリプトモジュール ID 、block.jsonファイルからの相対パスによる JavaScript モジュール、またはその両方を合わせたリストです (詳細)。

現時点では、WordPress スクリプトと WordPress スクリプトモジュールに互換性はありません。もしフロントエンドのビューアセットが WordPress スクリプトに依存しているなら、viewScript を使用してください。もし WordPress のスクリプトモジュール (現時点では Inteeractivity API) に依存しているなら、viewScriptModule を使用してください。スクリプトモジュールでより多くの機能 が徐々に利用可能になる予定です。

注意: WordPress 6.5.0 以降で利用可能。

Editor style

• 型: WPDefinedAsset|WPDefinedAsset[] (詳細)
• オプション
• ローカライズ: 不可
• プロパティ: editorStyle

{ "editorStyle": "file:./index.css" }

ブロックタイプのエディタースタイル定義。エディターのコンテキスト内でのみエンキューされます。

渡せるものは、wp_register_script 関数で登録したスクリプトハンドル、block.json ファイルからの相対パスによる JavaScript ファイル、またはその両方を合わせたリストです (詳細)。

注意: エディタースクリプトの配列を渡すオプションもあります。 WordPress 5.9.0 以降。

Style

• 型: WPDefinedAsset|WPDefinedAsset[] (詳細)
• オプション
• ローカライズ: 不可
• プロパティ: style

{ "style": [ "file:./style.css", "example-shared-style" ] }

ブロックタイプフロントエンド、およびエディタースタイル定義。エディター内、および、サイトのフロントエンドでコンテンツが表示される際の両方でエンキューされます。

渡せるものは、wp_register_script 関数で登録されたスクリプトハンドル、block.json ファイルからの JavaScript ファイルへの相対パス、または2つを混ぜ合わせたリストです (詳細)。

注意: スタイルの配列を渡すオプションもあります。 WordPress 5.9.0 以降。

View Style

• 型: WPDefinedAsset|WPDefinedAsset[] (詳細)
• オプション
• ローカライズ: 不可
• プロパティ: viewStyle
• Since: WordPress 6.5.0

{ "viewStyle": [ "file:./view.css", "example-view-style" ] }

ブロックタイプのフロントエンドスタイル定義。サイトのフロントでコンテンツを表示するときにのみエンキューされます。

渡せるものは、wp_register_style 関数で登録したスタイルハンドル、block.json ファイルからの相対パスによる CSS ファイル、またはその両方を合わせたリストです (詳細)。

フロントエンドのみのスタイルは、特に Interactive ブロックに便利です。エディターでスタイルが必要のない、ユーザーが何らかのアクションを実行した後にのみ表示される部分にスタイルを適用できます。これにはまず style プロパティを使用して、共通スタイルを1つのスタイルシートにまとめます。そしてエディター固有のスタイル、フロントエンド固有のスタイルが必要になったときのみ、editorStyle や viewStyle で拡張します。このときスタイルの共通部分は引き続きメインのスタイルシートで保持されます。

Render

• 型: WPDefinedPath (詳細)
• オプション
• ローカライズ: 不可
• プロパティ: render
• Since: WordPress 6.1.0

{ "render": "file:./render.php" }

フロントエンドに表示するブロックタイプをサーバでレンダリングする際に使用する PHP ファイル。次の変数がファイルに公開されます。

• $attributes (array): ブロックの属性
• $content (string): ブロックのデフォルトコンテンツ
• $block (WP_Block): ブロックのインスタンス

render で定義される render.php ファイルの実装例は、次のようになります。

<div <?php echo get_block_wrapper_attributes(); ?>>
	<?php echo esc_html( $attributes['label'] ); ?>
</div>

注意: このファイルは、サーバー上でページの HTML をレンダリングするときに、ブロックタイプのインスタンスごとにロードされます。ファイル内で関数やクラスを宣言する際には、この点を考慮する必要があります。エラーのリスクを回避する最も簡単な方法は、その共有ロジックを別のファイルから消費することです。

アセット

WPDefinedPath

WPDefinedPath タイプは string のサブタイプです。値は、block.json ファイルのある場所から JavaScript、CSS、PHP ファイルへの相対パスで表します。提供されるパスには、接頭辞 file: を付ける必要があります。この方法は npm のパッケージのローカルパス を扱う方法に基づいています。

例:

In block.json:

{
	"render": "file:./render.php"
}

WPDefinedAsset

JavaScript や CSS ファイル用に WPDefinedPath を拡張します。ファイルパスの代わりに、WordPress ヘルパーを使用して登録済みのアセットを参照するスクリプトハンドル、スクリプトモジュール ID、スタイルハンドルを使用できます。

例:

block.json 内

{
	"editorScript": "file:./index.js",
	"script": "file:./script.js",
	"viewScriptModule": [
		"file:./view.js",
		"example-registered-script-module-id"
	],
	"editorStyle": "file:./index.css",
	"style": [ "file:./style.css", "example-shared-style" ],
	"viewStyle": [ "file:./view.css", "example-view-style" ]
}

WordPress のコンテキスト内で、PHP でブロックが登録されると、自動的に block.json ファイル内に見つかるすべてのスクリプト、スクリプトモジュール、スタイルを登録し、アセットハンドルでなくファイルパスを使用します。

WPDefinedAsset タイプが、wp_register_script、wp_register_script_module、wp_register_style を使用した、スクリプト、スクリプトモジュール、スタイルの登録に必要なパラメータをミラーする方法を提供し、ブロックと関連するハンドルやスクリプトモジュール ID を割り当てなければならないのはこのためです。

次の形式を取るオブジェクトを指定できます。

• dependencies (string[]|{ id: string, import?: 'dynamic'|'static' }[]) – このスクリプトが依存する、登録済みのスクリプトハンドルの配列。スクリプトモジュールは、静的な依存関係には単純な文字列を、動的な依存関係を示すにはオブジェクト形式を使用します。動的な依存関係は、実行時に使用されるかどうかわからない依存関係で、通常は動的な import('module-id') 構文を使用します。デフォルト値: [].
• version (string|false|null) – スクリプトのバージョン番号を指定する文字列 (バージョン番号がある場合)。バージョン番号が false に設定されている場合は、現在インストールされている WordPress のバージョン番号が自動的に追加されます。null に設定すると、バージョンは追加されません。デフォルト値: false.

定義は、個別の PHP ファイル内に保存されます。ファイル名の最後は .asset.php で、block.json にリストされた JavaScript や CSS ファイルの隣に配置されます。WordPress は自動的にこのファイルをパターンマッチで検知します。@wordpress/scripts パッケージでこれらのアセットファイルを自動生成するオプションになると期待されるため、このオプションが好まれます。

例:

build/
├─ block.json
├─ index.js
└─ index.asset.php

block.json 内

{ "editorScript": "file:./index.js" }

build/index.asset.php 内

<?php
return array(
	'dependencies' => array(
		'react',
		'wp-blocks',
		'wp-i18n',
	),
	'version'      => '3be55b05081a63d8f9d0ecb466c42cfd',
);

フロントエンドでのエンキュー

WordPress 5.8リリースから、フロントエンドでレンダーされるときにのみ、ブロックタイプのスクリプトとスタイルをエンキューするように WordPress に指示できます。これは、block.json ファイルの以下のアセットフィールドに適用されます。

• script
• viewScript
• style
• viewStyle (Added in WordPress 6.5.0)

国際化

WordPress 文字列ディスカバリシステムは、このドキュメントで翻訳可能とマークされたフィールドを自動的に翻訳します。まずブロックメタデータを提供する block.json ファイル内で textdomain プロパティを設定する必要があります。

例:

{
	"title": "My block",
	"description": "My block is fantastic",
	"keywords": [ "fantastic" ],
	"textdomain": "my-plugin"
}

PHP

PHP では、ローカライズされるプロパティは、WordPress のバックエンドで register_block_type 実行時に、自動的に _x 関数でラップされます。これらの翻訳はインラインスクリプトとしてプラグインのスクリプトハンドル、または WordPress コアの wp-block-library スクリプトハンドルに追加されます。

register_block_type プロセスの働きにより、翻訳可能な値は、およそ次のコードスニペットのようになります。

<?php
$metadata = array(
	'title'       => _x( 'My block', 'block title', 'my-plugin' ),
	'description' => _x( 'My block is fantastic!', 'block description', 'my-plugin' ),
	'keywords'    => array( _x( 'fantastic', 'block keyword', 'my-plugin' ) ),
);

実装は既存の get_plugin_data 関数に従い、プラグインのコンテンツをパースしてプラグインのメタデータを取得し、動的に翻訳を適用します。

JavaScript

JavaScript では @wordpress/blocks パッケージから registerBlockType を使用し、第1引数に block.json からロードされたブロックメタデータオブジェクトを渡すことができます。すべてのローカライズされたプロパティは自動的に @wordpress/i18n パッケージの _x 関数呼び出しでラップされます。これは PHP での動作と同様です。

例:

import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata, {
	edit: Edit,
	// ...other client-side settings
} );

後方互換性

既存の登録方式は、サイバーサイド、フロントエンドの両方で引き続き動作します。block.json ベース登録の、ローレベルな実装詳細として機能します。

すべての詳細が準備できたら、コアブロックが徐々に移行される予定です。また、サードパーティ製のブロックはコンソールに警告が表示され、使用中のブロック登録 API をリファクタリングするよう促されます。

次のプロパティは後方互換性のため、クライアントサイドのみでサポートされる予定です。将来的にはこのうちのいくつかが代替の API で置換されるかもしれません。

• edit – 詳細についてはドキュメント「edit と save」を参照してください。
• save – 詳細についてはドキュメント「edit と save」を参照してください。
• transforms – 詳細についてはドキュメント「transforms」を参照してください。
• deprecated – 詳細についてはドキュメント「非推奨にするブロック」を参照してください。
• merge – 今日現在、ドキュメントされていません。役割としては、複数のブロックを1つにマージ処理します。
• getEditWrapperProps – 同様に、ドキュメントされていません。役割としては、ブロック編集のコンポーネントラッパーに追加の props を注入します。

例:

import { registerBlockType } from '@wordpress/blocks';

registerBlockType( 'my-plugin/block-name', {
	edit: function () {
		// Edit definition goes here.
	},
	save: function () {
		// Save definition goes here.
	},
	getEditWrapperProps: function () {
		// Implementation goes here.
	},
} );

WordPress でサポートされる 動的ブロック の場合、サーバー上で register_block_type 関数を使用して render_callback プロパティを登録することは変わらず可能です。

原文