ブロックタイプメタデータ

JavaScript コードと PHP コードベース間で共有可能なメタデータを使用して、新しいブロックタイプを登録できます。これにはまず block.json ファイルを作成します。block.json ファイルは、

  • ブロックタイプに名前を付与します。
  • 登録されるブロックタイプの重要なメタデータを定義します。例: title、category、icon、description、keywords
  • ブロックタイプの属性を定義します。
  • ブロックタイプのすべてのスクリプトとスタイルを登録します。

例:

{
    "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" ],
    "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",
    "editorStyle": "file:./build/index.css",
    "style": "file:./build/style.css"
}

ブロックディレクトリへブロックをサブミットする際にも同じファイルが使用されます。

サーバーサイドでの登録

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

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

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

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

例:

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

ブロック API

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

Name

  • 型: string
  • 必須
  • ローカライズ: 不可
  • プロパティ: name
{ "name": "core/heading" }

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

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

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

Title

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

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

Category

  • 型: string
  • 必須
  • ローカライズ: 不可
  • プロパティ: category
{ "category": "text" }

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

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

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

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

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

Parent

  • 型: string[]
  • オプション
  • ローカライズ: 不可
  • プロパティ: parent
{ "parent": [ "my-block/product" ] }

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

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

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

Text Domain

  • 型: string
  • オプション
  • ローカライズ: 不可
  • プロパティ: textdomain
{ "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" ]
}

Supports

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

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

Style Variations

  • 型: 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 (オプション)」セクション を参照してください。

Editor Script

  • 型: string (WPDefinedAsset)
  • オプション
  • ローカライズ: 不可
  • プロパティ: editorScript
{ "editorScript": "file:./build/index.js" }

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

Script

  • 型: string (WPDefinedAsset)
  • オプション
  • ローカライズ: 不可
  • プロパティ: script
{ "script": "file:./build/script.js" }

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

Editor Style

  • 型: string (WPDefinedAsset)
  • オプション
  • ローカライズ: 不可
  • プロパティ: editorStyle
{ "editorStyle": "file:./build/index.css" }

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

Style

  • 型: string (WPDefinedAsset)
  • オプション
  • ローカライズ: 不可
  • プロパティ: style
{ "style": "file:./build/style.css" }

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

アセット

WPDefinedAsset

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

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

例:

block.json 内

{
    "editorScript": "file:./build/index.js",
    "editorStyle": "my-editor-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 パッケージでこれらのアセットファイルを自動生成するオプションになると期待されるため、このオプションが好まれます。

例:

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',
);

国際化

WordPress 文字列ディスカバリは自動的に、翻訳可能とマークされたドキュメント内のフィールドを翻訳します。マークには block.json ファイル内の textdomain プロパティを使用します。このとき、ローカライズされるプロパティは、WordPress のバックエンドでregister_block_type_from_metadata 実行時に、自動的に _x 関数でラップされます。これらの翻訳はインラインスクリプトとして WordPress コアの wp-block-library スクリプトハンドル、またはプラグインのスクリプトハンドルに追加されます。

例:

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

register_block_type_from_metadata プロセスの働きにより、翻訳可能な値は、およそ次のようになります。

<?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 keywords', 'my-plugin' ) ),
);

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

後方互換性

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

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

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

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

例:

wp.blocks.registerBlockType( 'my-block/name', {
    edit: function () {
        // edit 定義がここに来ます。
    },
    save: function () {
        // save 定義がここに来ます。
    },
    getEditWrapperProps: function () {
        // 実装がここに来ます。
    },
} );

WordPress にサポートされる ダイナミックブロック の場合、サーバー上で register_block_type と register_block_type_from_metadata の両方を使用して render_callback プロパティを登録することは変わらず可能です。

原文

最終更新日: