block.json のメタデータ

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

例:

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 2,
	"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" ],
	"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" ],
	"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"

register_block_type 関数を使用すると、サーバーで block.json ファイル内に保存されたメタデータから簡単にブロックタイプを登録できます。

この関数は、このコンテキストに関連する2つのパラメータを取ります ($block_type は、より多くのタイプやバリアントを受け入れます）。

• $block_type (string) – block.json ファイルのあるフォルダーへのパス、または、名前が異なる場合、メタデータファイルへのフルパス。
• $args (array) – ブロックタイプ引数のオプション配列。デフォルト値は []。任意の引数を定義可。ただし、以下はデフォルトでサポートされる。
  • $render_callback (callable) – このブロックタイプのブロックをレンダーする際に使用されるコールバック。これは block.json 内の render フィールドの代替。

関数は、成功すると登録されたブロックタイプ (WP_Block_Type)、失敗すると false を返します。

例:

register_block_type(
	__DIR__ . '/notice',
	array(
		'render_callback' => 'render_block_core_notice',
	)
);

サーバーでブロックを登録した場合、クライアントではクライアント側設定を同じブロック名で登録するだけで構いません。

例:

registerBlockType( 'my-plugin/notice', {
	edit: Edit,
	// ...other client-side settings
} );

上述の理由により、PHP を使用してサーバー上にもブロックを登録することが推奨されていますが、クライアントサイドだけでブロックを登録する場合は、@wordpress/blocks パッケージの registerBlockType メソッドを使用して、block.json ファイルから読み込んだメタデータでブロックタイプを登録できます。

関数は2つの引数を取ります。

• $blockNameOrMetadata (string|Object) – ブロックタイプ名 (以前からサポート済み)、または、webpack などのバンドラーやカスタム Babel プラグインで、block.jsonファイルからロードされたメタデータオブジェクトです。
• $settings (Object) – クライアント側のブロックの設定。

関数は、成功すると登録されたブロックタイプ (WPBlock)、失敗すると undefined を返します。

例:

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

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

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

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

{ "apiVersion": 2 }

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

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

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

{ "name": "core/heading" }

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

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

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

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

{ "title": "Heading" }

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

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

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

{ "category": "text" }

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

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

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

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

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

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

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

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

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

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

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

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

{ "icon": "smile" }

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

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

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

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

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

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

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

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

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

{ "version": "1.0.3" }

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

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

{ "textdomain": "my-plugin" }

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

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

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

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

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

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

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

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

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

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

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

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

{
	"usesContext": [ "message" ]
}

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

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

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

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

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

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

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

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

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

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

• 型: object[]
• オプション
• ローカライズ: 可 (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 ファイルでは、どちらも文字列のみをサポートします。

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

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

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

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

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

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

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

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

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

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

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

• 型: 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 以降。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

例:

In block.json:

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

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

例:

block.json 内

{
	"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" ]
}

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

WPDefinedAsset タイプがミラーする方法だけでなく、wp_register_script と wp_register_style を使用してスクリプトとスタイルを登録する際に必要なパラメータも提供する必要があるのはこのためです。ブロックタイプ登録設定 script、style、editor_script、editor_style を使用して、ブロックに関連付けられたハンドルとして割り当てます。

次の形式を取るオブジェクトを提供することができます。

• handle (string) – スクリプトの名前。省略すると、自動的に生成される。
• dependencies (string[]) – このスクリプトが依存する、登録されたスクリプトのハンドルの配列。デフォルト値: []。
• version (string|false|null) – スクリプトのバージョン番号を指定する文字列。バージョンを指定すると、番号は URL にクエリ文字列として追加されます。これはキャッシュを避けるためです。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(
		'wp-blocks',
		'wp-element',
		'wp-i18n',
	),
	'version'      => '3be55b05081a63d8f9d0ecb466c42cfd',
);

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

• script
• viewScript
• style

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

例:

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

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 では @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 プロパティを登録することは変わらず可能です。

原文

最終更新日: 2023年1月9日