コンポーネント
Blockstudioは、ビルドごとに59個のUIコンポーネントを提供します。自動的に登録され、デザイントークンでスタイル設定され、ほかのブロックと同じタグ構文で記述されています。
Blockstudio 7.3には、WordPress Interactivity API を基盤とする、ヘッドレスな UI ブロックのセットが同梱されています。これらは bsui/* 名前空間に登録され、テンプレート、ファイルベースのページ、パターン、投稿コンテンツで組み合わせて使用できます。
注
UI コンポーネントは、コンポーネントセットの内容、命名、動作、プロジェクトでの使用パターンについてフィードバックを集めている間、ベータ版として提供されます。7.3で試すことができますが、安定版とされる前に API の仕様が変更される可能性があります。
UI コンポーネントを有効にする
同梱の UI コンポーネントは、初期状態では無効です。テーマの blockstudio.json で有効にできます。
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
または、フィルターを使って有効にします。
add_filter('blockstudio/settings/ui/enabled', '__return_true');
有効にすると、Blockstudio が includes/ui/blocks の同梱コンポーネントライブラリを登録します。
公開インベントリーと使用例
同梱の実装ブロックは通常の bsui/* 登録のままですが、コンポーネントギャラリーを作成する際は、公開されているファミリー一覧を使用してください。
use Blockstudio\Ui;
$families = Ui::inventory();
$examples = Ui::examples();
Ui::inventory() は、すべての複合コンポーネントを公開ルートごとにまとめ、そのファミリーに必要な実装登録を一覧表示します。Ui::examples() は、デフォルト値と例示用データを含む、正規化された決定的な宣言を追加します。必須のルートと子の関係を保持するため、そのまま Blockstudio\Render::document() に渡せます。
公開 Canvas インベントリーでは、これらの例を ui 型で公開し、通常の blocks 型から同梱の実装登録を除外します。これにより、内部のルート、トリガー、ポップアップ、レイヤーの断片を並べたギャラリーではなく、公開コンポーネントの各ファミリーにつき1つの完全な例を表示できます。
すでに描画されたドキュメントを組み立てる場合、Ui::global_assets($block_names, $html) は選択した出力で UI コンポーネントが実際に使われているときに限り、同梱のグローバルスタイルとスクリプトをそのまま返します。
レンダリング
通常のブロックタグ構文を使います。
<block name="bsui/button" label="Save" variant="default"></block>
短い <bs:> 構文も使えます。
<bs:bsui-button label="Save" variant="default" />
Blockstudio テンプレートでは、ブロックタグが自動的に描画されます。ファイルベースのページとパターンでは、ネイティブな WordPress ブロックとして同期されます。投稿コンテンツやウィジェット領域から UI コンポーネントを直接描画するには、ページ単位のブロックタグを有効にします。
{
"ui": {
"enabled": true
},
"blockTags": {
"enabled": true,
"allow": ["bsui/*", "app/*"]
}
}
基本コンポーネント
シンプルなコンポーネントは、単一のブロックとして描画されます。
<block name="bsui/button" label="Continue" variant="default"></block>
<block name="bsui/badge" label="Beta"></block>
<block
name="bsui/input"
nameAlt="email"
type="email"
placeholder="Email"
></block>
<block name="bsui/textarea" name="message" placeholder="Message"></block>
<block name="bsui/spinner"></block>
属性は各コンポーネントの block.json 属性に直接対応します。たとえば bsui/button は label、icon、iconPosition、href、variant、size、disabled をサポートしています。
bs_render_block([
'name' => 'bsui/button',
'data' => [
'label' => 'Continue',
'icon' => [
'set' => 'heroicons',
'subSet' => 'outline',
'icon' => 'arrow-right',
],
'iconPosition' => 'right',
],
]);
複合コンポーネント
多くの UI コンポーネントは、複数のブロックで構成されます。ルートブロックが状態を管理し、子ブロックで親を宣言します。
タブ
<block name="bsui/tabs" defaultValue="tab1">
<block name="bsui/tabs-list">
<block name="bsui/tabs-trigger" value="tab1" title="Features"></block>
<block name="bsui/tabs-trigger" value="tab2" title="Pricing"></block>
<block name="bsui/tabs-trigger" value="tab3" title="FAQ"></block>
</block>
<block name="bsui/tabs-panel" value="tab1">
<p>Features content.</p>
</block>
<block name="bsui/tabs-panel" value="tab2">
<p>Pricing content.</p>
</block>
<block name="bsui/tabs-panel" value="tab3">
<p>FAQ content.</p>
</block>
</block>
ダイアログ
<block name="bsui/dialog">
<block name="bsui/dialog-trigger" label="Open Dialog"></block>
<block name="bsui/dialog-backdrop"></block>
<block name="bsui/dialog-popup">
<p>Dialog content.</p>
<block name="bsui/dialog-close" label="Close"></block>
</block>
</block>
選択
<block name="bsui/select" placeholder="Choose a fruit" nameAlt="fruit">
<block name="bsui/select-trigger"></block>
<block name="bsui/select-popup">
<block name="bsui/select-option" value="apple" label="Apple"></block>
<block name="bsui/select-option" value="banana" label="Banana"></block>
<block name="bsui/select-option" value="cherry" label="Cherry"></block>
</block>
</block>
フォームフィールド
<block name="bsui/form" block="contact/form" successMessage="Thank you!">
<block name="bsui/field">
<block name="bsui/field-label" text="Email"></block>
<block name="bsui/input" nameAlt="email" type="email"></block>
<block name="bsui/field-error"></block>
</block>
</block>
利用可能なブロック
同梱の UI ライブラリには、次のブロックがあります。
| 領域 | ブロック |
|---|---|
| レイアウト | bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table |
| アクション | bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar |
| 入力 | bsui/checkbox, bsui/color-picker, bsui/date-input, bsui/file-upload, bsui/input, bsui/number-field, bsui/otp-input, bsui/password-input, bsui/phone-input, bsui/radio-group, bsui/rating, bsui/select, bsui/slider, bsui/switch, bsui/textarea, bsui/time-picker |
| オーバーレイ | bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip |
| ナビゲーション | bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs |
| フィードバック | bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast |
| フォーム | bsui/field, bsui/field-group, bsui/form |
複合コンポーネントには、bsui/dialog-trigger、bsui/dialog-popup、bsui/tabs-list、bsui/tabs-trigger、bsui/tabs-panel、bsui/select-trigger、bsui/select-popup、bsui/select-option などの子ブロックもあります。
スタイル設定
UI コンポーネントには、--bs-ui-* プレフィックスを使った独自の CSS カスタムプロパティが付属します。テーマの CSS から上書きできます。
:root {
--bs-ui-radius: 0.5rem;
--bs-ui-primary: oklch(0.45 0.18 260);
--bs-ui-primary-foreground: white;
}
コンポーネントの動作はヘッドレスですが、初期状態でも使いやすいよう、一定の設計方針が反映されています。まずトークンを上書きし、必要に応じてコンポーネント固有の CSS を追加してください。
同梱コンポーネントの CSS は、名前付きの bsui カスケードレイヤーに出力されます。レイヤーに属さないテーマの CSS は、!important を使わずにコンポーネントのルールを上書きできます。
.button-brand {
background: var(--brand-primary);
}
カスタム bsui/button バリアントを追加するには、既存の属性フィルターで select オプションを追加し、blockstudio/ui/button/variants-style を使ってバリアントの CSS を指定します。
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
if (($block['name'] ?? '') === 'bsui/button' && ($attribute['id'] ?? '') === 'variant') {
$attribute['options'][] = [
'label' => 'Brand',
'value' => 'brand',
];
}
return $attribute;
}, 10, 2);
add_filter('blockstudio/ui/button/variants-style', function($css) {
return $css . '
[data-bsui-button][data-variant="brand"] {
background: var(--brand-primary);
color: white;
}';
});
関連情報
- UI構成(制御フィールド、フィールドカード、ツールバーの区切り線を含む)
- プログラムによるレンダリング
- コンポーネント
- インタラクティビティ API