コンポーネント
組み合わせ
同梱のUIコンポーネントは、単体で使うのではなく組み合わせて使うように設計されています。セレクトはダイアログ内で開き、フォームはドロワー内で検証され、メニューはテーブル行に配置されます。このページでは、こうした連携を支える仕組みを説明します。複合ファミリーの構造、トリガーによるボタンプロパティの引き継ぎ、内部で使われるInteractivity API、重なった画面要素の一貫性を保つレイヤーモデルを取り上げます。
複合ファミリー
複合コンポーネントは、ルートブロックと子ブロックで構成されます。ルートが状態を管理し、各子ブロックはblock.json内のparentとusesContextを通じて、ファミリー内での位置を宣言します。
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
ルートはInnerBlocks領域を公開します。そこにはallowedBlocksリストと開始時のtemplateがあり、エディターでダイアログを挿入するとトリガー、バックドロップ、ポップアップが自動で用意されます。エディター、ファイルベースのページ、タグのいずれで構成しても、同じように動作します。
<bs:bsui-select name="role" placeholder="Pick a role">
<bs:bsui-select-trigger />
<bs:bsui-select-popup>
<bs:bsui-select-option value="viewer" label="Viewer" />
<bs:bsui-select-option value="editor" label="Editor" />
</bs:bsui-select-popup>
</bs:bsui-select>
ポップアップとパネルは通常のInnerBlocks領域であり、特別な構文を使うスロットではありません。bsui/dialog-popupにはグループブロックと同じ方法で子ブロックを入れられるため、フォームやセレクト、別のダイアログを中に配置することも普通の構成操作として行えます。
フラットなデータまたは組み合わせた子要素
ファミリーによっては、子要素の代わりにデータとしてコンテンツを受け取ります。セレクトにPHP由来の選択肢を渡す場合、optionsJSON配列を渡すと、トリガーとリストボックスが自動で表示されます。
bs_render_block([
'name' => 'bsui/select',
'data' => [
'name' => 'role',
'placeholder' => 'Pick a role',
'options' => wp_json_encode([
['value' => 'viewer', 'label' => 'Viewer'],
['value' => 'editor', 'label' => 'Editor'],
]),
],
]);
どちらの形式でも、同じマークアップ仕様と実行時の動作になります。構造を手作業で記述する場合は子要素を、計算によって生成する場合はoptionsを使います。
トリガーへの引き継ぎ
オーバーレイコンポーネントはボタンから開くため、そのボタンにはシステムボタンを使います。各トリガーでボタンを作り直す代わりに、bsui/dialog、bsui/alert-dialog、bsui/drawer、bsui/menu、bsui/popover、bsui/collapsible、bsui/tooltipのトリガーブロックには、ブロックフィールドを介してbsui/buttonを埋め込みます。
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructureは、ボタンの各フィールド名の先頭にtrigger_を付けてトリガーに展開します。trigger_label、trigger_variant、trigger_size、trigger_icon、trigger_iconPosition、trigger_href、trigger_disabledなど、すべてのボタンプロパティを利用できます。
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
トリガーのテンプレートでは、$a['trigger']がレンダリング済みのボタンなので、スタイルシートや今後の改良もボタンとともに適用されます。実行時には共通ヘルパーが、ラッパーのARIA設定(aria-haspopup、aria-expanded、aria-controls、aria-describedby、aria-labelledby、id)を内部のボタンに引き継ぎ、MutationObserverを通じて同期します。そのため、支援技術からは一貫した1つのコントロールとして認識されます。
内部で使われるInteractivity API
インタラクティブなファミリーはそれぞれ、WordPress Interactivity APIストアを持ち、bsui/dialog、bsui/select、bsui/form、bsui/tabsなど、ルートブロックの名前が付けられています。ここから3つの特徴が生まれます。
状態はサーバー側で初期化されます。 ルートテンプレートはブロックの属性から初期状態をdata-wp-contextとして出力します。
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
最初の描画は正しく行われHTML、クライアント側のハイドレーションによるちらつきはありません。ポップアップはhidden開始し、コンテキストがフロントエンド専用の状態処理に依存しないため、同じマークアップがエディターのキャンバスでも機能します。
動作はディレクティブで接続され、JavaScriptは使いません。 テンプレートではマークアップとストアを宣言的に接続します。PHPを取り除いたセレクトのトリガーは、ディレクティブだけで構成されています。
<button
data-wp-interactive="bsui/select"
data-wp-on--click="actions.toggle"
data-wp-on--keydown="actions.handleTriggerKeyDown"
data-wp-bind--aria-expanded="state.ariaExpanded"
data-wp-text="state.displayValue"
data-bsui-select-trigger
aria-haspopup="listbox"
>
data-wp-onはイベントをアクションに振り分け、data-wp-bindは属性を派生状態と同期し、data-wp-textは状態をテキストとして表示します。data-wp-on-document--clickはルートに外側クリックで閉じる動作を追加します。コンポーネントの組み合わせにイベントハンドラーを書く必要はありません。ストアはインラインモジュールとしてブロックに含まれます。
独自のストアを連携できます。 フォームコントロールでは属性としてディレクティブ式を指定でき、Interactivity APIの名前空間構文を使って任意のストアを参照できます。onChangeは変更処理を独自のアクションに振り分け、checkedはコントロールの状態を独自の状態に結び付けます。bindTextを使えば、ラベルをdata-wp-textスパンとして表示し、任意の状態パスに結び付けられます。
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindTextはbsui/label、bsui/checkbox、bsui/switch、bsui/toggle、bsui/radio-groupの項目で利用できます。チェックボックス、スイッチ、ラジオの各項目では、共通のラベルプリミティブに反映されるため、状態に応じて変わるテキストにもシステムのラベルと同じタイポグラフィが適用されます。セレクトなどの入力ではさらに、ルートからバブリングするchangeイベントが発火し、新しい値がdetailに含まれます。より大まかな連携に使えます。
制御された値
値を独自に管理するコントロールでは、valueまたはcheckedを未設定のままにします。初期選択にはdefaultValue、defaultChecked、またはToggleのdefaultPressedを使います。単独のToggleは、コンシューマーストアなしでポインター入力とキーボード入力を処理します。
独自のストアからフィールドを制御するには、バインディングと、バインドされた値を更新するonChangeアクションの両方を指定します。valueはディレクティブのパスであり、リテラルのデフォルト値ではありません。Input、Textarea、Password Input、Number Field、Slider、Radio Group、Color Picker、Rating、Time Pickerはvalueに対応しています。
Checkbox、Switch、Toggleでは、代わりにcheckedを使います。
パスには、それを所有する名前空間を付けます。たとえば、my/settings::context.quantityまたはmy/settings::state.quantityのように指定します。複合コントロールには独自の名前空間があり、名前空間なしのパスは親ストアではなく、そのコントロールを参照します。複合コントロールの値バインディングでは、数値の配列キーを含むコンテキストまたは状態へのドットパスに対応していますが、JavaScript式や関数呼び出しには対応していません。
以下は、Interactivity APIサポートを有効にしたカスタムブロックでの、Number Fieldの完全なバインディング例です:
<div
data-wp-interactive="my/settings"
data-wp-context='<?php echo esc_attr(wp_json_encode(['quantity' => 2])); ?>'
>
<bs:bsui-number-field
nameAlt="quantity"
defaultValue="2"
value="my/settings::context.quantity"
onChange="my/settings::actions.setQuantity"
/>
<output data-wp-text="context.quantity"></output>
</div>
import { getContext, store } from '@wordpress/interactivity';
store('my/settings', {
actions: {
setQuantity(event) {
// Compound controls publish their normalized value in a custom change event.
if (event.detail?.value !== undefined) {
getContext().quantity = event.detail.value;
}
},
},
});
サーバー側でレンダリングされる初期値にも、一致するデフォルト値を設定してください。ハイドレーション後は、0、false、空の値を含め、親の変更がバインドされたすべてのインスタンスに反映されます。CheckboxとSwitchの非表示フォーム入力も、それぞれのcheckedバインディングに従います。Time Pickerの値には、24時間形式のHH:MMまたは空文字列を使います。ネイティブのInput、Textarea、Password Inputのハンドラーではevent.target.valueを読み取ります。複合値コントロールはevent.detail.valueを出力します。
Number Fieldの上下限は任意です。minとmaxを省略すると上限・下限は設定されませんが、0を明示的に指定した場合は有効な境界値になります。
Select、Date Input、Phone Input、OTP InputはonChangeを通じて変更を出力しますが、この制御されたvalueバインディングは公開していません。初期値には、ドキュメントに記載されたデフォルトプロパティを使用してください。
独自ブロックからの構成
構成できるのはページだけではありません。ブロックタグはブロックテンプレート内で自動的にレンダリングされるため、プロジェクトのブロックからbsuiコンポーネントを直接出力し、独自の構造で囲めます。
<div useBlockProps class="settings-panel">
<bs:bsui-switch label="Public profile" name="public" />
<bs:bsui-space size="4" />
<bs:bsui-button label="Save" variant="default" />
</div>
PHPとbs_block()を使えば、同じことをcontentキーで入れ子にして実行できます。詳しくはプログラムによるレンダリングをご覧ください。どちらの方法でも、コンポーネントのスタイルシートとストアは一緒に読み込まれ、独自ブロックはシステム部品を配置する薄いレイヤーとして機能します。
コンポーネントを横並びに配置するには、bsui/stackを使います。これは汎用のフレックス行または列で、direction、間隔スケールのgap、align、justify、wrap切り替えを指定できます。デフォルトでは子要素は自然なサイズを保ちます。grow切り替えを使うと、子要素はスタックの長さを等分するように広がります。そのため、フッター内の2つのボタンを片端に寄せず、幅いっぱいに均等配置できます。
フィールドグループとカード
bsui/field-groupはフィールドセットをレンダリングします。デフォルトのバリアントは、背景面を追加せずに関連フィールドをグループ化します。落ち着いた外枠を付けるにはvariant="card"を使用し、その内側のコンテンツ面を表示するには、フィールドをbsui/field-group-content内に配置します。タイトルと説明はそのコンテンツブロックの外に置いてください:
<bs:bsui-field-group variant="card">
<bs:bsui-field-group-title text="Account settings" />
<bs:bsui-field-group-description text="Manage your account preferences." />
<bs:bsui-field-group-content>
<bs:bsui-field>
<bs:bsui-field-label text="Display name" />
<bs:bsui-input nameAlt="display_name" placeholder="Enter display name" />
</bs:bsui-field>
<bs:bsui-field>
<bs:bsui-field-label text="Email" />
<bs:bsui-input nameAlt="email" type="email" placeholder="Enter email" />
</bs:bsui-field>
</bs:bsui-field-group-content>
</bs:bsui-field-group>
グループのdisabled="true"では、ネイティブのフィールドセットの動作を利用して、フォームコントロールを無効にします。カードのスタイルを変更しても、デフォルトのバリアントは変わりません。
ツールバーの区切り線
ツールバー項目の間にbsui/toolbar-separatorを配置します。親ツールバーのorientationに従い、横向きのツールバーでは全高の縦線、縦向きのツールバーでは全幅の横線になります。区切り線はコントロールの高さを変えずに、ツールバーの枠線の内側まで伸びます。内容が利用可能な幅を超えると、横向きのツールバーはスクロールします。
レイヤーモデル
コンポーネントライブラリは、画面要素が重なると破綻しがちです。同梱コンポーネントは、実際のUI構築を想定したシンプルなルールに従います。
モーダルはbodyにポータル表示される
ダイアログ、アラートダイアログ、ドロワーを開くと、ポップアップとバックドロップはdocument.bodyに移動し、閉じたときの戻り先を示すコメントが元の場所に残ります。ポータル表示により、モーダルは祖先要素のoverflow、transform、スタッキングコンテキストの影響を受けません。開くとページのスクロールもロックされます。このロックはすべてのオーバーレイコンポーネントで参照カウントされ、スクロールバーの幅を補正してページのずれを防ぎます。バックドロップはz-index: 50、ポップアップは51に配置され、フォーカスはポップアップ内に移動します。Tabキーはポップアップ内にとどまり、閉じるとトリガーにフォーカスが戻ります。
モーダルは重ねて表示できます。ダイアログ内から別のダイアログを開くと、共通のスタックに追加されます。バックドロップが表示されるのは最外側のダイアログだけで、手前以外のダイアログは縮小されて背後からのぞきます。スタックは背後の各ポップアップに--bs-ui-nested-dialogsカスタムプロパティを設定し、階層が深くなるほど、ずれと縮小が大きくなります。また、親の高さを子に合わせることで、各レイヤーが均等にのぞくようにします。閉じると、1つずつ逆順にすべての状態が復元されます。
モーダルを閉じると、フォーカスはトリガーに戻り、正しい要素に移動します。共通のgetAnchorヘルパーがトリガーのラッパーから内部のシステムボタンを特定するため、見えないラッパーではなく、表示中のコントロールにフォーカスが戻ります。
最前面のモーダルにはtransformを適用しない
のぞき見効果のためにtransformを適用するのは背後のダイアログだけです。最前面のモーダルには意図的にtransformを適用しません。transformが適用された要素はposition: fixed子孫要素の包含ブロックとなり、その中で開くフローティングポップアップがすべて正常に動作しなくなるためです。
このルールがあるため、レイヤーモデル全体を組み合わせて使えます。フローティングレイヤーはすべて固定座標で配置されます。transformが設定された祖先がなければ、これらの座標はビューポート基準になります。
- メニューとコンボボックスはFloating UIの
fixed戦略を使い、トリガーを基準に位置を計算します。ビューポートに余裕がなければ下側に表示し、位置を反転または調整します。 - セレクトも未選択時は同じ方法で配置します。選択済みの場合は、選択肢がトリガーの真上に来るようにポップアップを合わせ、ビューポート内に収めます。これはmacOSのネイティブセレクトと同じ動作です。
- コンテキストメニューはポインターの
clientX/clientYで開きます。
最前面のモーダルにはtransformが適用されないため、ダイアログ、アラートダイアログ、ドロワーのどの中にあっても、入れ子の深さに関係なく、これらの要素はトリガーに正しく位置合わせされます。ポップアップはモーダル内にあることを認識する必要も、そのための処理もありません。
Escapeキーでは最も内側のレイヤーから閉じる
Escapeキーを1回押すと、内側から1レイヤーずつ閉じます。
- セレクトのリストボックス、メニュー、ポップオーバー、日付や電話番号のポップアップなど、開いているフローティングレイヤーが最初に閉じ、トリガーにフォーカスが戻ります。セレクトはイベントの伝播を止めます。また、フローティングレイヤーが開いている間はモーダルのハンドラーも処理を停止するため、その下のダイアログはキー操作を受け取りません。
- 次に最前面のモーダルが閉じます。
- モーダルが重なっている場合、Escapeキーを押すたびにスタックから1つずつ閉じます。
閉じる動作は意図されたルールであり、偶然の結果ではありません。dismissable="false"で表示したダイアログは、Escapeキーでもバックドロップのクリックでも閉じません。また、bsui/alert-dialogはモーダルと同様にEscapeキーで閉じますが、バックドロップのクリックは意図的に無視します。このパターンの目的は、誤操作で閉じないよう、閉じるかどうかを明示的に選ぶことです。通常のダイアログは、dismissableがデフォルトでtrueのため、バックドロップをクリックすると閉じます。
ダイアログ内のフォーム
上記のルールをすべて同時に確かめられるパターンです。トリガーでモーダルを開き、その中に入力検証を行うフォームがあり、フォームの中にフローティングセレクトがあります。
<bs:bsui-dialog>
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
<bs:bsui-dialog-backdrop />
<bs:bsui-dialog-popup>
<bs:bsui-dialog-header>
<bs:bsui-dialog-title content="Invite a teammate" />
<bs:bsui-dialog-description content="They receive an email with a join link." />
</bs:bsui-dialog-header>
<bs:bsui-dialog-content>
<bs:bsui-form block="team/invite" successMessage="Invitation sent.">
<bs:bsui-field name="email">
<bs:bsui-field-label text="Email" />
<bs:bsui-input name="email" type="email" placeholder="colleague@example.com" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<bs:bsui-field name="role">
<bs:bsui-field-label text="Role" />
<bs:bsui-select name="role" defaultValue="editor" placeholder="Pick a role">
<bs:bsui-select-trigger />
<bs:bsui-select-popup>
<bs:bsui-select-option value="viewer" label="Viewer" />
<bs:bsui-select-option value="editor" label="Editor" />
<bs:bsui-select-option value="admin" label="Admin" />
</bs:bsui-select-popup>
</bs:bsui-select>
</bs:bsui-field>
<bs:bsui-space size="2" />
<bs:bsui-button label="Send invite" />
</bs:bsui-form>
</bs:bsui-dialog-content>
<bs:bsui-dialog-footer>
<bs:bsui-dialog-close label="Cancel" />
</bs:bsui-dialog-footer>
</bs:bsui-dialog-popup>
</bs:bsui-dialog>
上記のタグと属性はすべて重要な役割を持ちます。トリガーはシステムボタンに処理を引き継ぎ、タイトルと説明にはcontentが設定され、各フィールドにはフォームのシリアライズに使う名前が指定されています。また、タグパーサーではrequired="true"が実際のブール値に変換されます。
実行時の各ストアの動作
bsui/dialog はサーバー上で {"open":false,"dismissable":true} をコンテキストに注入します。トリガーをクリックすると actions.open が実行されます。ポップアップと backdrop は body にポータルされ、スクロールバーの幅を補正してスクロールをロックします。ポップアップは150msかけて表示され、最初のフォーカス可能な要素にフォーカスが移り、Tabキーで内部を循環します。ヘッダー、コンテンツ、フッターの各領域は、モーダルの gap トークンに従って間隔を取ります。
bsui/select は、listbox hidden を含むフォーム内で待機します。トリガーをクリックすると context.open が切り替わり、固定されたビューポート座標で listbox が配置されます。defaultValue="editor" はすでに選択されているため、ポップアップは Editor がトリガーの真上に来るよう配置されます。矢印キー、Home、End、文字入力による検索でアクティブな選択肢を移動できます。Enterキーまたはクリックで選択し、Tabキーや外側のクリックでは選択せずに閉じます。トリガーの表示テキストは data-wp-text="state.displayValue" を通じて更新され、非表示の <input name="role"> は data-wp-bind--value="state.selectedValue" を通じて値を保持します。この値が後でフォームによってシリアライズされます。最上位のモーダルに変形が適用されていないため、これらすべてがダイアログ内に正しく固定されます。
bsui/formが送信を横取りします。フォーム末尾のbsui/buttonは、type属性のない通常のbutton要素を描画するため、HTMLの既定のHTMLによりフォームの送信コントロールになります。Cancelボタンはform要素の外にあるフッターに配置されているため、送信を実行できません。送信時、ストアはフォームのFormDataをシリアライズし、blockで指定されたブロックのデータAPIを通じて送信します。この例では、team/inviteブロックのデータベーススキーマに行を作成します。検証エラーはフィールドごとに返されます。各bsui/fieldはnameを受け取り、無効としてマークされ、フォーカスリングが破壊的な操作を示す色に変わり、メッセージがbsui/field-errorアラートに表示されます。成功すると、data-wp-bind--hiddenを通じてフォーム本文が非表示になり、successMessageが表示されます。
レイヤーは順番に閉じます。 listbox が開いている状態でEscapeキーを押すと、listbox が閉じて select トリガーにフォーカスが戻ります。次にEscapeキーを押すとダイアログが閉じ、Invite teammate にフォーカスが戻ります。dismissable はデフォルトのままなので、backdrop をクリックするとダイアログが閉じます。閉じるとスクロールのロックが解除され、ポップアップはポータルから元のドキュメント上の位置に戻ります。
同じマークアップをファイルベースのページに貼り付けるとネイティブブロックとして同期され、エディターで組み立てた同じ構成はキャンバス上で操作できるプレビューになります。これは、上記のすべての動作が、どちらのコンテキストでも読み込まれるディレクティブとストアに実装されているためです。
こうした境界を支える仕組み
ここで説明した境界は単なる慣例ではなく、このライブラリがどこで描画されても保つ不変条件です。すべてのラベルで同じタイポグラフィが使われ、すべてのモーダルポップアップで同じ表面スタイルが適用されて背後のページが暗くなり、フローティングポップアップはページのスクロール中もトリガーとの位置関係を保ちます。また、Escapeキーを押すと内側から外側へ、一度に1つのレイヤーだけが閉じます。これらの保証は、フロントエンドとエディターキャンバスの両方で、デフォルトのトークンでもテーマのトークンでも有効です。そのため、あるコンテキストで動作する構成は、ほかのコンテキストでも同じように動作します。
ライブの例
このページの構成例が文法にあたるなら、/ui/examples は表現集です。実際に描画される構成例を3段階で紹介しています。2つまたは3つのコンポーネント間の連携を示す組み合わせ、いくつかのコンポーネントで作る見慣れた製品パターン、そして実際の製品での使われ方に沿ってコンポーネントを組み合わせた小さなアプリ一式です。各コンポーネントのページ /ui にも、ラベル付きフィールドからポップオーバー内のカレンダーまで、具体的な使用例を掲載しています。
コンポーネントの基盤となる UI のディレクティブとストアの仕組み、および独自のブロックでの使い方を説明します。