下拉选择器

TuiSelect 当选项过多时，使用下拉菜单展示并选择内容。 它支持单选、多选、搜索筛选、以及灵活的选项渲染方式（配置式或插槽式）。

基础用法

配置式渲染 (Options Prop)

最基础的用法是通过 options 属性传入数据。适用于数据结构简单且无需自定义选项样式的场景。 options 数组项需包含 label 和 value 字段。

<script setup>
import { ref } from 'vue';

const value = ref('A');
const options = [
  { value: 'A', label: '选项 A' },
  { value: 'B', label: '选项 B' },
  { value: 'C', label: '选项 C', disabled: true }
];
</script>

<template>
  <TuiSelect v-model="value" :options="options" placeholder="请选择" />
</template>

插槽式渲染 (Slot Mode)

使用 <TuiOption> 子组件可以更灵活地渲染选项。这种方式允许您在选项中嵌入图标、图片或复杂的 HTML 结构。

<template>
  <TuiSelect v-model="value" placeholder="Select">
    <TuiOption 
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
      :disabled="item.disabled"
    />
  </TuiSelect>
</template>

多选

设置 multiple 属性即可启用多选模式。此时 v-model 绑定值为数组。

基础多选

<TuiSelect multiple v-model="selectedList" :options="options" />

标签折叠 (Collapse Tags)

当选中项过多时，可以通过以下属性控制显示效果，避免输入框高度无限撑开：

• collapseTags: 是否将多选的标签折叠（默认 true）。
• maxCollapseTags: 超过多少个标签后开始折叠（默认 2）。

<template>
  <TuiSelect 
    multiple 
    :maxCollapseTags="1" 
    v-model="vals" 
    :options="options" 
  />
  
  <TuiSelect 
    multiple 
    :collapseTags="false" 
    v-model="vals" 
    :options="options" 
  />
</template>

多选限制

使用 multipleLimit 属性限制用户最多选择的项目数量。

<TuiSelect multiple :multipleLimit="3" placeholder="最多选3项" ... />

筛选与搜索

设置 filterable 为 true 即可开启搜索功能。

默认筛选

默认情况下，组件会匹配 label 包含输入关键字的选项（不区分大小写）。

<TuiSelect filterable v-model="value" :options="options" />

自定义筛选 (Filter Method)

通过 filterMethod 可以自定义搜索逻辑（例如区分大小写，或同时匹配 value 和 label）。

<script setup>
const myFilter = (option, query) => {
  // 示例：仅匹配 value，且区分大小写
  return option.value.includes(query);
};
</script>

<template>
  <TuiSelect 
    multiple 
    filterable 
    filterPlaceholder="输入 Value 进行搜索"
    :filterMethod="myFilter" 
    v-model="value" 
    :options="options" 
  />
</template>

状态与外观

• Clearable: 开启 clearable 后，鼠标悬停时会显示清空按钮。
• Disabled: 禁用整个选择器。
• Size: 支持 large, default, small。
• Icon: 通过 icon 属性在输入框尾部添加自定义图标。
• FitInputWidth: 默认为 true，即下拉菜单宽度与输入框保持一致。设为 false 时，下拉菜单宽度将根据内容自适应（通常用于选项文字特别长的场景）。

<template>
  <div class="demo-gap">
    <TuiSelect size="small" placeholder="Small" ... />
    <TuiSelect size="large" placeholder="Large" ... />
    
    <TuiSelect :fitInputWidth="false" placeholder="宽选项适配" ... />
  </div>
</template>

API 参考

TuiSelect Props

属性名	类型	默认值	说明
modelValue	String/Number/Array	-	绑定值。单选为基本类型，多选为数组。
options	Array	[]	选项数据源，仅在配置式渲染时使用。
multiple	Boolean	false	是否开启多选。
disabled	Boolean	false	是否禁用。
clearable	Boolean	false	是否可以清空选项。
filterable	Boolean	false	是否可搜索。
filterMethod	Function	-	自定义搜索方法 (option, query) => boolean。
filterPlaceholder	String	-	搜索框的占位符。
collapseTags	Boolean	true	多选时是否将选中值按文字的形式展示。
maxCollapseTags	Number	2	多选时最多显示多少个 tag 后开始折叠。
multipleLimit	Number	-	多选时用户最多可以选择的项目数，为 0 则不限制。
size	String	'default'	尺寸。可选：large, default, small。
placeholder	String	-	占位符。
icon	String	-	自定义尾部图标类名。
fitInputWidth	Boolean	true	下拉弹窗宽度是否与输入框一致。
offset	Number	10	下拉弹窗的垂直偏移量。
allowCreate	Boolean	false	是否允许用户创建新条目（需配合 filterable 使用）。

TuiSelect Emits

事件名	说明	回调参数
update:modelValue	绑定值变化时触发。	(value)
change	选中值发生变化时触发。	(value)
visible-change	下拉框出现/隐藏时触发。	(visible: Boolean)
clear	点击清空按钮时触发。	-
blur	输入框失去焦点时触发。	(event)
focus	输入框获得焦点时触发。	(event)

TuiOption Props

属性名	类型	默认值	说明
value	String/Number/Object	-	选项的值。
label	String	-	选项的标签，若不设置则默认与 value 相同。
disabled	Boolean	false	是否禁用该选项。

全局交互监控

TuiSelect 组件深度集成了 TechUI 的全局服务（TuiService），通过监听全局信号来实现智能的闭合交互，确保下拉菜单只在需要时显示：

• ESC 响应 (escCounter)：组件实时监测全局 ESC 键的触发。当用户按下 Esc 键时，escCounter 更新，当前展开的下拉菜单会自动收起。
• 智能点击检测 (clickCounter)：组件监听全局点击事件。每次点击发生时，全局服务会更新 clickCounter 并提供 clickTarget（点击目标）。组件内部会进行精准的包含检测（Contains Check）：只有当点击目标不在 Select 组件自身内部（包括输入框和下拉面板）时，才会触发隐藏逻辑。这种机制确保了在复杂的页面布局中，点击外部关闭（Click Outside）的功能准确无误。

定位核心

TuiSelect 的下拉面板定位底层完全依赖于 Floating UI 库。

这意味着您无需担心下拉菜单在屏幕边缘的显示问题，组件会自动处理：

• 智能翻转 (Flip)：当下方空间不足时，菜单会自动翻转到上方显示。
• 视口修正 (Shift)：确保菜单始终保持在视口可见范围内，不会被截断。
• 跟随滚动：当页面滚动时，菜单会动态更新位置以保持与输入框的相对锚定。

您只需关注业务逻辑，复杂的几何计算均由底层引擎自动完成。