Select 选择框
下拉选择组件在一个下拉菜单中提供多种选项,方便用户快速选择所需内容。
本页面主要介绍 <mdui-select>
组件的使用方法,关于下拉菜单项的用法,请参见 <mdui-menu-item>
。
使用方法
按需导入组件:
import 'mdui/components/select.js';
import 'mdui/components/menu-item.js';
按需导入组件的 TypeScript 类型:
import type { Select } from 'mdui/components/select.js';
import type { MenuItem } from 'mdui/components/menu-item.js';
使用示例:
<mdui-select value="item-1">
<mdui-menu-item value="item-1">Item 1</mdui-menu-item>
<mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>
多选支持
下拉选择默认为单选,<mdui-select>
组件的 value
值即为当前选中的 <mdui-menu-item>
的 value
值。
添加 multiple
属性可以使下拉选择支持多选。此时 <mdui-select>
的 value
值为当前选中的 <mdui-menu-item>
的 value
的值组成的数组。
注意:在支持多选时,<mdui-select>
的 value
值为数组,只能通过 JavaScript 属性来读取和设置该值。
辅助文本
使用 label
属性设置下拉选择上方的标签文本。
使用 placeholder
属性设置未选中值时的占位文本。
使用 helper
属性设置下拉选择底部的帮助文本。也可以使用 helper
slot 来设置帮助文本。
只读模式
通过添加 readonly
属性,可以将下拉选择设置为只读模式。
禁用模式
通过添加 disabled
属性,可以禁用下拉选择。
可清空
添加 clearable
属性后,当下拉选择有值时,右侧会出现一个清空按钮。
也可以通过 clear
slot 自定义清空按钮。
下拉菜单位置
通过 placement
属性,你可以设置下拉菜单的位置。
文本右对齐
添加 end-aligned
属性,可以使文本右对齐。
前后文本及图标
通过设置 icon
和 end-icon
属性,可以在下拉选择的左侧和右侧添加 Material Icons 图标。你也可以通过 icon
和 end-icon
slot 在下拉选择的左侧和右侧添加元素。
通过设置 prefix
和 suffix
属性,可以在下拉选择的左侧和右侧添加文本。也可以通过 prefix
和 suffix
slot 在下拉选择的左侧和右侧添加文本元素。这些文本只有在下拉选择聚焦或有值时才会显示。
API
属性
HTML 属性 | JavaScript 属性 | Reflect | 类型 | 默认值 |
---|---|---|---|---|
variant | variant | 'filled' | 'outlined' | 'filled' | |
选择框的样式。可选值包括:
| ||||
multiple | multiple | boolean | false | |
是否支持多选 | ||||
name | name | string | '' | |
选择框的名称,将与表单数据一起提交 | ||||
value | value | string | string[] | '' | |
选择框的值,将与表单数据一起提交。 如果未指定 | ||||
defaultValue | string | string[] | '' | ||
默认选中的值。在重置表单时,将重置为该默认值。该属性只能通过 JavaScript 属性设置 | ||||
label | label | string | - | |
标签文本 | ||||
placeholder | placeholder | string | - | |
占位符文本 | ||||
helper | helper | string | - | |
选择框底部的帮助文本。也可以通过 | ||||
clearable | clearable | boolean | false | |
是否可以清空选择框 | ||||
clear-icon | clearIcon | string | - | |
当选择框可清空时,显示在选择框右侧的清空按钮的 Material Icons 图标名。也可以通过 | ||||
placement | placement | 'auto' | 'bottom' | 'top' | 'auto' | |
选择框的位置。可选值包括:
| ||||
end-aligned | endAligned | boolean | false | |
文本是否右对齐 | ||||
prefix | prefix | string | - | |
选择框的前缀文本。仅在聚焦状态,或选择框有值时才会显示。也可以通过 | ||||
suffix | suffix | string | - | |
选择框的后缀文本。仅在聚焦状态,或选择框有值时才会显示。也可以通过 | ||||
icon | icon | string | - | |
选择框的前缀图标的 Material Icons 图标名。也可以通过 | ||||
end-icon | endIcon | string | - | |
选择框的后缀图标的 Material Icons 图标名。也可以通过 | ||||
error-icon | errorIcon | string | - | |
表单字段验证失败时,显示在选择框右侧的 Material Icons 图标名。也可以通过 | ||||
form | form | string | - | |
关联的 如果未指定此属性,则该元素必须是 | ||||
readonly | readonly | boolean | false | |
是否为只读状态 | ||||
disabled | disabled | boolean | false | |
是否为禁用状态 | ||||
required | required | boolean | false | |
提交表单时,是否必须填写该字段 | ||||
validity | ValidityState | - | ||
表单验证状态对象,具体参见 | ||||
validationMessage | string | - | ||
如果表单验证未通过,此属性将包含提示信息。如果验证通过,此属性将为空字符串 | ||||
autofocus | autofocus | boolean | false | |
是否在页面加载完成后自动获取焦点 | ||||
tabindex | tabIndex | number | - | |
元素在使用 Tab 键切换焦点时的顺序 |
方法
名称 | 参数 | 返回值 |
---|---|---|
checkValidity | boolean | |
检查表单字段是否通过验证。如果未通过,返回 | ||
reportValidity | boolean | |
检查表单字段是否通过验证。如果未通过,返回 如果验证未通过,还会在组件上显示验证失败的提示。 | ||
setCustomValidity |
| void |
设置自定义的错误提示文本。只要这个文本不为空,就表示字段未通过验证 | ||
click | void | |
模拟鼠标点击元素 | ||
focus |
| void |
将焦点设置到当前元素。 可以传入一个对象作为参数,该对象的属性包括:
| ||
blur | void | |
移除当前元素的焦点 |
Slots
名称 |
---|
默认 |
|
icon |
左侧图标 |
end-icon |
右侧图标 |
error-icon |
验证失败状态的右侧图标 |
prefix |
左侧文本 |
suffix |
右侧文本 |
clear-button |
清空按钮 |
clear-icon |
清空按钮中的图标 |
helper |
底部的帮助文本 |
CSS Parts
名称 |
---|
chips |
多选时,放置选中值对应的 chip 的容器 |
chip |
多选时,每一个选中的值对应的 chip |
chip__button |
chip 内部的 |
chip__label |
chip 内部的文本 |
chip__delete-icon |
chip 内部的删除图标 |
text-field |
文本框,即 |
text-field__container |
text-field 内部的文本框容器 |
text-field__icon |
text-field 内部的左侧图标 |
text-field__end-icon |
text-field 内部的右侧图标 |
text-field__error-icon |
text-field 内部的验证失败状态的右侧图标 |
text-field__prefix |
text-field 内部的左侧文本 |
text-field__suffix |
text-field 内部的右侧文本 |
text-field__label |
text-field 内部的标签文本 |
text-field__input |
text-field 内部的 |
text-field__clear-button |
text-field 内部的清空按钮 |
text-field__clear-icon |
text-field 内部的清空按钮中的图标 |
text-field__supporting |
text-field 内部的底部辅助信息容器,包括 helper 和 error |
text-field__helper |
text-field 内部的底部帮助文本 |
text-field__error |
text-field 内部的底部错误描述文本 |
menu |
下拉菜单,即 |