useBlockProps
既定では、Gutenberg はブロックをエディター内でインタラクティブにするため、ブロックを囲む要素を作成します。コンテナーやカラムなどのブロックタイプでは、エディターとフロントエンドでマークアップが異なるため、問題になることがあります。useBlockPropsフックを使うと、ブロックテンプレート内の要素をルート要素として指定でき、エディターとフロントエンドのマークアップを一致させられます。
使い方
ブロックのルート要素にuseBlockProps属性を追加するだけです。
<div useBlockProps class="my-class">
<!--
This element will be rendered
as the root element of your block
in Gutenberg.
-->
</div>
Blockstudioは、エディターのクラスや属性(配置クラスなど)を、ブロックテンプレートで定義された内容と自動的に統合します。その処理には内部でget_block_wrapper_attributesが使われます。
blockstudio/blocks/components/use_block_props/renderフィルターは、フロントエンドとエディターの両方のレンダリング経路でラッパーに適用されます。そのため、テーマやインスタンスごとの統合で追加されたクラスは、エディターのキャンバスと保存済みのフロントエンドのマークアップの両方に表示されます。
出力:
<div class="my-class wp-block-your-block-name alignright">
</div>
注意点
エディター内のリンク
Blockstudioは、ブロックエディター内でのリンク遷移を防ぎます。これには、target="_blank"、修飾キーを押しながらのクリック、中クリック、キーボードによるアクティベーションが含まれます。
クリックイベントは引き続きGutenbergに届くため、通常のクリックでブロックが選択されます。
RichTextは引き続き編集できます。この動作はuseBlockPropsの有無にかかわらず適用され、ブロックのルート要素にアンカーを使用している場合も同様です。
フロントエンドのリンクとブラウザーのコンテキストメニューコマンドは変わりません。テンプレートからリンクを削除したり、$isEditorに応じて処理を分岐したりする必要はありません。
ルート要素
ブロックテンプレートにルート要素を複数指定できないため、useBlockPropsを使う場合、ルート要素は1つにする必要があります。たとえば、次のコードは機能せず、Gutenberg がテンプレートを囲む要素を作成します。
<div useBlockProps>
First root element.
</div>
<span>
Second root element.
</span>
同様に、useBlockProps はブロックテンプレート内で1回だけ使用できます。
@記号
Blockstudioは、html-react-parserを使って、Gutenberg 内でブロックテンプレートを有効なReactコードに変換します。このため、@文字をHTML属性名の中で使用できないという制約があります。
Alpine.jsなどのライブラリは、@文字を使ってHTML要素にディレクティブを定義します。
<button useBlockProps @click="console.log('hi')">
Click me
</button>
Gutenberg 内では、この@click属性は要素から取り除かれます。(もちろん、フロントエンドでは引き続き機能します)
この問題を回避するには、Alpine.jsが提供する代替構文を使えます。
<button useBlockProps x-on:click="console.log('hi')">
Click me
</button>
上記のコードはGutenberg内でもフロントエンドでも機能します。
キャンバスのbodyクラス
assets.reset.enabledが有効な場合、BlockstudioはWordPressのbody_classフィルターが返すサニタイズ済みのクラスもブロックエディターのキャンバスにコピーします。これにより、.brand-a .site-cardなどのテーマセレクターが両方の場所で機能します。
エディターで使用するクラスを絞り込む場合は、最終的なクラス一覧を次のフィルターで調整します。
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
return array_values(array_diff($classes, ['logged-in']));
});
このフィルターが制御するのは、エディターのキャンバスにコピーされるクラスだけです。フロントエンドのbodyクラスは変更されません。