SwSelect

SwSelect 是下拉选择器：选项收进弹层、触发器收起态。单 / 多选一个组件（multiple 开关），支持可清空（clearable）、分组（选项 group 字段）、可搜索（searchable）与输入即建（creatable）。受控 v-model，单选为单值、多选为数组。

薄壳套 reka-ui：默认基于 Select 原语；searchable 时内部切换 Combobox 原语（触发器变输入框），对外仍是同一套 props / v-model / 插槽。弹层自渲染（不是原生 <select> 的 OS 弹层），故完全可定制；键盘导航 / 弹层定位 / a11y 开箱自带。视觉走「最小必要基础样式」——触发器 / 弹层 / 选中 / 高亮 / 禁用态默认都肉眼可辨，颜色 / 圆角等由 applier 覆盖。

选型：选项多、要省横向空间时用本组件（下拉）。选项少（2–5）、要全部可见、省一次点击时用 SwSegmented（平铺）。二者互补，如 antd 同时有 Select 与 Segmented。

单选

<script setup lang="ts">
const status = ref()
</script>

<template>
  <SwSelect
    v-model="status"
    :options="[
      { value: 'all', label: '全部状态' },
      { value: 'ongoing', label: '连载中' },
      { value: 'completed', label: '已完结' },
    ]"
    placeholder="选择状态"
    aria-label="状态筛选"
  />

  <!-- 整体禁用：父表单 pending / 无权限时锁住选择器 -->
  <SwSelect v-model="status" :options="options" disabled />
</template>

多选 + 可清空

multiple 让 v-model 变数组；clearable 在有选中值时显示一键清空按钮。多选时触发器默认显示「已选 N 项」，要展示 tags / chips 走 #trigger 插槽：

分组

选项带 group 字段时，连续同名归一组、组首渲染分组标题；不带 group 则扁平：

<template>
  <SwSelect
    v-model="city"
    :options="[
      { value: 'bj', label: '北京', group: '直辖市' },
      { value: 'sh', label: '上海', group: '直辖市' },
      { value: 'hz', label: '杭州', group: '浙江' },
    ]"
  />
</template>

可搜索（searchable）

searchable 让触发器变输入框：输入按 label 本地过滤（大小写不敏感包含匹配，组内滤空整组隐藏），↑↓ + 回车可选。选项几十上百（演职员 / 标签 / 城市）时用它；集合大到不能一次拉全（作品库 / 全站用户）时用下面的远程搜索。

单选时输入框常显选中项 label（弹层打开后未输入前不过滤，避免被选中值锁死列表）；多选时已选项渲染为 chips（label + ✕ 移除，Backspace 空输入删末位）。

远程搜索（remote + @search + loading）

三件套组合出「从大集合里搜一个选一个」：remote 关掉本地 label 过滤（options 本身就是远程结果集——服务端按拼音 / 别名 / id 命中的项 label 未必含关键词，本地再滤一遍会把它们藏掉）；@search(term) 把用户输入交给业务（按 searchDebounce 防抖，默认 300ms；点清空立即发 ''，据此复位列表）；loading 在下拉里显示「加载中…」并压掉「无匹配」空态，当前列表保留不清空（防每次击键闪烁）。

结果陈旧期（用户已敲字、结果尚未回来：防抖窗口 ∪ loading）当前列表保留但不可选（选项 disabled + 变淡）——保留防塌陷跳动，不可选防「手快点下去选了与当前查询无关的对象」；creatable 的「创建」项同期藏掉。options 被整换后，已选项即使不在新结果集里，单选回显 / 多选 chips 的 label 也不会丢——组件内部缓存曾被选中值的 label（只记选过的，有界），同 value 的 label 后来变了以最新为准。

两条语义归业务：@search 收到的 '' 只表示「搜索词已清空」——复位 / 回初始列表 / 不搜由你定，不等于搜全部；remote 下 creatable 的「精确命中」只挡已加载页里的重复，真正的去重保证在服务端（唯一约束）。

<SwSelect v-model="mediaId" searchable remote :loading="pending" :options="mediaOptions" @search="onSearch" />

async function onSearch(term: string) {
  pending.value = true;
  mediaOptions.value = await api.media.options({ keyword: term }); // 整换结果集
  pending.value = false;
}

输入即建（creatable，标签选择场景）

creatable（仅 searchable 下生效）在输入无精确命中（大小写不敏感）时于列表尾部追加「创建 "xxx"」项。选中它不改 v-model，只发 @create（payload 为 trim 后输入文本）——业务调后端建项后自行把新 option 推进 options + v-model。multiple + searchable + creatable 组合即 tag-input 形态：

<script setup lang="ts">
async function onCreateTag(name: string) {
  const tag = await createTag(name) // 业务调后端建项
  tagOptions.value.push({ value: tag.id, label: tag.name })
  tagIds.value = [...tagIds.value, tag.id] // 推进 options + v-model
}
</script>

<template>
  <SwSelect v-model="tagIds" multiple searchable creatable :options="tagOptions" @create="onCreateTag" />
</template>

Props

SwSelectOption：{ value: string \| number; label: string; disabled?: boolean; group?: string }（可从包名导入：import type { SwSelectOption } from '@swift-web/framework'）

Events

Slots

样式定制 Token

触发器与弹层皮肤经 --sw-select-* token 覆盖（fallback 即默认视觉）。弹层 Portal 到 body，token 在 :root（或任意 body 祖先）覆盖即可，无需 :global 穿透：

高度 / 字号默认吃表单控件族语义 token --control-height（32px）/ --control-font-size（14px）——SwInput / SwSelect / SwSegmented 同行混排默认等高；覆盖这两个 token 全站控件同步缩放，组件级 token 优先级更高。

注意事项

• 弹层经 Portal 传送到 body：applier 要改弹层样式（如字号）须用全局 / :global 选择器（scoped :deep 够不到），命中 .sw-select-content。
• 无内置视觉品牌：组件只给最小必要基础样式；颜色 / 圆角等由 applier 覆盖。
• 多选触发器默认显示「已选 N 项」：要展示 tags / chips 等用 #trigger 插槽自定义。
• searchable 默认是本地过滤：只按 label 大小写不敏感包含匹配；远程搜索必须加 remote 关掉它，否则服务端按别名 / 拼音命中的项会被本地过滤藏掉。数据源仍归业务（组件只交出 @search 的搜索词、承接 options）。
• @create 不改 v-model：选中「创建 "xxx"」项只发事件——业务建项后必须自己把新 option 推进 options 并更新 v-model，否则界面无变化。
• searchable 时 #trigger 插槽不生效：搜索形态的触发器是输入框（多选为 chips + 输入框），无自定义触发器插槽。
• multiple 时 v-model 必须是数组：多选把 v-model 初始化为单值（如 ref('')）会让选中态、「已选 N 项」计数全错且类型崩——多选用 ref([])、单选用单值。
• 分组按「连续同名」归组：同名 group 的选项必须相邻排列，散落的同名 group 会渲染成多个同名分组块——options 传入前先按 group 排序。

相关

• SwSegmented · SwFormField