コンテンツへスキップ

コンポーネント

Blockstudioは、ビルドごとに59個のUIコンポーネントを提供します。自動的に登録され、デザイントークンでスタイル設定され、ほかのブロックと同じタグ構文で記述されています。

Blockstudio 7.3には、WordPress Interactivity API を基盤とする、ヘッドレスな UI ブロックのセットが同梱されています。これらは bsui/* 名前空間に登録され、テンプレート、ファイルベースのページ、パターン、投稿コンテンツで組み合わせて使用できます。

注

UI コンポーネントは、コンポーネントセットの内容、命名、動作、プロジェクトでの使用パターンについてフィードバックを集めている間、ベータ版として提供されます。7.3で試すことができますが、安定版とされる前に API の仕様が変更される可能性があります。

UI コンポーネントを有効にする

同梱の UI コンポーネントは、初期状態では無効です。テーマの blockstudio.json で有効にできます。

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

または、フィルターを使って有効にします。

PHP
add_filter('blockstudio/settings/ui/enabled', '__return_true');

有効にすると、Blockstudio が includes/ui/blocks の同梱コンポーネントライブラリを登録します。

公開インベントリーと使用例

同梱の実装ブロックは通常の bsui/* 登録のままですが、コンポーネントギャラリーを作成する際は、公開されているファミリー一覧を使用してください。

PHP
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 コンポーネントが実際に使われているときに限り、同梱のグローバルスタイルとスクリプトをそのまま返します。

レンダリング

通常のブロックタグ構文を使います。

HTML
<block name="bsui/button" label="Save" variant="default"></block>

短い <bs:> 構文も使えます。

HTML
<bs:bsui-button label="Save" variant="default" />

Blockstudio テンプレートでは、ブロックタグが自動的に描画されます。ファイルベースのページとパターンでは、ネイティブな WordPress ブロックとして同期されます。投稿コンテンツやウィジェット領域から UI コンポーネントを直接描画するには、ページ単位のブロックタグを有効にします。

JSON
{
  "ui": {
    "enabled": true
  },
  "blockTags": {
    "enabled": true,
    "allow": ["bsui/*", "app/*"]
  }
}

基本コンポーネント

シンプルなコンポーネントは、単一のブロックとして描画されます。

HTML
<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 をサポートしています。

PHP
bs_render_block([
  'name' => 'bsui/button',
  'data' => [
    'label' => 'Continue',
    'icon' => [
      'set' => 'heroicons',
      'subSet' => 'outline',
      'icon' => 'arrow-right',
    ],
    'iconPosition' => 'right',
  ],
]);

複合コンポーネント

多くの UI コンポーネントは、複数のブロックで構成されます。ルートブロックが状態を管理し、子ブロックで親を宣言します。

タブ

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

ダイアログ

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

選択

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

フォームフィールド

HTML
<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 から上書きできます。

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 を使わずにコンポーネントのルールを上書きできます。

CSS
.button-brand {
  background: var(--brand-primary);
}

カスタム bsui/button バリアントを追加するには、既存の属性フィルターで select オプションを追加し、blockstudio/ui/button/variants-style を使ってバリアントの CSS を指定します。

PHP
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;
}';
});

すべてのコンポーネント

アコーディオン 一度に1つのパネルが開く、縦に並んだセクション。 アラートダイアログ 操作を中断し、回答するまで閉じられないモーダル。 アスペクト比 コンテンツを固定の幅と高さの比率に保ちます。 アバター 読み込みに失敗すると、イニシャルに切り替わるユーザー画像。 バッジ ステータス、件数、カテゴリを示す小さなラベル。 パンくずリスト 階層の中で現在のページの位置を示します。 ボタン アクションを実行するボタン。強調度の異なるバリアントを選べます。 ボタングループ 関連するボタンを1つのセグメントコントロールにまとめます。 カレンダー 日付を1日選ぶためのカレンダーグリッド。 カード ヘッダー、本文、フッターをまとめるサーフェス。 カルーセル キーボード操作に対応した、スワイプ可能なスライドのトラック。 チェックボックス 二者択一の選択肢で、不確定状態にも対応します。 折りたたみ コンテンツ領域を1つ折りたたんだり、展開したりします。 カラーピッカー 色を選び、周囲のフォームとともに送信します。 コンボボックス 入力に合わせて選択肢の一覧を絞り込むテキスト入力欄。 コンテキストメニュー 右クリックした位置に表示されるアクション。 日付入力欄 ピッカーを使わずに日付を入力するためのマスク付きフィールド。 ダイアログ 集中して行うタスクや確認に使うモーダルレイヤー。 ドロワー 画面のどの端からでもスライドして現れるパネル。 フィールド ラベル、説明、エラーと1つのコントロールをまとめます。 フィールドグループ 関連するフィールドを共通の見出しの下にまとめます。 ファイルアップロード 複数ファイルに対応したドロップゾーンとファイル選択機能。 フォーム ページを再読み込みせずにフィールドを送信し、成功を知らせます。 入力 一般的な入力タイプに対応する1行テキストフィールド。 キーボードショートカット キーボードショートカットをキーキャップ内に表示します。 ラベル ラベル付きコンポーネントで共用する、コントロールのキャプション。 メニュー トリガーに固定された、アクションのドロップダウンリスト。 メニューバー デスクトップアプリのような、メニューの横並びバー。 メーター 既知の範囲内で測定値を示します。 ナビゲーションメニュー 入れ子リンクとホバーパネルを備えたサイトナビゲーション。 数値フィールド ステッパーと範囲制限に対応した数値入力欄。 OTP入力 ワンタイムパスコードを入力するための分割ボックス。 ページネーション 前後のページへのリンクと省略表示を備えたページリンク。 パスワード入力 表示切り替え機能付きのパスワードフィールド。 電話番号入力 国の選択と書式設定に対応した電話番号フィールド。 ポップオーバー トリガーに固定され、外側をクリックすると閉じるリッチコンテンツ。 プレビューカード リンク先をプレビューするホバーカード。 進捗 タスクの進捗状況を示します。 ラジオボタングループ 選択肢の中から1つだけ選べるセット。 評価 スコアを記録するための星評価コントロール。 スクロール領域 スタイル付きのオーバーレイスクロールバーを備えたスクロールコンテナー。 選択 選択肢の一覧から選ぶドロップダウン。 区切り線 コンテンツやコントロールのグループを区切る線。 スケルトン コンテンツの読み込み中に表示するプレースホルダーの形状。 スライダー トラック上をドラッグして値または範囲を選びます。 スペース スペーシングスケールに基づく、縦方向のリズムを刻む固定ステップ。 スピナー 所要時間が分からない進行中の作業を示します。 スタック 一定の間隔を保ちながら、子要素を行または列に配置します。 スイッチ 設定を切り替え、変更をすぐに適用します。 テーブル 並べ替えと縞模様に対応した表形式のデータ。 タブ 同じ領域を占めるパネルを切り替えます。 Text 指定したサイズとセマンティックタグで文章を表示します。 テキストエリア 行数に合わせて高さが変わる複数行テキストフィールド。 タイムピッカー 指定した刻み幅で時刻を選びます。 トーストプロバイダー 画面の隅に一時的な通知を表示します。 切り替え 押された状態を維持し、オンを表すボタン。 トグルグループ 単一選択または複数選択として機能するトグルのセット。 ツールバー コントロール間をフォーカスが移動する一列のコントロール。 ツールチップ ホバー時またはフォーカス時に表示される短いヒント。