Command 命令菜单

快速、可组合的命令菜单。输入即可过滤（前缀、子串或模糊子序列，以及关键词）；↑ / ↓ 移动高亮，回车选中。

基础用法

SCommand() {
  SCommandInput({ placeholder: 'Type a command or search…' })
  SCommandList() {
    SCommandEmpty({ text: 'No results found.' })
    SCommandGroup({ heading: 'Suggestions' }) {
      SCommandItem({ value: 'calendar', text: 'Calendar', icon: 'calendar' })
      SCommandItem({ value: 'emoji', text: 'Search Emoji', icon: 'sparkles', keywords: ['smile', 'face'] })
      SCommandItem({ value: 'calculator', text: 'Calculator', icon: 'zap', disabled: true })
    }
    SCommandSeparator()
    SCommandGroup({ heading: 'Settings' }) {
      SCommandItem({ value: 'profile', text: 'Profile', icon: 'user', shortcut: '⌘P' })
      SCommandItem({ value: 'settings', text: 'Settings', icon: 'settings', shortcut: '⌘S',
        onSelect: (v: string) => ... })
    }
  }
}

// palette in a dialog
SCommandDialog({ open: this.palette!! }) { SCommandInput() SCommandList() { ... } }

网页近似预览，真机效果以 HarmonyOS 渲染为准。

对话框

SCommandDialog 在居中的对话框中显示命令面板，选择后自动关闭。

SButton({ text: 'Open command palette' }).onClick(() => { this.palette = true; })
SCommandDialog({ open: this.palette!! }) {
  SCommandInput({ placeholder: 'Type a command or search…', autoFocus: true })
  SCommandList() { ... }
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

长列表（数据模式）

传入 items 代替插槽内容：结果列表是虚拟化的，不匹配的项根本不会构建，匹配项中也只构建可见的那些。试试输入 "echo 42"、"set 19" 或 "dlt"。

// 2 000 items: the data mode filters with the same cmdk scoring, keeps document order,
// and renders a List + Repeat.virtualScroll() — non-matching items are never built,
// and of the matches only the rows in view are. ↑ / ↓ + Enter work from the search field.
const COMMANDS: SparkCommandEntryData[] = [
  new SparkCommandEntryData({ value: 'cmd-0', label: 'Alpha file 1', group: 'Files', icon: 'file',
    shortcut: '⌘1', keywords: ['Files'], onSelect: (v: string) => ... }),
  ...
];

SCommand({
  items: COMMANDS,
  placeholder: 'Search 2 000 commands…',
  emptyText: 'No command found.',
  maxListHeight: 300,
  onItemSelect: (v: string) => { this.picked = v; }
})

// also as a palette
SCommandDialog({ open: this.palette!!, items: COMMANDS, onItemSelect: (v: string) => ... })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

MANY_COMMANDS.length 项 · query = "…" · selected = …

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SparkCommandDataList

SCommand({ items }) 的虚拟化结果列表（ADR D14）：List + Repeat(...).virtualScroll()，包含条目 / 分组标题两种模板。 只有可见的行（加上 cachedCount）才会存在；被过滤掉的项根本不在 entries 中。高度是显式的（各行高度之和，上限为 maxListHeight），并通过 childrenMainSize 提供每一行的精确高度，因此 scrollToIndex 无需测量帧节点即可让高亮项保持可见。 行只接收 @Param（复用的行不会在任何地方注册）。

属性	类型	默认值	说明
entries	SparkCommandRow[]	[]
highlighted	string	''
maxListHeight	number	300
rowsFocusable	boolean	false	行可获得键盘焦点（无搜索框）；当输入框持有焦点并驱动高亮时为 false

事件	类型	默认值	说明
onPick	(value: string) => void	() => { }
onHighlight	(value: string) => void	() => { }

SCommand

shadcn-vue Command（cmdk）：可搜索、可用键盘导航的操作列表。

条目按查询词不区分大小写匹配（前缀、子串，然后是子序列——见 sparkCommandScore）；没有匹配项的分组会隐藏；↑ / ↓ 移动高亮，Enter 选中。 结果保持文档顺序（只过滤，不重新排序）。

数据模式（长列表，ADR D14）：传入 items 代替插槽内容。此时 Command 会渲染自带的 搜索框和虚拟化列表（List + Repeat.virtualScroll()）：不匹配查询的项根本不会构建， 匹配项中也只构建可见的行。

相邻且 group 相同的条目共用一个分组标题。在搜索框中按 ↑ / ↓ 移动高亮（列表会滚动到高亮项），Enter 或点按激活条目（先调用条目的 onSelect，再调用 onItemSelect）。value 必须 唯一。showInput: false 会去掉搜索框（此时由行获得焦点）。

属性	类型	默认值	说明
shouldFilter	boolean	true	false：无论查询内容如何都显示每个条目（自行通过 onQueryChange 过滤数据）
items	SparkCommandEntryData[] | undefined	undefined	数据模式：条目（带内置搜索框的虚拟化列表）；undefined 表示插槽模式
placeholder	ResourceStr	$r('app.string.spark_command_placeholder')	数据模式：搜索框占位文字
emptyText	ResourceStr	$r('app.string.spark_no_results')	数据模式：没有匹配项时显示的文字
maxListHeight	number	300	数据模式：结果列表的最大高度（vp）
showInput	boolean	true	数据模式：是否渲染搜索框（false：由行获得焦点，查询词由开发者驱动）
autoFocus	boolean	false	数据模式：Command 出现时让搜索框获得焦点（指针设备；触屏上不弹出键盘）

事件	类型	默认值	说明
onQueryChange	(query: string) => void	() => { }
onItemSelect	(value: string) => void	() => { }	选中任意条目后触发（携带其值）

插槽: 子组件（尾随闭包）

SCommandInput

flex h-9 items-center gap-2 border-b px-3，包含一个搜索图标和无边框的输入框。

属性	类型	默认值	说明
placeholder	ResourceStr	$r('app.string.spark_command_placeholder')
autoFocus	boolean	false	出现时聚焦输入框（指针设备；触控设备上避免使用，以免键盘弹出）

SCommandList

可滚动的结果列表：max-h-[300px] overflow-y-auto。

属性	类型	默认值	说明
maxListHeight	number	300	滚动前的最大高度，单位 vp

插槽: 子组件（尾随闭包）

SCommandEmpty

查询词没有匹配任何条目时显示：py-6 text-center text-sm。

属性	类型	默认值	说明
text	ResourceStr	$r('app.string.spark_no_results')

插槽: 子组件（尾随闭包）

SCommandGroup

overflow-hidden p-1，可选标题使用 px-2 py-1.5 text-xs font-medium text-muted-foreground。

属性	类型	默认值	说明
heading	ResourceStr | undefined	undefined

插槽: 子组件（尾随闭包）

SCommandSeparator

-mx-1 h-px bg-border；搜索时隐藏。

无属性。

SCommandItem

单个结果行：relative flex items-center gap-2 rounded-sm px-2 py-1.5 text-sm，高亮时使用强调色背景（键盘 ↑/↓ 或指针悬停——立即切换，从不交叉淡入）；按下只会让该行变淡（对于选择行，按下的背景与高亮背景并列会显得像两个高亮）。激活通过行本身的原生 onClick 完成——点按、点击、屏幕阅读器、空格键——另外在输入框中按 Enter 也可激活（命令没有输入框时则作用于已聚焦的行）；会触发 onSelect(value)。在条目上链式调用的 .onClick() 不会触发（行自身的点击会接管）。

属性	类型	默认值	说明
value	string	''
text	ResourceStr	''
icon	string | undefined	undefined
shortcut	string | undefined	undefined
keywords	string[]	[]	额外的搜索关键词
disabled	boolean	false
checked	boolean | undefined	undefined	undefined：没有勾选插槽；true / false：显示 / 保留尾部的对勾（Combobox）

事件	类型	默认值	说明
onSelect	(value: string) => void	() => { }

SCommandDialog

shadcn-vue CommandDialog：放在居中对话框中的 Command 命令面板（p-0 overflow-hidden）。

选中条目后会关闭，除非设置 closeOnSelect: false。长命令面板请使用数据模式： SCommandDialog({ open: this.palette!!, items: COMMANDS, autoFocus: true, onItemSelect: ... })。

属性	类型	默认值	说明
open!!	boolean | undefined	undefined
defaultOpen	boolean	false
closeOnSelect	boolean	true
shouldFilter	boolean	true
title	ResourceStr	$r('app.string.spark_command_palette')	无障碍标题（shadcn 将其渲染为仅屏幕阅读器可见）
items	SparkCommandEntryData[] | undefined	undefined	数据模式（见 SCommand）：虚拟化命令面板的条目，代替插槽内容
placeholder	ResourceStr	$r('app.string.spark_command_placeholder')
emptyText	ResourceStr	$r('app.string.spark_no_results')
maxListHeight	number	300
autoFocus	boolean	false	数据模式：打开时让搜索框获得焦点（指针设备）

事件	类型	默认值	说明
onOpenChange	(open: boolean) => void	() => { }
onItemSelect	(value: string) => void	() => { }	选中任意条目后触发（携带其值）

插槽: 子组件（尾随闭包）