组合框 combobox

数据录入组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

过滤由宿主自己算：组件把输入串交给 input-value，筛出哪几条交给 collection 是调用方的事

城市

当前值：（未选）

<script setup lang="ts">
import { computed, ref } from "vue";
import { XhComboboxRoot } from "@xihan-ui/vue";

const cities = [
  { value: "beijing", label: "Beijing 北京" },
  { value: "berlin", label: "Berlin 柏林" },
  { value: "bern", label: "Bern 伯尔尼" },
  { value: "busan", label: "Busan 釜山（禁用）", disabled: true },
  { value: "london", label: "London 伦敦" },
];

const value = ref<string[]>([]);
const query = ref("");
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  return q === "" ? cities : cities.filter((c) => c.label.toLowerCase().includes(q));
});
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    v-model:input-value="query"
    :collection="filtered"
    label="城市"
    empty="无匹配城市"
    open-on-click
    placeholder="输入城市名筛选"
  />
  <p>当前值：{{ value[0] ?? "（未选）" }}</p>
</template>

多选

选完不收起、输入串自动清空，候选立刻回到全集；框里空着时退格删掉最后一个已选项

常去城市

已选：（无）

<script setup lang="ts">
import { computed, ref } from "vue";
import { XhComboboxRoot } from "@xihan-ui/vue";

const cities = [
  { value: "beijing", label: "Beijing 北京" },
  { value: "berlin", label: "Berlin 柏林" },
  { value: "chengdu", label: "Chengdu 成都" },
  { value: "london", label: "London 伦敦" },
];

const value = ref<string[]>([]);
const query = ref("");
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  return q === "" ? cities : cities.filter((c) => c.label.toLowerCase().includes(q));
});
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    v-model:input-value="query"
    :collection="filtered"
    label="常去城市"
    empty="无匹配城市"
    multiple
    placeholder="挑几个城市"
  />
  <p>已选：{{ value.length ? value.join("、") : "（无）" }}</p>
</template>

允许自由文本

allow-custom-value 让没匹配上候选的输入也能落值，适合标签、邮箱这类开放集合

技术栈

当前值：（未选）

<script setup lang="ts">
import { computed, ref } from "vue";
import { XhComboboxRoot } from "@xihan-ui/vue";

const frameworks = [
  { value: "vue", label: "Vue" },
  { value: "react", label: "React" },
  { value: "svelte", label: "Svelte" },
];

const value = ref<string[]>([]);
const query = ref("");
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  return q === "" ? frameworks : frameworks.filter((f) => f.label.toLowerCase().includes(q));
});
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    v-model:input-value="query"
    :collection="filtered"
    label="技术栈"
    empty="没有候选，按 Enter 直接用这串文本"
    allow-custom-value
    placeholder="选一个或直接打字"
  />
  <p>当前值：{{ value[0] ?? "（未选）" }}</p>
</template>

分组

候选分段展示；整段被筛空时连同段标题一起不渲染，列表里不留空壳

城市

当前值：（未选）

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhComboboxClearTrigger,
  XhComboboxContent,
  XhComboboxControl,
  XhComboboxEmpty,
  XhComboboxInput,
  XhComboboxItem,
  XhComboboxItemGroup,
  XhComboboxItemGroupLabel,
  XhComboboxItemIndicator,
  XhComboboxItemText,
  XhComboboxLabel,
  XhComboboxPositioner,
  XhComboboxRoot,
  XhComboboxTrigger,
} from "@xihan-ui/vue";

const groups = [
  {
    value: "asia",
    label: "亚洲",
    items: [
      { value: "beijing", label: "Beijing 北京" },
      { value: "chengdu", label: "Chengdu 成都" },
    ],
  },
  {
    value: "europe",
    label: "欧洲",
    items: [
      { value: "berlin", label: "Berlin 柏林" },
      { value: "london", label: "London 伦敦" },
    ],
  },
];

const value = ref<string[]>([]);
const query = ref("");
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  if (q === "") return groups;
  return groups
    .map((g) => ({ ...g, items: g.items.filter((c) => c.label.toLowerCase().includes(q)) }))
    .filter((g) => g.items.length > 0);
});
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    v-model:input-value="query"
    open-on-click
    placeholder="按大洲分组"
  >
    <XhComboboxLabel>城市</XhComboboxLabel>
    <XhComboboxControl>
      <XhComboboxInput />
      <XhComboboxTrigger>▾</XhComboboxTrigger>
      <XhComboboxClearTrigger>✕</XhComboboxClearTrigger>
    </XhComboboxControl>
    <XhComboboxPositioner>
      <XhComboboxContent>
        <XhComboboxItemGroup v-for="g in filtered" :key="g.value" :value="g.value">
          <XhComboboxItemGroupLabel>{{ g.label }}</XhComboboxItemGroupLabel>
          <XhComboboxItem v-for="c in g.items" :key="c.value" :value="c.value">
            <XhComboboxItemText>{{ c.label }}</XhComboboxItemText>
            <XhComboboxItemIndicator>✓</XhComboboxItemIndicator>
          </XhComboboxItem>
        </XhComboboxItemGroup>
      </XhComboboxContent>
      <XhComboboxEmpty>无匹配城市</XhComboboxEmpty>
    </XhComboboxPositioner>
  </XhComboboxRoot>
  <p>当前值：{{ value[0] ?? "（未选）" }}</p>
</template>

形态

variant 只改输入行的底色与描边用法，取值、过滤与键盘行为都不变

outline

subtle

ghost

<script setup lang="ts">
import { XhComboboxRoot } from "@xihan-ui/vue";

const variants = ["outline", "subtle", "ghost"] as const;

const fruits = [
  { value: "apple", label: "苹果" },
  { value: "banana", label: "香蕉" },
  { value: "cherry", label: "樱桃" },
];
</script>

<template>
  <div style="display: grid; gap: 16px; justify-items: start">
    <XhComboboxRoot
      v-for="v in variants"
      :key="v"
      :variant="v"
      :collection="fruits"
      :label="v"
      open-on-click
      placeholder="选择水果"
      style="width: 240px"
    />
  </div>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 subtle 形态，只看语气这一轴

brand

neutral

success

warning

danger

info

<script setup lang="ts">
import { XhComboboxRoot } from "@xihan-ui/vue";

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;

const fruits = [
  { value: "apple", label: "苹果" },
  { value: "banana", label: "香蕉" },
  { value: "cherry", label: "樱桃" },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <XhComboboxRoot
      v-for="t in tones"
      :key="t"
      variant="subtle"
      :tone="t"
      :collection="fruits"
      :label="t"
      open-on-click
      placeholder="选择水果"
      style="width: 200px"
    />
  </div>
</template>

尺寸

不传 size 即默认档；行高、内边距与字号一起换档，浮层里的候选也跟着变

sm

默认

lg

<script setup lang="ts">
import { XhComboboxRoot } from "@xihan-ui/vue";

const sizes = [
  { size: "sm", label: "sm" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "lg" },
];

const fruits = [
  { value: "apple", label: "苹果" },
  { value: "banana", label: "香蕉" },
  { value: "cherry", label: "樱桃" },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: flex-end; gap: 16px">
    <XhComboboxRoot
      v-for="s in sizes"
      :key="s.label"
      :size="s.size"
      :collection="fruits"
      :label="s.label"
      open-on-click
      placeholder="选择水果"
      style="width: 200px"
    />
  </div>
</template>

受控展开

传了 open 就由宿主说了算：组件只报展开意图，这里满两个字符才真的把浮层放出来

城市

浮层：收起 · 当前值：（未选）

<script setup lang="ts">
import { computed, ref } from "vue";
import { XhComboboxRoot } from "@xihan-ui/vue";

const cities = [
  { value: "beijing", label: "Beijing 北京" },
  { value: "berlin", label: "Berlin 柏林" },
  { value: "bern", label: "Bern 伯尔尼" },
  { value: "london", label: "London 伦敦" },
];

const value = ref<string[]>([]);
const query = ref("");
const wantOpen = ref(false);
// 组件的展开意图与输入长度两个条件都满足才展开
const open = computed(() => wantOpen.value && query.value.trim().length >= 2);
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  return q === "" ? cities : cities.filter((c) => c.label.toLowerCase().includes(q));
});

function onOpenChange(details: { open: boolean }): void {
  wantOpen.value = details.open;
}
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    v-model:input-value="query"
    :collection="filtered"
    :open="open"
    label="城市"
    empty="无匹配城市"
    placeholder="至少输入两个字符"
    @open-change="onOpenChange"
  />
  <p>浮层：{{ open ? "展开" : "收起" }} · 当前值：{{ value[0] ?? "（未选）" }}</p>
</template>

选中后清空输入

选中值一变就把输入串清掉，候选立刻回到全集，接着挑下一个不用先删字

城市

当前值：（未选）

<script setup lang="ts">
import { computed, ref, watch } from "vue";
import { XhComboboxRoot } from "@xihan-ui/vue";

const cities = [
  { value: "beijing", label: "Beijing 北京" },
  { value: "berlin", label: "Berlin 柏林" },
  { value: "chengdu", label: "Chengdu 成都" },
  { value: "london", label: "London 伦敦" },
];

const value = ref<string[]>([]);
const query = ref("");
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  return q === "" ? cities : cities.filter((c) => c.label.toLowerCase().includes(q));
});
const picked = computed(() => cities.find((c) => c.value === value.value[0]) ?? null);

// 输入串受控，选中值一落地就把它清成空串
watch(value, () => {
  query.value = "";
});
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    v-model:input-value="query"
    :collection="filtered"
    label="城市"
    empty="无匹配城市"
    open-on-click
    placeholder="选完接着挑下一个"
  />
  <p>当前值：{{ picked?.label ?? "（未选）" }}</p>
</template>

校验状态

invalid 让输入行报 aria-invalid、描边转告警色；选出值后判定自己撤掉

常驻城市

这一项必填

<script setup lang="ts">
import { computed, ref } from "vue";
import { XhComboboxRoot } from "@xihan-ui/vue";

const cities = [
  { value: "beijing", label: "Beijing 北京" },
  { value: "berlin", label: "Berlin 柏林" },
  { value: "chengdu", label: "Chengdu 成都" },
];

const value = ref<string[]>([]);
const query = ref("");
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  return q === "" ? cities : cities.filter((c) => c.label.toLowerCase().includes(q));
});
// 校验归宿主，组件只负责把这个结论铺成属性
const invalid = computed(() => value.value.length === 0);
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    v-model:input-value="query"
    :collection="filtered"
    :invalid="invalid"
    label="常驻城市"
    empty="无匹配城市"
    open-on-click
    placeholder="必须选一个城市"
  />
  <p v-if="invalid" style="color: var(--xh-fg-danger)">这一项必填</p>
</template>

异步候选

输入串每变一次就重新去远端查一遍，等结果的这段时间候选为空、由空态节点顶上

城市

当前值：（未选）

<script setup lang="ts">
import { ref } from "vue";
import { XhComboboxRoot } from "@xihan-ui/vue";

interface City {
  value: string;
  label: string;
}

const pool: City[] = [
  { value: "beijing", label: "Beijing 北京" },
  { value: "berlin", label: "Berlin 柏林" },
  { value: "bern", label: "Bern 伯尔尼" },
  { value: "chengdu", label: "Chengdu 成都" },
  { value: "london", label: "London 伦敦" },
];

const value = ref<string[]>([]);
const options = ref<City[]>([]);
const loading = ref(false);
let timer = 0;

// 每次输入都重开一轮查询，上一轮未落地的先撤掉
function onSearch(details: { inputValue: string }): void {
  window.clearTimeout(timer);
  const q = details.inputValue.trim().toLowerCase();
  options.value = [];
  if (q === "") {
    loading.value = false;
    return;
  }
  loading.value = true;
  timer = window.setTimeout(() => {
    options.value = pool.filter((c) => c.label.toLowerCase().includes(q));
    loading.value = false;
  }, 600);
}
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    :collection="options"
    label="城市"
    :empty="loading ? '查询中…' : '无匹配城市'"
    placeholder="输入城市名查询"
    @input-value-change="onSearch"
  />
  <p>当前值：{{ value[0] ?? "（未选）" }}</p>
</template>

候选里的自定义内容

条目内容是插槽：主文本之外还能带副标题与标记，过滤与键盘行为一点不变

邮箱

当前值：（未选）

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhBadge,
  XhComboboxClearTrigger,
  XhComboboxContent,
  XhComboboxControl,
  XhComboboxEmpty,
  XhComboboxInput,
  XhComboboxItem,
  XhComboboxItemIndicator,
  XhComboboxItemText,
  XhComboboxLabel,
  XhComboboxPositioner,
  XhComboboxRoot,
  XhComboboxTrigger,
} from "@xihan-ui/vue";

const mailboxes = [
  { value: "gmail", label: "name@gmail.com", note: "国际", tone: "info" },
  { value: "qq", label: "name@qq.com", note: "国内", tone: "success" },
  { value: "163", label: "name@163.com", note: "国内", tone: "success" },
];

const value = ref<string[]>([]);
const query = ref("");
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  return q === "" ? mailboxes : mailboxes.filter((m) => m.label.toLowerCase().includes(q));
});
</script>

<template>
  <XhComboboxRoot
    v-model:value="value"
    v-model:input-value="query"
    open-on-click
    placeholder="输入邮箱前缀"
  >
    <XhComboboxLabel>邮箱</XhComboboxLabel>
    <XhComboboxControl>
      <XhComboboxInput />
      <XhComboboxTrigger>▾</XhComboboxTrigger>
      <XhComboboxClearTrigger>✕</XhComboboxClearTrigger>
    </XhComboboxControl>
    <XhComboboxPositioner>
      <XhComboboxContent>
        <XhComboboxItem v-for="m in filtered" :key="m.value" :value="m.value">
          <XhComboboxItemText>
            <span style="display: inline-flex; align-items: center; gap: 8px">
              {{ m.label }}
              <XhBadge variant="subtle" :tone="m.tone" size="sm">{{ m.note }}</XhBadge>
            </span>
          </XhComboboxItemText>
          <XhComboboxItemIndicator>✓</XhComboboxItemIndicator>
        </XhComboboxItem>
      </XhComboboxContent>
      <XhComboboxEmpty>没有匹配的邮箱</XhComboboxEmpty>
    </XhComboboxPositioner>
  </XhComboboxRoot>
  <p>当前值：{{ value[0] ?? "（未选）" }}</p>
</template>

随表单提交

根插槽把选中值交出来：在根里补一个隐藏输入承接它，值随原生表单一并提交；浮层收起时回车留给表单

常驻城市

表单收到：（还没提交）

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhButton,
  XhComboboxClearTrigger,
  XhComboboxContent,
  XhComboboxControl,
  XhComboboxEmpty,
  XhComboboxInput,
  XhComboboxItem,
  XhComboboxItemIndicator,
  XhComboboxItemText,
  XhComboboxLabel,
  XhComboboxPositioner,
  XhComboboxRoot,
  XhComboboxTrigger,
} from "@xihan-ui/vue";

const cities = [
  { value: "beijing", label: "Beijing 北京" },
  { value: "chengdu", label: "Chengdu 成都" },
  { value: "hangzhou", label: "Hangzhou 杭州" },
];

const value = ref<string[]>([]);
const query = ref("");
const submitted = ref("");
const filtered = computed(() => {
  const q = query.value.trim().toLowerCase();
  return q === "" ? cities : cities.filter((c) => c.label.toLowerCase().includes(q));
});

function onSubmit(event: Event): void {
  const data = new FormData(event.target as HTMLFormElement);
  submitted.value = String(data.get("city") ?? "");
}
</script>

<template>
  <form
    style="display: flex; flex-direction: column; gap: 12px; max-inline-size: 420px"
    @submit.prevent="onSubmit"
  >
    <XhComboboxRoot
      v-slot="{ value: picked }"
      v-model:value="value"
      v-model:input-value="query"
      open-on-click
      placeholder="输入城市名"
    >
      <XhComboboxLabel>常驻城市</XhComboboxLabel>
      <XhComboboxControl>
        <XhComboboxInput />
        <XhComboboxTrigger>▾</XhComboboxTrigger>
        <XhComboboxClearTrigger>✕</XhComboboxClearTrigger>
      </XhComboboxControl>
      <XhComboboxPositioner>
        <XhComboboxContent>
          <XhComboboxItem v-for="c in filtered" :key="c.value" :value="c.value">
            <XhComboboxItemText>{{ c.label }}</XhComboboxItemText>
            <XhComboboxItemIndicator>✓</XhComboboxItemIndicator>
          </XhComboboxItem>
        </XhComboboxContent>
        <XhComboboxEmpty>无匹配城市</XhComboboxEmpty>
      </XhComboboxPositioner>
      <!-- 进表单的出口由作者补：多选时按自己的约定拼串 -->
      <input type="hidden" name="city" :value="picked.join(',')" />
    </XhComboboxRoot>
    <XhButton type="submit" variant="outline" style="align-self: start">提交</XhButton>
    <span>表单收到：{{ submitted || "（还没提交）" }}</span>
  </form>
</template>

多行输入宿主

输入框写 as="textarea" 即换成多行；此时不写 role 与 aria-expanded，textarea 保留它自带的 textbox 角色

回复内容

草稿：（空）

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhComboboxContent,
  XhComboboxControl,
  XhComboboxInput,
  XhComboboxItem,
  XhComboboxItemIndicator,
  XhComboboxItemText,
  XhComboboxLabel,
  XhComboboxPositioner,
  XhComboboxRoot,
  XhComboboxTrigger,
} from "@xihan-ui/vue";

const replies = [
  { value: "received", label: "已收到，稍后处理" },
  { value: "shipping", label: "商品已发出，请注意查收" },
  { value: "refund", label: "退款已提交，三个工作日内到账" },
];

const value = ref<string[]>([]);
const draft = ref("");
const filtered = computed(() => {
  const q = draft.value.trim().toLowerCase();
  return q === "" ? replies : replies.filter((r) => r.label.toLowerCase().includes(q));
});
</script>

<template>
  <XhComboboxRoot v-model:value="value" v-model:input-value="draft" allow-custom-value>
    <XhComboboxLabel>回复内容</XhComboboxLabel>
    <XhComboboxControl>
      <!-- 换标签只此一处；键盘、高亮与选中回填的行为一律不变 -->
      <XhComboboxInput as="textarea" rows="3" placeholder="挑一条常用语，或自己写" />
      <XhComboboxTrigger>▾</XhComboboxTrigger>
    </XhComboboxControl>
    <XhComboboxPositioner>
      <XhComboboxContent>
        <XhComboboxItem v-for="r in filtered" :key="r.value" :value="r.value">
          <XhComboboxItemText>{{ r.label }}</XhComboboxItemText>
          <XhComboboxItemIndicator>✓</XhComboboxItemIndicator>
        </XhComboboxItem>
      </XhComboboxContent>
    </XhComboboxPositioner>
  </XhComboboxRoot>
  <p>草稿：{{ draft || "（空）" }}</p>
</template>

产物

层	值
自定义元素	<xh-combobox>
Vue 组件	XhComboboxClearTrigger XhComboboxContent XhComboboxControl XhComboboxEmpty XhComboboxHiddenInput XhComboboxInput XhComboboxItem XhComboboxItemGroup XhComboboxItemGroupLabel XhComboboxItemIndicator XhComboboxItemText XhComboboxLabel XhComboboxPositioner XhComboboxRoot XhComboboxTrigger
组合式函数	useCombobox
状态机	comboboxMachine
皮肤	@xihan-ui/styles/combobox.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="combobox"：root · label · control · input · trigger · clear-trigger · positioner · content · item · item-text · item-indicator · item-group · item-group-label · empty · hidden-input

Props

属性	类型	必填	说明
collection	ComboboxNode[]		候选数据，显示文本与禁用的事实源。过滤仍归调用方：交进来的就是此刻该显示的那几条。 给了它，条目部件只需报 value，显示文本也不再从活 DOM 现查。 缺省即回到「文本写在条目里、现查 DOM」的老路。
value	string | string[]		选中值。给定即受控：cell 直读 prop，写只发 onValueChange 不落内部值。 单选写成裸串是简写，内部一律归一成数组。
defaultValue	string | string[]
inputValue	string		输入框里的字符串。给定即受控，与选中值各自独立。 过滤不由组件做：调用方拿这个串去筛条目，把筛完的结果重新渲染进来。
defaultInputValue	string
open	boolean		展开态。给定即受控：内部不再自改，只发 onOpenChange。
defaultOpen	boolean
name	string		表单字段名；给了 hidden-input 才带 name 并参与提交。多选按逗号拼成一串。
multiple	boolean
disabled	boolean		整个控件禁用：输入框与两个按钮都用原生 disabled。
readOnly	boolean		只读：文字可选可复制，但展开、选中、清空一概不发生。
invalid	boolean		校验失败：输入框报 aria-invalid，各角色节点带 data-invalid。
loop	boolean		方向键走到尽头是否回绕，默认 true。
placeholder	string		输入框占位文字。
allowCustomValue	boolean		允许提交候选列表里没有的值（回车与失焦时把输入串本身收成选中值）。
openOnClick	boolean		点输入框即展开，默认 false（只有触发按钮与方向键展开）。
inputBehavior	ComboboxInputBehavior		输入行为，默认 none。
placement	Placement
dir	Direction		文字方向，缺省 ltr。只改写浮层在行内轴上 start 与 end 的落点。
offset	number
variant	ControlVariant		形态：outline / subtle / ghost，决定输入行的描边与底色怎么用。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦与选中强调用哪族颜色。
size	Size		尺寸：sm / md / lg，决定输入行高度、内边距与字号档位。
onValueChange	(details: ComboboxValueChangeDetails) => void		value 变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。
onInputValueChange	(details: ComboboxInputValueChangeDetails) => void		输入串变化回调：调用方据此重新过滤候选。
onOpenChange	(details: ComboboxOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。

状态机

状态：open · closed

事件：OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE · ESCAPE · INPUT.CHANGE · INPUT.SET · INPUT.BLUR · ITEM.HIGHLIGHT · ITEM.SELECT · VALUE.COMMIT · VALUE.SET · VALUE.CLEAR · ITEMS.SYNC · FORM.RESET

判据：isOpenControlled · isMultiple · hasHighlight

connect API

useCombobox 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
open	boolean
collection	readonly ComboboxNodeMeta[]	collection 推出的候选元信息，按数据顺序排列；没给 collection 即空数组。
value	string[]	选中集合；单选模式下长度 ≤ 1，形状不随模式变。
inputValue	string	输入框里的字符串。
valueText	string | null	单选选中项的显示文本；无选中或多选时为 null。
highlightedValue	string | null	高亮候选；收起时为 null。焦点不在它身上，只经 aria-activedescendant 上报。
multiple	boolean
disabled	boolean
readOnly	boolean
invalid	boolean
empty	boolean	候选为空（已结算且条数为 0）且当前展开：empty 角色节点据此显形。
canClear	boolean	清空按钮此刻可不可按。
isSelected	(value: string) => boolean
setOpen	(next: boolean) => void
setValue	(next: string[]) => void
setInputValue	(next: string) => void
clear	() => void
getRootProps	() => T['element']
getLabelProps	() => T['label']
getControlProps	() => T['element']
getInputProps	(props?: ComboboxInputProps) => T['input']	不传参即单行 input，产出与加此参数前逐字相同。
getTriggerProps	() => T['button']
getClearTriggerProps	() => T['button']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getItemGroupProps	(props: ComboboxItemGroupProps) => T['element']
getItemGroupLabelProps	(props: ComboboxItemGroupProps) => T['element']
getItemProps	(props: ComboboxItemProps) => T['element']
getItemTextProps	(props: ComboboxItemProps) => T['element']
getItemIndicatorProps	(props: ComboboxItemProps) => T['element']
getEmptyProps	() => T['element']
getHiddenInputProps	() => T['input']	表单影子：选中值随表单提交。给了 name 才带 name，不给就不参与提交。

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowDown	closed, focus in input	展开候选列表并把高亮落到首个可选候选
ArrowUp	closed, focus in input	展开候选列表并把高亮落到末个可选候选
Alt+ArrowDown	closed, focus in input	展开候选列表但不预选任何候选
ArrowDown	open	高亮移到下一个候选（禁用项跳过、尽头按 loop 回绕），焦点不动
ArrowUp	open	高亮移到上一个候选（禁用项跳过、尽头按 loop 回绕），焦点不动
Home	open	高亮移到首个可选候选；收起态不接管，光标照常跳到行首
End	open	高亮移到末个可选候选；收起态不接管，光标照常跳到行尾
Enter	open, 有高亮且未禁用	选中高亮候选：单选把输入串换成它的文本并收起，多选把它并入集合、清空输入串且不收起
Enter	open, 无高亮且 allowCustomValue	把输入串本身收成选中值
Escape	open	先摘掉高亮；高亮已空时才收起列表，选中值不变
Alt+ArrowUp	open	收起列表，选中值不变
Tab / Shift+Tab	open	收起列表且不拦按键，焦点按 Tab 序列自然离开
Backspace	multiple, 输入串为空且已有选中	删掉最后一个已选项
可打印字符	focus in input	改写输入串并展开列表；过滤由调用方按 onInputValueChange 自己做