Select 选择器

使用

import { KSelect } from "@ksware/ksw-ux";

当选项过多时，使用下拉菜单展示并选择内容。

TIP

在 SSR 场景下，您需要将组件包裹在 <client-only></client-only> 之中 (如: Nuxt) 和 SSG (e.g: VitePress).

基础用法

适用广泛的基础单选 v-model 的值为当前被选中的 k-option 的 value 属性值

有禁用选项

在 k-option 中，设定 disabled 值为 true，即可禁用该选项

禁用状态

禁用整个选择器组件

为 k-select 设置 disabled属性，则整个选择器不可用。

可清空单选

您可以使用清除图标来清除选择。

为 k-select 设置 clearable 属性，则可将选择器清空。 需要注意的是，clearable 属性仅适用于单选。

基础多选

多选选择器使用 tag 组件来展示已选中的选项。

为 k-select 设置 multiple 属性即可启用多选， 此时 v-model 的值为当前选中值所组成的数组。 默认情况下选中值会以 Tag 组件的形式展现， 你也可以设置 collapse-tags 属性将它们合并为一段文字。 您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

自定义模板

你可以自定义如何来渲染每一个选项。

将自定义的 HTML 模板插入 k-option 的 slot 中即可。

自定义下拉菜单的头部

您可以自定义下拉菜单的头部。

使用slot 自定义内容

自定义下拉菜单的底部

您可以自定义下拉菜单的底部。

使用slot 自定义内容

将选项进行分组

你可以为选项进行分组来区分不同的选项

使用 k-option-group 对备选项进行分组，它的 label 属性为分组名

筛选选项

可以利用筛选功能快速查找选项。

为k-select添加filterable属性即可启用搜索功能。 默认情况下，Select 会找出所有 label 属性包含输入值的选项。 如果希望使用其他的搜索逻辑，可以通过传入一个 filter-method 来实现。 filter-method 为一个 Function，它会在输入值发生变化时调用，参数为当前输入值。

远程搜索

输入关键字以从远程服务器中查找数据。

从服务器搜索数据，输入关键字进行查找。为了启用远程搜索，需要将filterable和remote设置为true，同时传入一个remote-method。 remote-method为一个Function，它会在输入值发生变化时调用，参数为当前输入值。 需要注意的是，如果 k-option 是通过 v-for 指令渲染出来的，此时需要为k-option 添加 key 属性， 且其值需具有唯一性，比如这个例子中的 item.value。

创建新的选项

创建并选中未包含在初始选项中的条目。

通过使用 allow-create 属性，用户可以通过输入框创建新项目。 为了使 allow-create 正常工作， filterable 的值必须为 true。 本例还使用了 default-first-option 属性， 在该属性为 true 的情况下，按下回车就可以选中当前选项列表中的第一个选项，无需使用鼠标或键盘方向键进行定位。

使用值键 value-key 属性

创建并选中未包含在初始选项中的条目。

如果 Select 的绑定值为对象类型，请务必指定 value-key 作为它的唯一性标识。

通过使用 value-key 属性，可以正确处理带有重复label的数据。 这样虽然label 是重复的，但任可通过 id 来确认唯一性。

自定义标签

您可以自定义标签。

将自定义的标签插入 k-select 的 slot 中即可。 collapse-tags, collapse-tags-tooltip, max-collapse-tags 在此模式下不生效.

自定义加载

修改加载区域内容

Select API

Select Props

参数名	描述	类型	默认值
model-value / v-model	绑定值	string | number | boolean | object | array	-
multiple	是否多选	boolean	false
value-key	作为 value 唯一标识的键名，绑定值为对象类型时必填	string	value
clearable	是否显示清除图标	boolean	false
size	输入框大小	enum	'base'
placeholder	输入框占位文本	string	-
filterable	是否可筛选	boolean	false
allow-create	是否允许用户创建新条目，只有当 filterable 设置为 true 时才会生效	boolean	false
filter-method	自定义筛选方法	Function	-
remote	是否启用服务端远程搜索	boolean	false
remote-method	远程搜索方法	Function	-
remote-show-suffix	远程搜索方法显示后缀图标	boolean	false
loading	是否显示加载中状态	boolean	false
loading-text	加载中状态文本	string	-
no-match-text	无匹配数据时显示的文本,也可以使用 empty 插槽设置	string	No matching data
no-data-text	无选项时显示的文本,也可以使用 empty 插槽设置	string	No Data
popper-class	选择器下拉菜单的自定义类名	string	''
collapse-tags	多选时是否将选中值按文字的形式展示	boolean	false
collapse-tags-tooltip	当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。要使用此属性，collapse-tags 属性必须设定为true	boolean	false
tag-type	标签类型	enum	info
reserve-keyword	当 multiple 和 filterable 被设置为true时，是否在选中一个选项后保留当前的搜索关键词	boolean	true
default-first-option	是否在输入框按下回车时，选择第一个匹配项。需配合 filterable 或 remote 使用	boolean	false
teleported	是否将下拉列表插入至 body 元素	boolean	true
persistent	当下拉选择器未被激活并且 persistent 设置为 false ，选择器会被删除	boolean	true
automatic-dropdown	对于不可搜索的输入框，是否在输入框获得焦点后自动弹出选项菜单	boolean	false
clear-icon	自定义清除图标	string | Component	-
fit-input-width	是否将下拉选择器的宽度调整为输入框的宽度	boolean	true
suffix-icon	自定义输入框后缀图标	string | Component	-
placement	下拉列表出现的位置	enum	'bottom-start'

Select Events

事件名	描述	类型
blur	输入框失去焦点时触发	Function
focus	输入框获得焦点时触发	Function
change	选中值发生变化时触发	Function
visible-change	下拉列表显示/隐藏时触发	Function
clear	点击清除图标时触发	Function
remove-tag	多选模式下移除标签时触发	Function

Select Slots

插槽名	描述	参数
default	option组件列表	-
header	下拉列表头部内容	-
footer	下拉列表底部内容	-
prefix	KSelect组件头部内容	-
empty	无选项时显示的内容	-
tag	自定义标签内容	-
loading	自定义loading内容	-
label	自定义标签内容	-

Select Methods

方法名	描述	类型
blur	使输入框失去焦点	Function
focus	使输入框获得焦点	Function

Option API

Option Props

参数名	描述	类型	默认值
value	选项的值	string | number | boolean | object	-
label	选项的标签，若不设置则默认与value相同	string | number	-
disabled	是否禁用该选项	boolean	false

Option Slots

插槽名	描述	参数
default	默认插槽内容	-

OptionGroup API

OptionGroup Props

参数名	描述	类型	默认值
label	分组的名称	string	-
disabled	是否将该分组下所有选项置为禁用	boolean	false

OptionGroup Slots

插槽名	描述	参数
default	默认插槽内容	-