Combobox 组合框

带建议列表的自动补全输入与命令面板。在指针设备 / 宽屏上锚定在触发器下方（至少与其等宽）；在紧凑触屏上为底部面板。

基础用法

const FRAMEWORKS: SparkSelectOption[] = [
  new SparkSelectOption('next.js', 'Next.js'),
  new SparkSelectOption('sveltekit', 'SvelteKit'),
  ...
];

SCombobox({
  value: this.framework!!,
  options: FRAMEWORKS,
  placeholder: 'Select framework…',
  searchPlaceholder: 'Search framework…',
  emptyText: 'No framework found.'
})

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

长列表

结果是虚拟化的：与查询不匹配的选项从不会被构建，匹配的选项中也只构建可见的行。试试输入 "north 7" 或 "brk"。

// 1 000 options: filtering keeps only the matches, and only the visible
// matches are built (List + Repeat.virtualScroll()). ↑ / ↓ + Enter work from the search field.
SCombobox({
  value: this.place!!,
  options: MANY_PLACES,
  placeholder: 'Select place…',
  searchPlaceholder: 'Search 1 000 places…',
  triggerWidth: 260
})

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

MANY_PLACES.length 个选项 · place = …

API

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

SCombobox

shadcn-vue 的 Combobox（Popover + Command）：显示所选标签并带有 chevrons-up-down 图标的 outline 按钮；打开后是一个可搜索的列表，已选项带有对勾标记。

在指针 / 宽屏上锚定在触发器下方（宽度与触发器相同，至少 200vp）；在紧凑的触控屏上则是底部面板。再次选择当前选项会将其清空（shadcn 行为），除非设置了 deselectable: false。

结果为虚拟化列表（ADR D14：List + Repeat.virtualScroll()）：过滤时会重新计算匹配的行（每次按键为 O(n)，采用 cmdk 评分），只构建可见的行——不匹配的选项根本不会被构建。↑ / ↓ 移动高亮（列表跟随），Enter 选中。

面板令牌（ADR D13/D14）：--combobox-*（background、border-color、radius、border-width、padding、shadow、highlight-background、highlight-foreground、max-height），未设置时回退到共享的 --popover-* 表面；可通过 tokens 按实例设置。

属性	类型	默认值	说明
value!!	string | undefined	undefined
defaultValue	string	''
options	SparkSelectOption[]	[]
placeholder	ResourceStr	$r('app.string.spark_select_option')
searchPlaceholder	ResourceStr	$r('app.string.spark_search_placeholder')
emptyText	ResourceStr	$r('app.string.spark_no_results')
triggerWidth	Length	200	触发器宽度（shadcn 演示为 w-[200px]）；'100%' 表示占满父容器
disabled	boolean	false
deselectable	boolean	true
adaptive	SparkAdaptive SparkAdaptive = 'auto' | 'pointer' | 'touch'	'auto'
tokens	SparkOptionPanelTokens	{}

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