弹出选择 popselect

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

示例

基础用法

触发器旁弹出一个列表，选完即收起；collection 是条目的事实源，浮层里不写条目也会铺开

当前值：（未选）

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

const fruits = [
  { value: "apple", label: "苹果" },
  { value: "banana", label: "香蕉" },
  { value: "blueberry", label: "蓝莓" },
  { value: "cherry", label: "樱桃（缺货）", disabled: true },
  { value: "durian", label: "榴莲" },
];

const picked = ref<string[]>([]);
// 触发器上显示当前选中项的文本，没选中就显示提示语
const label = computed(
  () => fruits.find((f) => f.value === picked.value[0])?.label ?? "请选择水果",
);
</script>

<template>
  <XhPopselectRoot v-model:value="picked" :collection="fruits" placement="bottom-start">
    <XhPopselectTrigger>{{ label }}</XhPopselectTrigger>
    <XhPopselectPositioner>
      <XhPopselectContent />
    </XhPopselectPositioner>
  </XhPopselectRoot>
  <p>当前值：{{ picked.length ? picked.join("、") : "（未选）" }}</p>
</template>

多选

multiple 下落值是切换、浮层不收起，可以接着挑；收起交给 Esc 或点浮层外

已选 1 个

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

const cities = [
  { value: "bj", label: "北京" },
  { value: "sh", label: "上海" },
  { value: "gz", label: "广州" },
  { value: "sz", label: "深圳" },
  { value: "cd", label: "成都" },
];

const picked = ref<string[]>(["bj"]);
// 多选把各项文本连起来显示
const label = computed(() => {
  const texts = picked.value.map((v) => cities.find((c) => c.value === v)?.label ?? v);
  return texts.length ? texts.join("、") : "请选择城市";
});
</script>

<template>
  <XhPopselectRoot v-model:value="picked" :collection="cities" multiple placement="bottom-start">
    <XhPopselectTrigger>{{ label }}</XhPopselectTrigger>
    <XhPopselectPositioner>
      <XhPopselectContent />
    </XhPopselectPositioner>
  </XhPopselectRoot>
  <p>已选 {{ picked.length }} 个</p>
</template>

受控

选中值与展开态都由外部持有：组件只发意图，写不写回由你决定

展开：否；当前值：normal

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhButton,
  XhPopselectContent,
  XhPopselectPositioner,
  XhPopselectRoot,
  XhPopselectTrigger,
} from "@xihan-ui/vue";

const levels = [
  { value: "low", label: "低" },
  { value: "normal", label: "中" },
  { value: "high", label: "高" },
];

const picked = ref<string[]>(["normal"]);
const open = ref(false);
const label = computed(() => levels.find((l) => l.value === picked.value[0])?.label ?? "未设置");
</script>

<template>
  <XhPopselectRoot
    v-model:value="picked"
    v-model:open="open"
    :collection="levels"
    placement="bottom-start"
  >
    <XhPopselectTrigger>优先级：{{ label }}</XhPopselectTrigger>
    <XhPopselectPositioner>
      <XhPopselectContent />
    </XhPopselectPositioner>
  </XhPopselectRoot>
  <p>
    <XhButton variant="ghost" size="sm" @click="open = !open">从外部开合</XhButton>
    <XhButton variant="ghost" size="sm" @click="picked = ['high']">从外部设为「高」</XhButton>
  </p>
  <p>展开：{{ open ? "是" : "否" }}；当前值：{{ picked.join("、") || "（未选）" }}</p>
</template>

形态·语气·尺寸

三个视觉轴只写在根上，触发器与浮层都从这里继承

<script setup lang="ts">
import { ref } from "vue";
import {
  XhPopselectContent,
  XhPopselectPositioner,
  XhPopselectRoot,
  XhPopselectTrigger,
} from "@xihan-ui/vue";

const plans = [
  { value: "free", label: "免费版" },
  { value: "pro", label: "专业版" },
  { value: "team", label: "团队版" },
];

const outline = ref<string[]>(["free"]);
const subtle = ref<string[]>(["pro"]);
const ghost = ref<string[]>(["team"]);
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center">
    <XhPopselectRoot v-model:value="outline" :collection="plans" variant="outline" size="sm">
      <XhPopselectTrigger>outline · sm</XhPopselectTrigger>
      <XhPopselectPositioner>
        <XhPopselectContent />
      </XhPopselectPositioner>
    </XhPopselectRoot>

    <XhPopselectRoot
      v-model:value="subtle"
      :collection="plans"
      variant="subtle"
      tone="success"
      size="md"
    >
      <XhPopselectTrigger>subtle · success</XhPopselectTrigger>
      <XhPopselectPositioner>
        <XhPopselectContent />
      </XhPopselectPositioner>
    </XhPopselectRoot>

    <XhPopselectRoot
      v-model:value="ghost"
      :collection="plans"
      variant="ghost"
      tone="danger"
      size="lg"
    >
      <XhPopselectTrigger>ghost · danger · lg</XhPopselectTrigger>
      <XhPopselectPositioner>
        <XhPopselectContent />
      </XhPopselectPositioner>
    </XhPopselectRoot>
  </div>
</template>

自定义条目

手写整棵部件树：条目里想放什么都行，行为与 collection 铺开的那一套完全一致

当前指派：u1

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhPopselectContent,
  XhPopselectItem,
  XhPopselectItemIndicator,
  XhPopselectItemText,
  XhPopselectPositioner,
  XhPopselectRoot,
  XhPopselectTrigger,
} from "@xihan-ui/vue";

const members = [
  { value: "u1", label: "赵晓", role: "负责人" },
  { value: "u2", label: "钱多", role: "开发" },
  { value: "u3", label: "孙离", role: "设计" },
];

const picked = ref<string[]>(["u1"]);
const label = computed(() => members.find((m) => m.value === picked.value[0])?.label ?? "指派给");
</script>

<template>
  <XhPopselectRoot v-model:value="picked" :collection="members" placement="bottom-start">
    <XhPopselectTrigger>指派给：{{ label }}</XhPopselectTrigger>
    <XhPopselectPositioner>
      <XhPopselectContent>
        <XhPopselectItem v-for="m in members" :key="m.value" :value="m.value">
          <XhPopselectItemText>{{ m.label }}</XhPopselectItemText>
          <span style="color: var(--xh-fg-muted); font-size: var(--xh-font-size-sm)">
            {{ m.role }}
          </span>
          <XhPopselectItemIndicator />
        </XhPopselectItem>
      </XhPopselectContent>
    </XhPopselectPositioner>
  </XhPopselectRoot>
  <p>当前指派：{{ picked.join("、") || "（未指派）" }}</p>
</template>

产物

层	值
自定义元素	<xh-popselect>
Vue 组件	XhPopselectContent XhPopselectItem XhPopselectItemIndicator XhPopselectItemText XhPopselectPositioner XhPopselectRoot XhPopselectTrigger
组合式函数	usePopselect
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/popselect.css

解剖

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

data-scope="popselect"：root · trigger · positioner · content · item · item-text · item-indicator

Props

属性	类型	必填	说明
size	Size		尺寸：sm / md / lg，决定触发器高度、内边距与字号档位。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦与选中强调用哪族颜色。
variant	ControlVariant		形态：outline / subtle / ghost，决定触发器的描边与底色怎么用。

connect API

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

成员	类型	说明
open	boolean
value	string[]	选中集合；单选恒为长度 ≤ 1。
collection	readonly PopselectNodeMeta[]	collection 推出的条目元信息，按数据顺序排列；没给 collection 即空数组。
multiple	boolean
focusedValue	string | null	焦点锚点；焦点不在列表内时为 null。
disabled	boolean
isSelected	(value: string) => boolean
setOpen	(next: boolean) => void
setValue	(next: string[]) => void
select	(value: string) => void	落值：单选替换并收起浮层，多选切换并保持展开。
getRootProps	() => T['element']
getTriggerProps	() => T['button']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getItemProps	(props: PopselectItemProps) => T['element']
getItemTextProps	(props: PopselectItemProps) => T['element']
getItemIndicatorProps	(props: PopselectItemProps) => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowDown / ArrowUp	focus on trigger, 收起态	展开浮层；焦点随即进入列表，落在选中项上，无选中则落首个可停留条目
ArrowDown	focus in content	焦点移到下一个可停留条目（禁用项跳过、尽头按 loop 回绕）
ArrowUp	focus in content	焦点移到上一个可停留条目（禁用项跳过、尽头按 loop 回绕）
Home	focus in content	焦点移到首个可停留条目
End	focus in content	焦点移到末个可停留条目
Enter / Space	focus in content, 单选	选中焦点条目并收起浮层，焦点归还触发器；条目禁用则不认
Enter / Space	focus in content, multiple	切换焦点条目的选中态，浮层保持展开继续挑
单个可打印字符	focus in content, typeahead 未关	连打检索把焦点移到首字母匹配的条目，不落值
Tab / Shift+Tab	focus in content	收起浮层并放行焦点，按 Tab 序列离开