ブロックラッパー

Topics

ブロックエディターのすべてのブロックは HTML ラッパーの中に含まれます。エディター内とフロントエンド上の両方で正しく機能するには、決められた属性を持つ必要があります。開発者として、私たちはこのマークアップを直接操作でき、WordPress の提供する useBlockProps() のようなツールを使用して、ブロックのラッパーに追加された属性を変更できます。

ブロックラッパーに適切な属性を付けることは、カスタムスタイルやブロック supportsのような機能を使用する場合に、特に重要です。

WordPress のブロックは、3つの異なるタイプのマークアップで定義でき、それぞれがユニークな役割を果たします。

  • エディターマークアップ: このマークアップは、ブロックエディター内でのブロックの視覚的な表現です。ブロックが registerBlockType によってクライアントサイドで登録される際に、Edit React コンポーネントを使用して定義されます。
  • save マークアップ: このマークアップは、ブロックのコンテンツが保存される際にデータベースに保存されます。これもブロックの登録時に registerBlockType で提供される save 関数経由で指定されます。ブロックがダイナミックレンダリングを利用しなければ、この保存されたマークアップがフロントエンドに表示されます。
  • ダイナミックレンダーマークアップ: ブロックのコンテンツを動的に生成する場合、このマークアップが必要になります。サーバーサイドで定義され、register_block_type の render_callback 関数か、block.json で指定された render.php ファイルで定義されます。存在すれば、このマークアップは保存されたマークアップを上書きし、ブロックのフロントエンドの表示に使用されます。

Edit コンポーネントと save 関数の両方において、ラッパー要素は、標準的な DOM 要素（例: <div>）、またはネイティブ DOM 要素にすべての追加 prop を渡す React コンポーネントでなければなりません。これらのラッパーに React フラグメント (<Fragment>) や <ServerSideRender> コンポーネントは使えません。

エディターマークアップ

useBlockProps() フックは、@wordpress/block-editor パッケージで提供され、Edit コンポーネント内でのブロックの外側マークアップの定義に使用されます。

このフックは、以下のようないくつかのタスクを単純化します。

  • ブロックの HTML 構造へのユニーク id の割り当て。
  • 機能や情報を拡張するため、様々なアクセシビリティと data- 属性を追加。
  • ブロックのカスタム設定を反映するクラスとインラインスタイルの組み込み。デフォルトでは、以下が含まれる。
    • 一般的なブロックスタイル用の wp-block クラス。
    • ブロック固有のクラス。ブロックの名前空間と名前を組み合わせ、ユニークで的を絞ったスタイル機能を確保する。

次の例では、useBlockProps()フックを使用して、Editコンポーネントでブロックのエディターマークアップを定義します。

const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;

registerBlockType( ..., {
	edit: Edit
} );

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

ブロックエディターでのブロックのマークアップは次のようになります。クラスと属性は自動的に適用されます。

<p
    tabindex="0"
    id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe"
    role="document"
    aria-label="Block: Minimal Gutenberg Block ca6eda"
    data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe"
    data-type="block-development-examples/minimal-block-ca6eda"
    data-title="Minimal Gutenberg Block ca6eda"
    class="
        block-editor-block-list__block
        wp-block
        is-selected
        wp-block-block-development-examples-minimal-block-ca6eda
    "
>Hello World - Block Editor</p>

ブロックの Edit コンポーネントでは、 useBlockProps() フックを使用して、追加のクラスや属性を引数として渡します (例 を参照してください)。

supports プロパティを使用して機能を有効化すると、対応するクラスや属性は自動的に useBlockProps が返すオブジェクトに含まれます。

Top ↑

save マークアップ

マークアップをデータベース内に保存する際には、必ず useBlockProps.save() が返す prop をブロックのラッパー要素に追加してください。useBlockProps.save() は、ブロッククラス名、そしてブロックの supports API によって注入された HTML 属性を正しくレンダーします。

次のコードはクライアント内でブロックを登録します。ブロックを編集するときと、ブロックがデータベースに保存されるときに使用されるマークアップの定義方法に注意してください。

const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;
const save = () => <p { ...useBlockProps.save() }>Hello World - Frontend</p>;

registerBlockType( ..., {
	edit: Edit,
	save,
} );

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

フロントエンド上でのブロックのマークアップは次のようになります。クラスは自動的に適用されます。

<p class="wp-block-block-development-examples-minimal-block-ca6eda">Hello World – Frontend</p>

ブロックの save 関数にクラスや属性を追加したければ、useBlockProps.save() の引数として渡してください (例を参照てください)。

任意の機能で supports を追加すると、useBlockProps.save() フックが返すオブジェクトに適切なクラスが追加されます。次の例では、テキストと背景色のクラスが段落ブロックに追加されています。

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

この HTML を生成した ブロックの例 は、Block Development Examples リポジトリで参照できます。

Top ↑

ダイナミックレンダーマークアップ

ブロックのサーバー側レンダー定義にあるマークアップは get_block_wrapper_attributes() 関数を使用して、ブロックの設定を反映するために必要な属性の文字列を生成できます。例を参照してください。

ダイナミックブロックでは、フォントエンドのマークアップはサーバーサイドでレンダーされます。save 関数で useBlockProps.save() を使用したのと同じように、get_block_wrapper_attributes() 関数を利用して、必要なクラスと属性を出力できます。例を参照してください。

<p <?php echo get_block_wrapper_attributes(); ?>>
	<?php esc_html_e( 'Block with Dynamic Rendering – hello!!!', 'block-development-examples' ); ?>
</p>

原文

最終更新日: