下拉选择器 (原生)

TuiSelectNative 是基于浏览器原生 HTML <select> 元素封装的组件。 相比于功能强大的 TuiSelect，它的体积更轻量，交互完全遵循操作系统或浏览器的原生行为。它主要用于对 UI 定制要求不高、或需要调用原生控件的场景。

基础用法

配置式渲染

通过 options 属性传入选项数组。默认识别 label 和 value 字段，也可通过 labelKey 和 valueKey 自定义。

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

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

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

插槽式渲染

使用 <TuiOptionNative> 子组件进行构建。

<template>
  <TuiSelectNative v-model="value">
    <TuiOptionNative label="选项 A" value="A" />
    <TuiOptionNative label="选项 B" value="B" />
  </TuiSelectNative>
</template>

多选

设置 multiple 属性开启多选模式。

注意

原生 <select multiple> 的表现形式通常是一个展开的列表框（List Box），用户需要按住 Ctrl (Windows) 或 Command (Mac) 键来进行多选。这与 TuiSelect 的 Tag 标签形式完全不同。

<template>
  <TuiSelectNative multiple v-model="selectedValues" :options="options" />
</template>

装饰与状态

可清空 (Clearable)

尽管原生 Select 不支持清空按钮，但组件通过外层封装实现了此功能。 设置 clearable 后，鼠标悬停时会显示删除图标（仅单选模式有效）。

<TuiSelectNative v-model="val" clearable :options="options" />

图标 (Icon)

通过 icon 属性可以在选择框头部添加图标。

<TuiSelectNative icon="tui-icon ti-star" v-model="val" :options="options" />

尺寸 (Size)

支持 large, small 以及默认尺寸。

<TuiSelectNative size="small" v-model="val1" :options="options" />
<TuiSelectNative size="large" v-model="val2" :options="options" />

API 参考

TuiSelectNative Props

属性名	类型	默认值	说明
modelValue	String/Number/Array	-	绑定值。
options	Array	[]	数据源。
valueKey	String	'value'	选项对象中值的键名。
labelKey	String	'label'	选项对象中标签的键名。
disabledKey	String	'disabled'	选项对象中禁用的键名。
multiple	Boolean	false	是否开启多选（原生行为）。
disabled	Boolean	false	是否禁用。
clearable	Boolean	false	是否显示清空按钮。
size	String	null	尺寸。可选：large, small。
icon	String	-	头部图标类名。
placeholder	String	-	占位符（通常作为第一个禁用选项显示）。
width	String/Number	-	宽度。
required	Boolean	false	原生 required 属性。
autofocus	Boolean	false	原生 autofocus 属性。
name	String	-	原生 name 属性。
id	String	-	原生 id 属性。
customClass	String	-	自定义类名。

TuiSelectNative Emits

事件名	说明	回调参数
update:modelValue	绑定值变化时触发。	(value)
change	选项改变时触发。	(value)
focus	获得焦点时触发。	(event)
blur	失去焦点时触发。	(event)
clear	点击清空按钮时触发。	-

TuiSelectNative Methods (Expose)

方法名	说明
focus	使选择框获取焦点。
blur	使选择框失去焦点。
getSelectElement	获取内部原生 select DOM 元素。
syncSelectedState	手动同步选中状态。

TuiOptionNative Props

属性名	类型	默认值	说明
value	String/Number/Boolean	Required	选项的值。
label	String/Number	-	选项的标签。
disabled	Boolean	false	是否禁用。
selected	Boolean	false	是否选中。
customClass	String	-	自定义类名。