选择器 select

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

示例

基础用法

collection 是条目的事实源：显示文本与禁用都写在数据里，结构由组件铺开

水果

当前值：（未选）

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

const fruit = ref<string[]>([]);
const fruits = [
  { value: "apple", label: "苹果" },
  { value: "banana", label: "香蕉" },
  { value: "blueberry", label: "蓝莓" },
  { value: "cherry", label: "樱桃（缺货）", disabled: true },
  { value: "durian", label: "榴莲" },
];
</script>

<template>
  <XhSelectRoot v-model:value="fruit" :collection="fruits" label="水果" placeholder="请选择" />
  <p>当前值：{{ fruit.length ? fruit.join("、") : "（未选）" }}</p>
</template>

多选

multiple 下点中即在集合里增删该项、浮层不收起，触发器上的文本把选中项连起来

苹果水果（多选）

已选：apple

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

const picked = ref<string[]>(["apple"]);
const fruits = [
  { value: "apple", label: "苹果" },
  { value: "banana", label: "香蕉" },
  { value: "blueberry", label: "蓝莓" },
  { value: "durian", label: "榴莲" },
];
</script>

<template>
  <XhSelectRoot
    v-model:value="picked"
    :collection="fruits"
    multiple
    label="水果（多选）"
    placeholder="请选择"
  />
  <p>已选：{{ picked.length ? picked.join("、") : "（无）" }}</p>
</template>

受控

传了 value 就由宿主说了算：组件只发 value-change，宿主写回它才变，这里把樱桃挡在门外

banana水果

宿主持有的值：banana

<script setup lang="ts">
import { ref } from "vue";
import {
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

const value = ref<string[]>(["banana"]);
const rejected = ref(false);
const fruits = [
  { value: "apple", label: "苹果" },
  { value: "banana", label: "香蕉" },
  { value: "cherry", label: "樱桃（选不中）" },
];

// 只有通过校验的值才写回，未写回则界面停在原值
function onValueChange(details: { value: string[] }) {
  rejected.value = details.value.includes("cherry");
  if (!rejected.value) value.value = details.value;
}
</script>

<template>
  <XhSelectRoot :value="value" placeholder="请选择" @value-change="onValueChange">
    <XhSelectLabel>水果</XhSelectLabel>
    <XhSelectTrigger>
      <XhSelectValueText />
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent>
        <XhSelectItem v-for="f in fruits" :key="f.value" :value="f.value">
          <XhSelectItemText>{{ f.label }}</XhSelectItemText>
          <XhSelectItemIndicator>✓</XhSelectItemIndicator>
        </XhSelectItem>
      </XhSelectContent>
    </XhSelectPositioner>
  </XhSelectRoot>
  <p>宿主持有的值：{{ value.join("、") }}{{ rejected ? " · 上一次选择被拒绝" : "" }}</p>
</template>

禁用

根部件的 disabled 把触发器转成原生 disabled，浮层展不开、也不占 Tab 位

苹果水果

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

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

<template>
  <XhSelectRoot
    :collection="fruits"
    :default-value="['apple']"
    disabled
    label="水果"
    placeholder="请选择"
  />
</template>

形态

variant 只改触发器的颜色槽位，浮层与键盘行为三档一致

苹果outline

苹果subtle

苹果ghost

<script setup lang="ts">
import { XhSelectRoot } 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: flex; flex-wrap: wrap; gap: 16px">
    <XhSelectRoot
      v-for="v in variants"
      :key="v"
      :variant="v"
      :collection="fruits"
      :default-value="['apple']"
      :label="v"
      placeholder="请选择"
    />
  </div>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 outline 只看语气的差别

苹果brand

苹果neutral

苹果success

苹果warning

苹果danger

苹果info

<script setup lang="ts">
import { XhSelectRoot } 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">
    <XhSelectRoot
      v-for="t in tones"
      :key="t"
      variant="outline"
      :tone="t"
      :collection="fruits"
      :default-value="['apple']"
      :label="t"
      placeholder="请选择"
    />
  </div>
</template>

尺寸

触发器与浮层条目一起换档，不传 size 即默认档

苹果小

苹果默认

苹果大

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

// 中间一档不写 size，用 undefined 表达
const sizes = [
  { size: "sm", label: "小" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "大" },
] as const;
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">
    <XhSelectRoot
      v-for="s in sizes"
      :key="s.label"
      :size="s.size"
      :collection="fruits"
      :default-value="['apple']"
      :label="s.label"
      placeholder="请选择"
    />
  </div>
</template>

异步加载选项

首次展开才去取数据：open-change 报出展开意图，数据到达前用一条禁用条目占位

曲目

当前值：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

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

const value = ref<string[]>([]);
const songs = ref<Song[]>([]);
const loading = ref(false);
let requested = false;

// 展开一次即发起请求，拿到数据后不再重复取
function onOpenChange(details: { open: boolean }): void {
  if (!details.open || requested) return;
  requested = true;
  loading.value = true;
  window.setTimeout(() => {
    songs.value = [
      { value: "song1", label: "起风了" },
      { value: "song2", label: "夜空中最亮的星" },
      { value: "song3", label: "海阔天空" },
      { value: "song4", label: "晴天" },
    ];
    loading.value = false;
  }, 800);
}
</script>

<template>
  <XhSelectRoot v-model:value="value" placeholder="请选择" @open-change="onOpenChange">
    <XhSelectLabel>曲目</XhSelectLabel>
    <XhSelectTrigger>
      <XhSelectValueText />
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent>
        <XhSelectItem v-if="loading" value="loading" disabled>
          <XhSelectItemText>加载中…</XhSelectItemText>
        </XhSelectItem>
        <XhSelectItem v-for="s in songs" :key="s.value" :value="s.value">
          <XhSelectItemText>{{ s.label }}</XhSelectItemText>
          <XhSelectItemIndicator>✓</XhSelectItemIndicator>
        </XhSelectItem>
      </XhSelectContent>
    </XhSelectPositioner>
  </XhSelectRoot>
  <p>当前值：{{ value[0] ?? "（未选）" }}</p>
</template>

宽度

触发器与浮层各有自己的宽度槽位，写在根部件上即可；装不下的文本在行内以省略号收口

long缺省宽度

long加宽

<script setup lang="ts">
import {
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

const plans = [
  { value: "basic", label: "基础版" },
  { value: "pro", label: "专业版" },
  { value: "long", label: "旗舰版 · 含无限席位与专属客户成功经理的年度合约" },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <XhSelectRoot :default-value="['long']" placeholder="请选择">
      <XhSelectLabel>缺省宽度</XhSelectLabel>
      <XhSelectTrigger>
        <XhSelectValueText />
        <XhSelectIndicator>▾</XhSelectIndicator>
      </XhSelectTrigger>
      <XhSelectPositioner>
        <XhSelectContent>
          <XhSelectItem v-for="p in plans" :key="p.value" :value="p.value">
            <XhSelectItemText>{{ p.label }}</XhSelectItemText>
            <XhSelectItemIndicator>✓</XhSelectItemIndicator>
          </XhSelectItem>
        </XhSelectContent>
      </XhSelectPositioner>
    </XhSelectRoot>

    <XhSelectRoot
      :default-value="['long']"
      placeholder="请选择"
      style="--xh-select-trigger-min-w: 15rem; --xh-select-content-min-w: 22rem"
    >
      <XhSelectLabel>加宽</XhSelectLabel>
      <XhSelectTrigger>
        <XhSelectValueText />
        <XhSelectIndicator>▾</XhSelectIndicator>
      </XhSelectTrigger>
      <XhSelectPositioner>
        <XhSelectContent>
          <XhSelectItem v-for="p in plans" :key="p.value" :value="p.value">
            <XhSelectItemText>{{ p.label }}</XhSelectItemText>
            <XhSelectItemIndicator>✓</XhSelectItemIndicator>
          </XhSelectItem>
        </XhSelectContent>
      </XhSelectPositioner>
    </XhSelectRoot>
  </div>
</template>

选项里的自定义内容

条目与触发器显示都是插槽：内容想写什么写什么，选中与键盘行为不变

liuyi负责人

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhAvatarFallback,
  XhAvatarImage,
  XhAvatarRoot,
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

const members = [
  { value: "liuyi", name: "刘一", initial: "刘", team: "设计组" },
  { value: "chener", name: "陈二", initial: "陈", team: "前端组" },
  { value: "zhangsan", name: "张三", initial: "张", team: "服务端组" },
];

const picked = ref<string[]>(["liuyi"]);
const current = computed(() => members.find((m) => m.value === picked.value[0]) ?? null);
</script>

<template>
  <XhSelectRoot v-model:value="picked" placeholder="请选择成员">
    <XhSelectLabel>负责人</XhSelectLabel>
    <XhSelectTrigger>
      <XhSelectValueText>
        <span v-if="current" style="display: inline-flex; align-items: center; gap: 8px">
          <XhAvatarRoot size="sm">
            <XhAvatarImage />
            <XhAvatarFallback>{{ current.initial }}</XhAvatarFallback>
          </XhAvatarRoot>
          {{ current.name }}
        </span>
        <span v-else>请选择成员</span>
      </XhSelectValueText>
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent>
        <XhSelectItem v-for="m in members" :key="m.value" :value="m.value">
          <XhSelectItemText>
            <span style="display: inline-flex; align-items: center; gap: 8px">
              <XhAvatarRoot size="sm">
                <XhAvatarImage />
                <XhAvatarFallback>{{ m.initial }}</XhAvatarFallback>
              </XhAvatarRoot>
              <span>
                {{ m.name }}
                <span style="color: var(--xh-fg-muted); font-size: 12px">{{ m.team }}</span>
              </span>
            </span>
          </XhSelectItemText>
          <XhSelectItemIndicator>✓</XhSelectItemIndicator>
        </XhSelectItem>
      </XhSelectContent>
    </XhSelectPositioner>
  </XhSelectRoot>
</template>

插槽里的操作入口

根部件把 open、value 与 setOpen、setValue 交给插槽，浮层之外的按钮据此展开或清空

水果

当前值：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

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

<template>
  <XhSelectRoot
    v-slot="{ open, value, setOpen, setValue }"
    v-model:value="picked"
    placeholder="请选择"
  >
    <XhSelectLabel>水果</XhSelectLabel>
    <XhSelectTrigger>
      <XhSelectValueText />
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent>
        <XhSelectItem v-for="f in fruits" :key="f.value" :value="f.value">
          <XhSelectItemText>{{ f.label }}</XhSelectItemText>
          <XhSelectItemIndicator>✓</XhSelectItemIndicator>
        </XhSelectItem>
      </XhSelectContent>
    </XhSelectPositioner>
    <div style="display: flex; gap: 8px; margin-block-start: 8px">
      <XhButton variant="outline" size="sm" @click="setOpen(!open)">
        {{ open ? "收起" : "展开" }}
      </XhButton>
      <XhButton variant="ghost" size="sm" :disabled="value.length === 0" @click="setValue([])">
        清空
      </XhButton>
    </div>
  </XhSelectRoot>
  <p>当前值：{{ picked[0] ?? "（未选）" }}</p>
</template>

大量选项

浮层高度封顶后自行滚动；敲首字母连打检索直接跳到该字母开头的条目，方向键照常可用

仓位

当前值：（未选）

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

const letters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
// 26 个字母各四条，首字母连打即可在段间跳转
const options = Array.from({ length: 104 }, (_, i) => {
  const letter = letters[i % 26];
  const seq = Math.floor(i / 26) + 1;
  return { value: `${letter}${seq}`, label: `${letter} 区 ${seq} 号仓` };
});

const picked = ref<string[]>([]);
</script>

<template>
  <XhSelectRoot
    v-model:value="picked"
    :collection="options"
    label="仓位"
    placeholder="敲 M 试试"
  />
  <p>当前值：{{ picked[0] ?? "（未选）" }}</p>
</template>

分组

条目分段展示：段落壳与段标题由作者写，条目照旧归到同一份集合，方向键与连打检索跨段贯通

食材

当前值：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

const groups = [
  {
    id: "select-group-fruit",
    label: "水果",
    items: [
      { value: "apple", label: "苹果" },
      { value: "banana", label: "香蕉" },
    ],
  },
  {
    id: "select-group-vegetable",
    label: "蔬菜",
    items: [
      { value: "carrot", label: "胡萝卜" },
      { value: "celery", label: "芹菜" },
    ],
  },
];

const picked = ref<string[]>([]);
</script>

<template>
  <XhSelectRoot v-model:value="picked" placeholder="请选择">
    <XhSelectLabel>食材</XhSelectLabel>
    <XhSelectTrigger>
      <XhSelectValueText />
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent>
        <!-- 段标题只是普通节点，不带条目标记，导航与检索都跳过它 -->
        <div v-for="g in groups" :key="g.id" role="group" :aria-labelledby="g.id">
          <div :id="g.id" style="padding: 4px 8px; color: var(--xh-fg-subtle); font-size: 12px">
            {{ g.label }}
          </div>
          <XhSelectItem v-for="o in g.items" :key="o.value" :value="o.value">
            <XhSelectItemText>{{ o.label }}</XhSelectItemText>
            <XhSelectItemIndicator>✓</XhSelectItemIndicator>
          </XhSelectItem>
        </div>
      </XhSelectContent>
    </XhSelectPositioner>
  </XhSelectRoot>
  <p>当前值：{{ picked[0] ?? "（未选）" }}</p>
</template>

多选标签

触发器的显示是插槽：只摆前两个标签、其余折成 +N；可删除的标签行放在触发器之外，删除按钮调根插槽的 setValue

vuesveltesolid技术栈

Vue Svelte Solid

<script setup lang="ts">
import { ref } from "vue";
import {
  XhBadge,
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

const options = [
  { value: "vue", label: "Vue" },
  { value: "svelte", label: "Svelte" },
  { value: "solid", label: "Solid" },
  { value: "lit", label: "Lit" },
  { value: "preact", label: "Preact" },
];

const picked = ref<string[]>(["vue", "svelte", "solid"]);

function labelOf(value: string): string {
  return options.find((o) => o.value === value)?.label ?? value;
}
</script>

<template>
  <XhSelectRoot
    v-slot="{ value, setValue }"
    v-model:value="picked"
    multiple
    placeholder="请选择"
  >
    <XhSelectLabel>技术栈</XhSelectLabel>
    <XhSelectTrigger>
      <XhSelectValueText>
        <span v-if="value.length === 0" style="color: var(--xh-fg-subtle)">请选择</span>
        <span v-else style="display: inline-flex; align-items: center; gap: 4px">
          <XhBadge v-for="v in value.slice(0, 2)" :key="v" variant="subtle" size="sm">
            {{ labelOf(v) }}
          </XhBadge>
          <span v-if="value.length > 2" style="color: var(--xh-fg-muted); font-size: 12px">
            +{{ value.length - 2 }}
          </span>
        </span>
      </XhSelectValueText>
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent>
        <XhSelectItem v-for="o in options" :key="o.value" :value="o.value">
          <XhSelectItemText>{{ o.label }}</XhSelectItemText>
          <XhSelectItemIndicator>✓</XhSelectItemIndicator>
        </XhSelectItem>
      </XhSelectContent>
    </XhSelectPositioner>
    <!-- 可删除的标签行放在触发器之外，删掉一项即把它从集合里摘掉 -->
    <div
      v-if="value.length > 0"
      style="display: flex; flex-wrap: wrap; gap: 6px; margin-block-start: 8px"
    >
      <span
        v-for="v in value"
        :key="v"
        style="
          display: inline-flex;
          align-items: center;
          gap: 4px;
          padding: 2px 6px;
          border-radius: var(--xh-shape-control);
          background: var(--xh-bg-subtle);
          font-size: 12px;
        "
      >
        {{ labelOf(v) }}
        <button
          type="button"
          :aria-label="`移除 ${labelOf(v)}`"
          style="border: 0; background: none; color: var(--xh-fg-muted); cursor: pointer"
          @click="setValue(value.filter((x: string) => x !== v))"
        >
          ✕
        </button>
      </span>
    </div>
  </XhSelectRoot>
</template>

校验状态

校验结论由宿主给出：告警描边写进触发器的使用者令牌，错误文案用 aria-describedby 挂到触发器上

所属部门

这一项必填

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

const departments = [
  { value: "design", label: "设计组" },
  { value: "frontend", label: "前端组" },
  { value: "server", label: "服务端组" },
];

const picked = ref<string[]>([]);
const invalid = computed(() => picked.value.length === 0);

// 描边与它的悬停档一起换成告警色，其余槽位不动
const invalidStyle = computed(() =>
  invalid.value
    ? {
        "--xh-select-trigger-border": "var(--xh-color-danger-500)",
        "--xh-select-trigger-border-hover": "var(--xh-color-danger-500)",
      }
    : undefined,
);
</script>

<template>
  <XhSelectRoot v-model:value="picked" placeholder="必须选一个">
    <XhSelectLabel>所属部门</XhSelectLabel>
    <XhSelectTrigger
      :style="invalidStyle"
      :aria-describedby="invalid ? 'select-invalid-tip' : undefined"
    >
      <XhSelectValueText />
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent>
        <XhSelectItem v-for="d in departments" :key="d.value" :value="d.value">
          <XhSelectItemText>{{ d.label }}</XhSelectItemText>
          <XhSelectItemIndicator>✓</XhSelectItemIndicator>
        </XhSelectItem>
      </XhSelectContent>
    </XhSelectPositioner>
  </XhSelectRoot>
  <p v-if="invalid" id="select-invalid-tip" style="color: var(--xh-fg-danger)">这一项必填</p>
</template>

滚动加载

浮层的滚动容器就是 content：@scroll 直接落在它身上，滚到底就把下一页并进选项

工单

已加载 20 / 80 条

<script setup lang="ts">
import { ref } from "vue";
import {
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

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

const PAGE_SIZE = 20;
const TOTAL = 80;

function makePage(from: number): Ticket[] {
  return Array.from({ length: PAGE_SIZE }, (_, i) => ({
    value: `no-${from + i + 1}`,
    label: `第 ${from + i + 1} 号工单`,
  }));
}

const tickets = ref<Ticket[]>(makePage(0));
const loading = ref(false);
const picked = ref<string[]>([]);

// 距底不足 8px 视为触底，取下一页
function onScroll(event: Event): void {
  const el = event.target as HTMLElement;
  if (loading.value || tickets.value.length >= TOTAL) return;
  if (el.scrollTop + el.clientHeight < el.scrollHeight - 8) return;
  loading.value = true;
  window.setTimeout(() => {
    tickets.value = [...tickets.value, ...makePage(tickets.value.length)];
    loading.value = false;
  }, 500);
}
</script>

<template>
  <XhSelectRoot v-model:value="picked" placeholder="请选择">
    <XhSelectLabel>工单</XhSelectLabel>
    <XhSelectTrigger>
      <XhSelectValueText />
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent @scroll="onScroll">
        <XhSelectItem v-for="t in tickets" :key="t.value" :value="t.value">
          <XhSelectItemText>{{ t.label }}</XhSelectItemText>
          <XhSelectItemIndicator>✓</XhSelectItemIndicator>
        </XhSelectItem>
        <XhSelectItem v-if="loading" value="loading" disabled>
          <XhSelectItemText>加载中…</XhSelectItemText>
        </XhSelectItem>
      </XhSelectContent>
    </XhSelectPositioner>
  </XhSelectRoot>
  <p>已加载 {{ tickets.length }} / {{ TOTAL }} 条</p>
</template>

命令式聚焦

在触发器上取模板 ref，实例的 $el 就是那个按钮，focus 与 blur 直接调它

优先级

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

const levels = [
  { value: "p0", label: "紧急" },
  { value: "p1", label: "高" },
  { value: "p2", label: "普通" },
];

const picked = ref<string[]>([]);
const trigger = ref<InstanceType<typeof XhSelectTrigger> | null>(null);
const submitted = ref(false);

// 提交时没选值就把焦点送回触发器
function submit(): void {
  submitted.value = true;
  if (picked.value.length === 0) trigger.value?.$el.focus();
}

function blurTrigger(): void {
  trigger.value?.$el.blur();
}
</script>

<template>
  <XhSelectRoot v-model:value="picked" placeholder="请选择">
    <XhSelectLabel>优先级</XhSelectLabel>
    <XhSelectTrigger ref="trigger">
      <XhSelectValueText />
      <XhSelectIndicator>▾</XhSelectIndicator>
    </XhSelectTrigger>
    <XhSelectPositioner>
      <XhSelectContent>
        <XhSelectItem v-for="l in levels" :key="l.value" :value="l.value">
          <XhSelectItemText>{{ l.label }}</XhSelectItemText>
          <XhSelectItemIndicator>✓</XhSelectItemIndicator>
        </XhSelectItem>
      </XhSelectContent>
    </XhSelectPositioner>
  </XhSelectRoot>
  <div style="display: flex; gap: 8px; margin-block-start: 8px">
    <XhButton variant="outline" size="sm" @click="submit">提交</XhButton>
    <XhButton variant="ghost" size="sm" @click="blurTrigger">移开焦点</XhButton>
  </div>
  <p v-if="submitted && picked.length === 0" style="color: var(--xh-fg-danger)">
    还没选优先级，焦点已回到选择器
  </p>
</template>

产物

层	值
自定义元素	<xh-select>
Vue 组件	XhSelectContent XhSelectIndicator XhSelectItem XhSelectItemIndicator XhSelectItemText XhSelectLabel XhSelectPositioner XhSelectRoot XhSelectTrigger XhSelectValueText
组合式函数	useSelect
状态机	selectMachine
皮肤	@xihan-ui/styles/select.css

解剖

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

data-scope="select"：root · label · trigger · value-text · indicator · positioner · content · item · item-text · item-indicator · hidden-select

Props

属性	类型	必填	说明
collection	SelectNode[]		条目数据，显示文本与禁用的事实源。给了它，条目部件只需报 value， 显示文本也不再从活 DOM 现查。缺省即回到「文本写在条目里、现查 DOM」的老路。
value	string | string[] | null		选中值。裸串是单选的简写，null 是「受控且无选中」，缺省（undefined）才是非受控；内部一律按数组处理。 受控时 cell 直读 prop，写只发 onValueChange 不落内部值。
defaultValue	string | string[] | null		非受控初始选中值。与 value 同样接受裸串与 null。
multiple	boolean		允许选中多项。单选时选完即收起，多选时保持展开继续选。
open	boolean		展开态。给定即受控：内部不再自改，只发 onOpenChange。
defaultOpen	boolean
disabled	boolean		整个控件禁用：trigger 用原生 disabled，隐藏 select 不参与提交。
required	boolean		原生表单校验：无选中值时提交被拦下。
name	string		表单字段名。给定后隐藏 select 才带 name，选中值随表单一并提交。
placeholder	string		无选中时 value-text 显示的占位文字。
placement	Placement
offset	number
loop	boolean		方向键走到尽头是否回绕，默认 true。
dir	Direction		文字方向，默认 ltr。
variant	ControlVariant		形态：outline / subtle / ghost，决定触发器的描边与底色怎么用。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦与选中强调用哪族颜色。
size	Size		尺寸：sm / md / lg，决定触发器高度、内边距与字号档位。
onValueChange	(details: SelectValueChangeDetails) => void		value 变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。
onOpenChange	(details: SelectOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。

状态机

状态：open · closed

事件：OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE · ITEM.HIGHLIGHT · ITEM.LOST · ITEM.SELECT · VALUE.SET · FORM.RESET

判据：isOpenControlled · isMultiple

connect API

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

成员	类型	说明
open	boolean
collection	readonly SelectNodeMeta[]	collection 推出的条目元信息，按数据顺序排列；没给 collection 即空数组。
value	string[]	选中集合，按选中先后排列而非文档顺序。单选恒为长度 ≤ 1。
valueText	string[]	选中项的文本，与 value 逐项等长对应；某项在 DOM 里查不到条目时该项退回值本身。
displayText	string	value-text 实际显示的文字：有选中取其文本（多选按半角逗号加空格连起来），否则取 placeholder。
multiple	boolean	是否允许多选。
highlightedValue	string | null	高亮锚点；收起时为 null。
setOpen	(next: boolean) => void
setValue	(next: string | string[]) => void
getRootProps	() => T['element']
getLabelProps	() => T['element']
getTriggerProps	() => T['button']
getValueTextProps	() => T['element']
getIndicatorProps	() => T['element']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getItemProps	(props: SelectItemProps) => T['element']
getItemTextProps	(props: SelectItemProps) => T['element']
getItemIndicatorProps	(props: SelectItemProps) => T['element']
getHiddenSelectProps	() => T['select']	表单出口：一份视觉隐藏的原生 select，由根部件自行渲染（作者不必手写）。 选项由适配器按当前值补齐，原生提交与 required 校验据此拿到值。

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	closed, focus in trigger	展开列表并把高亮落到当前选中项（无选中则落首个可用条目）
ArrowDown	closed, focus in trigger	展开列表并把高亮落到选中项的下一个可用条目
ArrowUp	closed, focus in trigger	展开列表并把高亮落到选中项的上一个可用条目
单个可打印字符	closed, focus in trigger	连打检索命中的条目直接成为选中值（多选是加进集合，已在集合里则不动），列表不展开
ArrowDown	open, focus in content	高亮移到下一个条目（禁用项跳过、尽头按 loop 回绕）
ArrowUp	open, focus in content	高亮移到上一个条目（禁用项跳过、尽头按 loop 回绕）
Home	open, focus in content	高亮移到首个可用条目
End	open, focus in content	高亮移到末个可用条目
单个可打印字符	open, focus in content	连打检索移动高亮，不改选中值
Enter / Space	open, 单选, 高亮条目未禁用	选中高亮条目并关闭列表，焦点归还 trigger
Enter / Space	open, 多选, 高亮条目未禁用	切换高亮条目的选中态，列表不收起、焦点留在条目上
Escape	open	关闭列表并把焦点归还 trigger，选中值不变
Tab / Shift+Tab	open	关闭列表，焦点不归还 trigger，按 Tab 序列自然离开