FxSelect 选择器 / FxOption / FxOptionGroup

不依赖任何 UI 框架。基于 FxTooltip + FxScrollbar + FxIcon。

基础用法

<template>
  <FxSelect v-model="value" placeholder="请选择" style="width: 240px">
    <FxOption value="a" label="选项 A" />
    <FxOption value="b" label="选项 B" />
    <FxOption value="c" label="选项 C" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

options 数据驱动

通过 options 属性直接传数据，无需手写 FxOption。option-props 可自定义字段别名。

<template>
  <div class="flex flex-col gap-4">
    <FxSelect
      v-model="value1"
      :options="options"
      placeholder="数据驱动 options"
      style="width: 240px"
    />
    <FxSelect
      v-model="value2"
      :options="customOptions"
      :option-props="{ label: 'name', value: 'id', disabled: 'unavailable' }"
      placeholder="自定义字段别名"
      style="width: 240px"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value1 = ref("")
const value2 = ref("")
const options = [
  { value: "a", label: "选项 A" },
  { value: "b", label: "选项 B" },
  { value: "c", label: "选项 C" },
]
const customOptions = [
  { id: 1, name: "北京", unavailable: false },
  { id: 2, name: "上海", unavailable: false },
  { id: 3, name: "广州", unavailable: true },
]
</script>

多选（multiple）

<template>
  <FxSelect
    v-model="value"
    multiple
    placeholder="请选择"
    style="width: 240px"
  >
    <FxOption value="a" label="选项 A" />
    <FxOption value="b" label="选项 B" />
    <FxOption value="c" label="选项 C" />
    <FxOption value="d" label="选项 D" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref<string[]>([])
</script>

折叠标签（collapse-tags）

<template>
  <div class="flex flex-col gap-4">
    <FxSelect
      v-model="value"
      multiple
      collapse-tags
      placeholder="折叠标签"
      style="width: 280px"
    >
      <FxOption value="a" label="选项 A" />
      <FxOption value="b" label="选项 B" />
      <FxOption value="c" label="选项 C" />
      <FxOption value="d" label="选项 D" />
      <FxOption value="e" label="选项 E" />
    </FxSelect>
    <FxSelect
      v-model="value2"
      multiple
      collapse-tags
      :max-collapse-tags="3"
      collapse-tags-tooltip
      placeholder="最多显示 3 个"
      style="width: 280px"
    >
      <FxOption value="a" label="选项 A" />
      <FxOption value="b" label="选项 B" />
      <FxOption value="c" label="选项 C" />
      <FxOption value="d" label="选项 D" />
      <FxOption value="e" label="选项 E" />
    </FxSelect>
    <FxSelect
      v-model="value3"
      multiple
      collapse-tags
      :max-collapse-tags="2"
      collapse-tags-tooltip
      :tag-tooltip="{ effect: 'dark', placement: 'top' }"
      placeholder="自定义 tooltip 配置（tag-tooltip）"
      style="width: 280px"
    >
      <FxOption value="a" label="选项 A" />
      <FxOption value="b" label="选项 B" />
      <FxOption value="c" label="选项 C" />
      <FxOption value="d" label="选项 D" />
    </FxSelect>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref<string[]>(["a", "b", "c", "d"])
const value2 = ref<string[]>(["a", "b", "c", "d", "e"])
const value3 = ref<string[]>(["a", "b", "c", "d"])
</script>

collapse-tags 折叠多余标签，max-collapse-tags 控制最多显示数；开启 collapse-tags-tooltip 后，悬浮 +N 会用 tooltip 显示被折叠的项，tag-tooltip 可配置该 tooltip，字段透传给 FxTooltip（完整字段见下方 API 表，含 effect / placement / offset / showArrow / transition / appendTo 等）。

搜索（filterable）

为 FxSelect 启用搜索过滤。默认会匹配所有 label 包含输入值的选项；如需自定义过滤策略，可传 filter-method（输入值变化时调用，参数为当前输入值）。

<template>
  <FxSelect
    v-model="value"
    filterable
    placeholder="搜索"
    style="width: 240px"
  >
    <FxOption value="a" label="北京" />
    <FxOption value="b" label="上海" />
    <FxOption value="c" label="广州" />
    <FxOption value="d" label="深圳" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

可清空（clearable）

<template>
  <FxSelect
    v-model="value"
    clearable
    placeholder="可清空"
    style="width: 240px"
  >
    <FxOption value="a" label="选项 A" />
    <FxOption value="b" label="选项 B" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("a")
</script>

分组（FxOptionGroup）

<template>
  <FxSelect v-model="value" placeholder="请选择" style="width: 240px">
    <FxOptionGroup label="一线城市">
      <FxOption value="bj" label="北京" />
      <FxOption value="sh" label="上海" />
      <FxOption value="gz" label="广州" />
      <FxOption value="sz" label="深圳" />
    </FxOptionGroup>
    <FxOptionGroup label="二线城市">
      <FxOption value="hz" label="杭州" />
      <FxOption value="cd" label="成都" />
      <FxOption value="wh" label="武汉" />
    </FxOptionGroup>
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

下拉头部（header slot）

<template>
  <FxSelect v-model="value" placeholder="请选择" style="width: 240px">
    <template #header>
      <div style="padding: 8px 16px; font-size: 12px; color: var(--fx-text-color-secondary)">
        下拉头部
      </div>
    </template>
    <FxOption value="a" label="选项 A" />
    <FxOption value="b" label="选项 B" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

下拉底部（footer slot）

<template>
  <FxSelect v-model="value" placeholder="请选择" style="width: 240px">
    <FxOption value="a" label="选项 A" />
    <FxOption value="b" label="选项 B" />
    <template #footer>
      <div
        style="
          padding: 8px 16px;
          font-size: 12px;
          color: var(--fx-color-primary);
          cursor: pointer;
        "
        @click="value = ''"
      >
        清空选择
      </div>
    </template>
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

v-for 渲染选项（options）

<template>
  <FxSelect v-model="value" placeholder="请选择" style="width: 240px">
    <FxOption
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
      :disabled="item.disabled"
    />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
const options = [
  { value: "a", label: "选项 A" },
  { value: "b", label: "选项 B" },
  { value: "c", label: "选项 C", disabled: true },
  { value: "d", label: "选项 D" },
]
</script>

自定义选项内容（custom label）

<template>
  <FxSelect v-model="value" placeholder="请选择" style="width: 240px">
    <FxOption
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    >
      <span style="display: flex; align-items: center; gap: 8px">
        <FxIcon :name="item.icon" />
        {{ item.label }}
      </span>
    </FxOption>
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
const options = [
  { value: "a", label: "北京", icon: "ep:location" },
  { value: "b", label: "上海", icon: "ep:location" },
  { value: "c", label: "广州", icon: "ep:location" },
]
</script>

对象值（value-key）

如果 FxSelect 的绑定值是对象，务必设置 value-key 为其唯一标识键名。通过 value-key 可正确处理 label 重复的数据——label 重复但通过 id 区分选项。

<template>
  <FxSelect
    v-model="value"
    value-key="id"
    placeholder="请选择"
    style="width: 240px"
  >
    <FxOption
      v-for="item in cities"
      :key="item.id"
      :value="item"
      :label="item.name"
    />
  </FxSelect>
  <p
    style="margin-top: 12px; color: var(--fx-text-color-secondary); font-size: 12px"
  >
    选中值：{{ JSON.stringify(value) }}
  </p>
</template>

<script setup lang="ts">
import { ref } from "vue"
interface City {
  id: number
  name: string
}
const value = ref<City>()
const cities: City[] = [
  { id: 1, name: "北京" },
  { id: 2, name: "上海" },
  { id: 3, name: "广州" },
]
</script>

自定义标签（custom tag）

多选模式下可通过 tag 作用域插槽自定义标签内容（作用域参数：item、index、close）。使用自定义 tag 时 collapse-tags、collapse-tags-tooltip、max-collapse-tags 不生效。

<template>
  <FxSelect
    v-model="value"
    multiple
    placeholder="自定义标签"
    style="width: 280px"
  >
    <template #tag="{ item, close }">
      <span class="fx-select__tag-text">{{ item.label }}</span>
      <FxIcon
        name="ep:close-bold"
        class="fx-select__tag-close"
        @click.stop="close()"
      />
    </template>
    <FxOption value="a" label="选项 A" />
    <FxOption value="b" label="选项 B" />
    <FxOption value="c" label="选项 C" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref<string[]>(["a", "b"])
</script>

加载中（loading）

loading 显示加载状态，loading-text 自定义加载文本。

<template>
  <FxSelect v-model="value" loading loading-text="加载中..." placeholder="请选择" style="width: 240px">
    <FxOption value="a" label="选项 A" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

远程搜索（remote search）

输入关键词从服务端搜索数据。设置 filterable 和 remote 为 true 开启远程搜索，并传入 remote-method（输入值变化时调用的函数，参数为当前输入值）。内置 debounce 防抖（默认 300ms）。注意：用 v-for 渲染 FxOption 时需加 key（唯一值，如 item.value）。

<template>
  <FxSelect
    v-model="value"
    filterable
    remote
    :remote-method="remoteMethod"
    :loading="loading"
    placeholder="输入城市名搜索"
    style="width: 240px"
  >
    <FxOption
      v-for="item in options"
      :key="item.value"
      :value="item.value"
      :label="item.label"
    />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
const loading = ref(false)
const options = ref<{ value: string; label: string }[]>([])
const allData = [
  { value: "bj", label: "北京" },
  { value: "sh", label: "上海" },
  { value: "gz", label: "广州" },
  { value: "sz", label: "深圳" },
  { value: "hz", label: "杭州" },
  { value: "cd", label: "成都" },
]
const remoteMethod = (query: string) => {
  if (!query) {
    // 空关键词时展示全部可选数据，避免下拉直接显示"暂无数据"
    options.value = allData
    return
  }
  loading.value = true
  setTimeout(() => {
    options.value = allData.filter((item) => item.label.includes(query))
    loading.value = false
  }, 300)
}
</script>

创建新选项（allow-create）

通过 allow-create 属性，用户可在输入框中输入新值来创建不在选项列表中的项。注意：allow-create 需配合 filterable 使用。

<template>
  <FxSelect
    v-model="value"
    filterable
    allow-create
    multiple
    placeholder="输入创建新标签"
    style="width: 280px"
  >
    <FxOption value="a" label="已有标签 A" />
    <FxOption value="b" label="已有标签 B" />
    <FxOption value="c" label="已有标签 C" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref<string[]>(["a"])
</script>

空值处理（empty-values）

empty-values 定义哪些值视为"未选择"（显示 placeholder）。

<template>
  <div class="flex flex-col gap-2">
    <FxSelect
      v-model="value"
      :empty-values="[null, undefined, '']"
      placeholder="可为空值"
      style="width: 240px"
    >
      <FxOption :value="null" label="不选择" />
      <FxOption value="a" label="选项 A" />
      <FxOption value="b" label="选项 B" />
    </FxSelect>
    <p style="color: var(--fx-text-color-secondary); font-size: 12px">
      当前值：{{ JSON.stringify(value) }}
    </p>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref<string | null>(null)
</script>

禁用（disabled）

<template>
  <FxSelect v-model="value" disabled placeholder="禁用" style="width: 240px">
    <FxOption value="a" label="选项 A" />
    <FxOption value="b" label="选项 B" />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

禁用选项（disabled option）

<template>
  <FxSelect v-model="value" placeholder="请选择" style="width: 240px">
    <FxOption value="a" label="选项 A" />
    <FxOption value="b" label="选项 B" />
    <FxOption value="c" label="禁用选项" disabled />
  </FxSelect>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

尺寸（size）

<template>
  <div class="flex flex-col gap-4">
    <FxSelect v-model="value" size="large" placeholder="Large" style="width: 240px">
      <FxOption value="a" label="选项 A" />
      <FxOption value="b" label="选项 B" />
    </FxSelect>
    <FxSelect v-model="value" placeholder="Default" style="width: 240px">
      <FxOption value="a" label="选项 A" />
      <FxOption value="b" label="选项 B" />
    </FxSelect>
    <FxSelect v-model="value" size="small" placeholder="Small" style="width: 240px">
      <FxOption value="a" label="选项 A" />
      <FxOption value="b" label="选项 B" />
    </FxSelect>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
const value = ref("")
</script>

键盘交互

键	行为
↑ / ↓	在可见 option 间导航（跳过禁用项，循环）；下拉关闭时按 ↓ 展开
Enter	选中当前高亮 option（IME 组合态时不触发）
Esc	有搜索词时清空搜索词；否则关闭下拉
Backspace	多选且输入框为空时删除最后一个非禁用 tag
Tab	关闭下拉并切焦到下一可聚焦元素
Home / End	跳到首个 / 末个可见 option
PageUp / PageDown	向上 / 向下跳 10 项

非 filterable 单选模式下，组件根元素带 tabindex="-1"，可通过 Tab 聚焦后使用键盘。

FxSelect Props（常用）

属性	类型	默认值	说明
model-value (v-model)	OptionValue | OptionValue[]	—	绑定值
multiple	boolean	false	是否多选
disabled	boolean	false	是否禁用
clearable	boolean	false	是否可清空
filterable	boolean	false	是否可搜索
placeholder	string	'请选择'	占位文字
size	'large' | 'default' | 'small'	'default'	尺寸
collapse-tags	boolean	false	多选折叠 tag
max-collapse-tags	number	1	折叠时最多显示 tag 数
value-key	string	'value'	对象值主键
no-data-text	string	'暂无数据'	无数据文本
no-match-text	string	—	无匹配文本
multiple-limit	number	0	多选最多可选数
filter-method	(query: string) => void	—	自定义过滤
value-key	string	'value'	对象值主键
fit-input-width	boolean	false	菜单匹配输入框宽
show-arrow	boolean	true	显示箭头
offset	number	12	浮层偏移
tabindex	string | number	0	tabindex
aria-label	string	—	aria-label
allow-create	boolean	false	允许创建（需 filterable）
remote	boolean	false	远程加载
loading	boolean	false	加载中
loading-text	string	—	加载中文本
options	Record<string, any>[]	—	数据驱动
option-props	{ label?, value?, disabled? }	{label,value,disabled}	options 字段别名
empty-values	any[]	[undefined, null, '']	空值列表
value-on-clear	any	—	清空时回填的值，不传时维持默认（多选 []、单选 undefined）
id	string	—	input id
automatic-dropdown	boolean	false	focus 时自动展开下拉
popper-options	Record<string, unknown>	—	透传给底层 floating-ui 的定位配置
remote-show-suffix	boolean	false	远程搜索时是否仍显示后缀（箭头）
collapse-tags-tooltip	boolean	false	折叠 tag 时悬浮显示被折叠项
tag-tooltip	{ effect?, placement?, offset?, showArrow?, fallbackPlacements?, appendTo?, popperClass?, popperStyle?, transition?, teleported?, popperOptions?, showAfter?, hideAfter?, autoClose? }	—	折叠 tag tooltip 的配置，字段透传给 FxTooltip
validate-event	boolean	true	值变化时是否触发表单项校验

FxSelect Events

事件名	说明
update:modelValue	值变化
change	变化时
clear	清空时
visible-change	显隐变化
remove-tag	多选移除 tag
focus / blur	聚焦 / 失焦
popup-scroll	下拉菜单滚动时持续触发（参数：{ scrollTop, scrollLeft }）
end-reached	下拉滚动到边界时触发（参数：top / bottom / left / right）

FxSelect Slots

插槽名	说明
default	选项内容（FxOption / FxOptionGroup）
prefix	前置内容
tag	自定义多选标签（作用域：item/index/close）
label	自定义选中项标签（单选作用域：label/value；多选 tag 内含 index/label/value）
header	下拉菜单头部内容
footer	下拉菜单底部内容
empty	无数据 / 无匹配数据时的内容
loading	加载中内容

FxOption Props

属性	类型	说明
value	OptionValue	选项值
label	string | number	选项标签
disabled	boolean	是否禁用
created	boolean	是否由用户创建（配合 allow-create）

FxOptionGroup Props

属性	类型	说明
label	string	分组标题
disabled	boolean	是否禁用整组