block.json

Topics

  • ブロックの基本のメタデータ
  • ブロックの動作、出力、スタイルのためのファイル
  • attributes を使用したブロックデータの保存
    • 属性の読み取りと更新
  • supports によるブロックの UI 設定パネルの有効化
  • その他の情報

block.json ファイルはブロックの定義と登録プロセスを簡素化します。両方のプロセスに JSON 形式の同じブロック定義を使用し、サーバーとクライアントの両方でブロックを登録します。

block.json の図解を開く

完全なブロックの例を見るには こちら をクリックして、block.json をチェックしてください。

block.jsonを使用することでブロックの登録が簡単になるだけでなく、パフォーマンスや開発性の向上など複数の利点があります。

block.json のメタデータには、block.json で設定できるすべてのプロパティの詳細な説明が記述されています。これらのプロパティを使用すると以下の定義が可能です。

  • ブロックの基本的なメタデータ
  • ブロックの動作、スタイル、出力のためのファイル
  • ブロック内へのデータ保管
  • ブロックの UI パネルの設定

ブロックの基本のメタデータ

block.json のプロパティを通して、ブロックの一意な識別方法や検索方法、ブロックエディターに表示されるブロックの情報を定義できます。プロパティの一部を紹介します。

  • apiVersion: ブロックが使用する API のバージョン (現在のバージョンは2)。
  • name: 名前空間を含むブロックの一意な識別子。
  • title: ブロックの表示タイトル。
  • category: インサーターパネルでのブロックのカテゴリー。
  • iconDashiconスラッグまたはカスタム SVG アイコン。
  • description: ブロックインスペクタに表示される短い説明。
  • keywords: ブロックをインサータで検索する際に使用。
  • textdomain: プラグインのテキストドメイン (翻訳などで重要)。

Top ↑

ブロックの動作、出力、スタイルのためのファイル

editorScript と editorStyle プロパティは エディターでのみ エンキューされてロードされる Javascript と CSS ファイルを定義します。

script と style プロパティは エディターとフロントエンドの両方で エンキューされてロードされる Javascript と CSSファイルを定義します。

viewScript プロパティは フロントエンドでのみ エンキューされてロードされる1つ以上の Javascript ファイルを定義します。

これらのプロパティ (editorScripteditorStylescript styleviewScript) の値には、ファイルのパス (接頭辞に file: を付ける) か、wp_register_script または wp_register_style で登録されたハンドル か、その両方を含む配列を指定します。

render プロパティ (WordPress 6.1で導入) は、フロントエンドに返されるマークアップをレンダーする .php テンプレートファイルのパスを設定します。このメソッドは register_block_type 関数に $render_callback 関数が渡されていない場合にのみ、リクエストに応じてブロックのマークアップを返すために使用されます。

Top ↑

attributes を使用したブロックデータの保存

ブロックの属性は、ブロックに割り当てられた設定やデータです。ブロックのさまざまな要素を決定できます。例えば、コンテンツ、レイアウト、スタイル、その他ブロックの構造とともに保存したい特定の情報などです。たとえばフォントサイズなど、ユーザーがブロックを変更すると、その変更を永続化する方法が必要です。属性はその解決策です。

新しいブロックタイプを登録する際、block.json の attributes プロパティに、ブロックが必要なカスタムデータとデータベースへの保存方法を記述します。これにより、エディターは値を正しく解析し、ブロックの Edit と save 関数に attributes を渡せます。

例: block.json で定義された属性

"attributes": {
	"fallbackCurrentYear": {
		"type": "string"
	},
	"showStartingYear": {
		"type": "boolean"
	},
	"startingYear": {
		"type": "string"
	}
},

デフォルトでは属性はシリアライズされ、ブロックのデリミッタに格納されますが、これは構成できます

例: ブロックのマークアップ表現として保管された属性

<!-- wp:block-development-examples/copyright-date-block-09aac3 {"fallbackCurrentYear":"2023","showStartingYear":true,"startingYear":"2020"} -->
<p class="wp-block-block-development-examples-copyright-date-block-09aac3">© 2020–2023</p>
<!-- /wp:block-development-examples/copyright-date-block-09aac3 -->x

これらの 属性 は React コンポーネントの Edit (ブロックエディターに表示するため)、save 関数 (データベース に保存されるマークアップを返すため)、そしてブロックの任意のサーバーサイドレンダー定義 (上の render プロパティ参照) に渡されます。

Top ↑

属性の読み取りと更新

Edit コンポーネントは、setAttributes 関数を介して主に属性を更新する機能を受け取ります。

どのように属性が Edit コンポーネントsave 関数render.php に渡されるかは、上のコードの ブロックの例 を参照してください。

Attributes API に関する完全な情報については、属性のリファレンスページを参照してください。

属性の図解を開く

Top ↑

supports によるブロックの UI 設定パネルの有効化

コアブロックを含む多くのブロックは、同種のカスタマイズオプションを提供します。例えば、背景色の変更、テキスト色の変更、パディングのカスタマイズオプションの追加など。

block.json の supports プロパティは、ブロックの特定機能のサポートを宣言します。ユーザーは設定サイドバーから特定の設定 (色やマージンなど) をカスタマイズできます。

利用可能なブロック supports を使用することで、ブロックの動作をコアブロックに合わせられ、同じ機能を自分で繰り返さずにすみます。

例: block.json で定義される supports

"supports": {
	"color": {
		"text": true,
		"link": true,
		"background": true
	}
}

supportsを使用すると、プロパティのセットが生成されます。このプロパティは手動でブロックのラッピング要素に追加して、ブロックデータの一部として適切に保存されるようにする必要があります。

supportsを使用するとプロパティのセットが生成されますが、これは手動でブロックのラッピング要素に追加する必要があります。これにより、ブロックデータの一部として適切に保存され、フロントエンドに配信されるブロックのマークアップを生成する際に考慮されることが保証されます。

例: ブロックのマークアップ表現として保存される supports のカスタム設定

<!-- wp:block-development-examples/block-supports-6aa4dd {"backgroundColor":"contrast","textColor":"accent-4"} -->
<p class="wp-block-block-development-examples-block-supports-6aa4dd has-accent-4-color has-contrast-background-color has-text-color has-background">Hello World</p>
<!-- /wp:block-development-examples/block-supports-6aa4dd -->

上のコード完全なブロックの例を参照してください。

Supports APIに関する詳細な情報については、サポートのリファレンスページを参照してください。

Top ↑

その他の情報

原文

最終更新日: