block.json

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

次の図は block.json ファイルの基本的な構造を詳説しています。

完全なブロックの例と関連する block.json ファイルを参照するには、Block Development Examples GitHub リポジトリにアクセスしてください。

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

「block.json のメタデータ」は、block.json ファイル内で使用できる、ブロックのすべてのプロパティに関する包括的なガイドです。この記事では、指定可能な最も一般的なオプションを取り上げます:

• ブロックの基本的なメタデータ。
• ブロックの機能、外観、出力を決定するファイル。
• ブロック内へのデータ保管方法。
• ユーザーインターフェース内でのブロックの設定パネル。

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

• apiVersion: ブロックが使用する API のバージョンを指定します。特別な要件がなければ、最新のバージョンを使用してください。
• name: 名前空間を含むブロックの一意の名前 (例: my-plugin/my-custom-block)。
• title: ブロックの表示タイトル。インサーター内で表示されます。
• category: インサーター内で、その下にブロックが表示されるカテゴリー。一般的なカテゴリーは、text、media、design、widgets、theme。
• icon: インサーター内でブロックを表すアイコン。Dashiconスラッグまたはカスタム SVG アイコン。
• description: ブロックの短い説明。タイトル以上のコンテキストを与えます。
• keywords: ユーザーのブロックの検索を支援するキーワードの配列。
• textdomain: 国際化で使用されるブロックのテキストドメイン。

また、block.json ファイルではブロックの機能に必要なファイルを指定できます。

• editorScript: ブロックエディター内のみで使用される JavaScript ファイル。
• editorStyle: ブロックエディター内でのスタイル用の CSS ファイル。
• script: ブロックエディターとフロントエンドの両方で読み込まれる JavaScript ファイル。
• style: ブロックエディターとフロントエンドの両方で適用される CSS ファイル。
• viewScript: フロントエンドのみを対象とする JavaScript ファイル。

これらのすべてのプロパティに対して、ファイルのパス (file: で始まる) や、wp_register_script または wp_register_style を使用して登録された ハンドル、または、両方のオプションを組み合わせた配列を指定できます。

さらに、WordPress 6.1 で導入された render プロパティは、動的にレンダーされる ブロックのフロントエンドのマークアップを生成する PHP テンプレートファイルへのパスを指定します。この方法は、 register_block_type() 関数に $render_callback 関数が提供されていない場合に使用されます。

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

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

以下は block.json で定義された3つの属性の例です。

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

ブロックは、JSON に似た特定の属性を含む HTML スタイルのコメントタグを使用して「区切られます」。これらの区切り文字によって、投稿コンテンツをレンダリングしたり、ブロックエディターで投稿を編集する際、ブロックの境界を認識し、ブロックの属性を解析できます。

以下は、ブロックの区切り文字で定義された属性を示すコードの例です。

<!-- 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 -->

すべての属性はシリアライズされ、デフォルトではブロックの区切り文字に格納されますが、これはニーズに合わせて構成できます。詳しくは記事「Understanding Block Attributes」を参照してください。

これらの属性は、ブロックエディターでの表示のためにブロックの Edit React コンポーネントや、データベースに保存されるマークアップ生成のために save 関数、ブロックのサーバーサイドレンダリング定義に渡されます。

Edit コンポーネントには setAttributes 関数を通して、これらの属性を変更するユニークな機能があります。

次の図は、典型的なブロックにおいて、属性がどのように保存、読み取り、更新されるかを詳説しています。

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

属性とカスタムブロックでの使用方法の詳細については、属性 API リファレンスガイドを参照してください。

コアブロックを含む多くのブロックには、同種のカスタマイズオプションがあります。例えば、背景色、テキスト色、パディングの調整など。

block.json の supports プロパティを使用すると、これらのブロックの一般的なカスタマイズオプションを宣言できます。有効化するとブロックのユーザーは、色やマージンなどのオプションを設定サイドバーから直接調整できます。

これらの定義済みの supports を活用することで、ブロックはコアブロックの動作と一貫性を持ち、同様の機能をゼロから作り直す必要がなくなります。

以下は block.json で定義された色の supports の例です。

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

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

次のコードは、ブロック supports を有効化して生成される属性とCSSクラスが、ブロックのマークアップ表現にどのように格納されるかを示しています。

<!-- 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 とカスタムブロックでの使用方法の詳細については、supports API リファレンスページを参照してください。

• block.json の図解
• 属性の図解

原文

最終更新日: 2024年5月31日