Home / Team Handbook / ブロックエディターハンドブック / リファレンスガイド / ブロック API リファレンス / メタデータ

メタデータ

Topics

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!"
		}
	},
	"editorScript": "file:./build/index.js",
	"script": "file:./build/script.js",
	"viewScript": "file:./build/view.js",
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style.css"
}

ブロック API ブロック API

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

Top ↑

API Version API Version

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

{ "apiVersion": 2 }

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

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

Top ↑

Name Name

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

{ "name": "core/heading" }

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

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

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

Top ↑

Title Title

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

{ "title": "Heading" }

ブロックの表示タイトルです。翻訳関数で翻訳できます。ブロックインサーターはこの名前を表示します。

Top ↑

Category Category

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

{ "category": "text" }

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

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

text
media
design
widgets
theme
embed

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

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

Top ↑

Parent Parent

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

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

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

Top ↑

Icon Icon

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

{ "icon": "smile" }

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

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

Top ↑

Description Description

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

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

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

Top ↑

Keywords Keywords

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

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

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

Top ↑

Version Version

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

{ "version": "1.0.3" }

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

Top ↑

Text Domain Text Domain

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

{ "textdomain": "my-plugin" }

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

Top ↑

Attributes Attributes

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

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

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

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

Top ↑

Provides Context Provides Context

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

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

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

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

Top ↑

Context Context

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

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

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

{
	"usesContext": [ "message" ]
}

Top ↑

Supports Supports

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

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

Top ↑

Block Styles Block Styles

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

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

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

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

Top ↑

Example Example

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

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

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

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

Top ↑

Editor Script Editor Script

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

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

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

Top ↑

Script Script

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

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

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

Top ↑

View Script View Script

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

{ "viewScript": "file:./build/view.js" }

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

Top ↑

Editor Style Editor Style

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

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

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

Note: An option to pass also an array of editor styles exists since WordPress 5.9.0.

Top ↑

Style Style

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

{ "style": "file:./build/style.css" }

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

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

Top ↑

アセットアセット

Top ↑

WPDefinedAsset WPDefinedAsset

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

代わりに WordPress ヘルパーを使用してすでに登録されたアセットを参照する、スクリプトハンドル名やスタイルハンドル名も使用できます。

例:

block.json 内

{
	"editorScript": "file:./index.js",
	"script": "my-script-handle",
	"viewScript": "file:./view.js",
	"editorStyle": "my-editor-style-handle",
	"style": [ "file:./style.css", "my-style-handle" ]
}

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 パッケージでこれらのアセットファイルを自動生成するオプションになると期待されるため、このオプションが好まれます。

例:

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

block.json 内

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

build/index.asset.php 内

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

Top ↑

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

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

script
viewScript (PHP の登録時にブロックが render_callback を定義する場合、ブロックの作者はスクリプトをエンキューする責任があります。)
style

Top ↑

国際化国際化

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

例:

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

Top ↑

PHP 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 関数に従い、プラグインのコンテンツをパースしてプラグインのメタデータを取得し、動的に翻訳を適用します。

Top ↑

JavaScript 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
} );

Top ↑

後方互換性後方互換性

既存の登録方式は、サイバーサイド、フロントエンドの両方で引き続き動作します。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 プロパティを登録することは変わらず可能です。

原文

最終更新日: 2021年12月12日

ようこそ

協力者募集中

フィードバック

メタデータ

Topics