kaze風
CommandPalette
コマンドパレット
プレビュー
コマンドパレットはモーダルオーバーレイとして表示されます。
Cmd+K などのキーボードショートカットで開くのが一般的です。
使いどころ
使う場面
- アプリ内の移動や操作を、キーボードで検索して実行する。操作が多いアプリの上級者向け
- commands に { id, label, group, keywords, onSelect } を渡す。group で見出し付きに分かれ、keywords で別名や英語名でも見つかる
- open と onOpenChange で制御する。開くショートカット（⌘K など）は呼び出し側で用意する
使わない場面
- 初めての利用者が見つける必要のある主要な操作。ふつうの画面上のボタンやメニューにも置く
- 選択肢から値を選ぶこと。Select か Combobox を使う
- フォームの入力やコンテンツの検索。Search を使う
- 操作が 5 個以下のアプリ。Dropdown で足りる
使い方
<CommandPalette
open={isOpen}
onOpenChange={setOpen}
commands={[
{ id: "1", label: "ホーム", onSelect: () => navigate("/") },
{ id: "2", label: "設定", group: "一般", onSelect: () => navigate("/settings") },
]}
/>プロパティ
| 名前 | 型 | デフォルト | 説明 |
|---|---|---|---|
open必須 | boolean | なし | 表示状態 |
onOpenChange必須 | (open: boolean) => void | なし | 表示状態変更時のコールバック |
commands必須 | Command[] | なし | コマンドの配列 { id, label, icon?, group?, onSelect } |
placeholder | string | "コマンドを検索..." | 検索入力のプレースホルダー |
searchLabel | string | なし | Accessible label for the search input (default: "コマンド検索") |
label | string | なし | Accessible label for the dialog (default: "コマンドパレット") |
emptyMessage | string | なし | Message shown when no commands match (default: "該当するコマンドが見つかりません") |
filter | (command: Command, query: string) => boolean | なし | 絞り込みの差し替え。既定は label と keywords を、全角半角・ひらがなカタカナ・大文字小文字を区別せずに照合する |
型と必須かどうかはソースの型定義から自動で生成しています。表にない HTML 標準の属性（className や aria-* など）も、ルート要素にそのまま渡せます。
キーボード操作
| キー | 動作 |
|---|---|
| 文字入力 | label と keywords で絞り込む（全角・半角、ひらがな・カタカナ、大文字・小文字を区別しない） |
| ↓ / ↑ | 候補を次 / 前に移す。端では反対側に回る。フォーカスは入力欄に残る |
| Enter | 選択中のコマンドを実行して閉じる |
| Escape | 閉じる（背後の Dialog などは閉じない） |
| Tab / Shift + Tab | パレット内でフォーカスを回す。外には出ない |
アクセシビリティ
- role="dialog"（aria-modal）の中に、combobox の入力欄と listbox の候補が入る。選択中の候補は aria-activedescendant で伝わる
- 候補にフォーカスは移らず、入力欄に残る。日本語入力の変換中のキーは IME に任せ、パレットは反応しない
- 該当なしのときは emptyMessage が role="status" で伝わる
- dialog の名前は label（既定「コマンドパレット」）。背景は inert にならず、スクロールだけ止まる
文言
- label は動詞を含む操作名か、移動先の名前にする（「プロジェクトを作成」「設定を開く」）
- keywords に略称、英語名、読みを入れて、探す人の言葉で見つかるようにする