导航组件版本 0.1.0

CommandPalette 命令面板

通过键盘优先的搜索界面快速查找并执行应用内命令。

使用概览

适合使用

专业用户频繁跨页面执行命令或打开资源时。

不建议使用

命令很少且可见导航已经足够直接清晰时。

真实示例

正在加载示例…

安装

本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。

pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/command-palette.json

基础用法

导入

import { CommandPalette } from "@richardqiu/quartz/command-palette";

JSX

<CommandPalette aria-label="快速命令" placeholder="搜索命令" emptyText="没有匹配命令" items={[{ id: "new", label: "新建项目", group: "项目" }, { id: "settings", label: "打开设置", group: "导航" }]} />

状态与控制摘要

默认

键盘焦点可见

已选择

空状态

已禁用

label · textactive · boolean

API 参考

属性	类型	默认值	说明
`items`	`readonly CommandPaletteItem[]`	`必填`	提供可搜索命令、分组、关键词与禁用状态。
`onSelect`	`(id: string) => void`	`未设置`	在用户提交可用命令时返回其稳定标识。

组合结构

01CommandPalette

键盘约定

方向键浏览可用结果，Enter 执行当前命令，Escape 清除查询和活动结果。

可访问性契约

由使用方命名组合框，并为每个结果提供稳定命令 ID。
活动结果通过 aria-activedescendant 与 aria-selected 暴露。