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';

使用示例:

Item 1 Item 2
<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>

示例

形状

通过 variant 属性设置下拉选择的形状。

多选支持

下拉选择默认为单选,<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 属性,可以使文本右对齐。

前后文本及图标

通过设置 iconend-icon 属性,可以在下拉选择的左侧和右侧添加 Material Icons 图标。你也可以通过 iconend-icon slot 在下拉选择的左侧和右侧添加元素。

通过设置 prefixsuffix 属性,可以在下拉选择的左侧和右侧添加文本。也可以通过 prefixsuffix slot 在下拉选择的左侧和右侧添加文本元素。这些文本只有在下拉选择聚焦或有值时才会显示。

API

属性

HTML 属性JavaScript 属性Reflect类型默认值
variantvariant'filled' | 'outlined''filled'

选择框的样式。可选值包括:

  • filled:带背景色的选择框,视觉效果较强
  • outlined:带边框的选择框,视觉效果较弱
multiplemultiplebooleanfalse

是否支持多选

namenamestring''

选择框的名称,将与表单数据一起提交

valuevaluestring | string[]''

选择框的值,将与表单数据一起提交。

如果未指定 multiple 属性,该值为字符串;如果指定了 multiple 属性,该值为字符串数组。HTML 属性只能设置字符串值;如果需要设置数组值,请通过 JavaScript 属性设置。

defaultValuestring | string[]''

默认选中的值。在重置表单时,将重置为该默认值。该属性只能通过 JavaScript 属性设置

labellabelstring-

标签文本

placeholderplaceholderstring-

占位符文本

helperhelperstring-

选择框底部的帮助文本。也可以通过 slot="helper" 设置

clearableclearablebooleanfalse

是否可以清空选择框

clear-iconclearIconstring-

当选择框可清空时,显示在选择框右侧的清空按钮的 Material Icons 图标名。也可以通过 slot="clear-icon" 设置

placementplacement'auto' | 'bottom' | 'top''auto'

选择框的位置。可选值包括:

  • auto:自动判断位置
  • bottom:位于下方
  • top:位于上方
end-alignedendAlignedbooleanfalse

文本是否右对齐

prefixprefixstring-

选择框的前缀文本。仅在聚焦状态,或选择框有值时才会显示。也可以通过 slot="prefix" 设置

suffixsuffixstring-

选择框的后缀文本。仅在聚焦状态,或选择框有值时才会显示。也可以通过 slot="suffix" 设置

iconiconstring-

选择框的前缀图标的 Material Icons 图标名。也可以通过 slot="icon" 设置

end-iconendIconstring-

选择框的后缀图标的 Material Icons 图标名。也可以通过 slot="end-icon" 设置

error-iconerrorIconstring-

表单字段验证失败时,显示在选择框右侧的 Material Icons 图标名。也可以通过 slot="error-icon" 设置

formformstring-

关联的 <form> 元素。此属性值应为同一页面中的一个 <form> 元素的 id

如果未指定此属性,则该元素必须是 <form> 元素的子元素。通过此属性,你可以将元素放置在页面的任何位置,而不仅仅是 <form> 元素的子元素。

readonlyreadonlybooleanfalse

是否为只读状态

disableddisabledbooleanfalse

是否为禁用状态

requiredrequiredbooleanfalse

提交表单时,是否必须填写该字段

validityValidityState-

表单验证状态对象,具体参见 ValidityState

validationMessagestring-

如果表单验证未通过,此属性将包含提示信息。如果验证通过,此属性将为空字符串

autofocusautofocusbooleanfalse

是否在页面加载完成后自动获取焦点

tabindextabIndexnumber-

元素在使用 Tab 键切换焦点时的顺序

方法

名称参数返回值
checkValidity
boolean

检查表单字段是否通过验证。如果未通过,返回 false 并触发 invalid 事件;如果通过,返回 true

reportValidity
boolean

检查表单字段是否通过验证。如果未通过,返回 false 并触发 invalid 事件;如果通过,返回 true

如果验证未通过,还会在组件上显示验证失败的提示。

setCustomValidity
  • message: string
void

设置自定义的错误提示文本。只要这个文本不为空,就表示字段未通过验证

click
void

模拟鼠标点击元素

focus
  • options: FocusOptions (可选)
void

将焦点设置到当前元素。

可以传入一个对象作为参数,该对象的属性包括:

  • preventScroll:默认情况下,元素获取焦点后,页面会滚动以将该元素滚动到视图中。如果不希望页面滚动,可以将此属性设置为 true
blur
void

移除当前元素的焦点

事件

名称
focus

获得焦点时触发

blur

失去焦点时触发

change

选中的值变更时触发

invalid

表单字段验证未通过时触发

clear

在点击由 clearable 属性生成的清空按钮时触发。可以通过调用 event.preventDefault() 阻止清空选择框

Slots

名称
默认

<mdui-menu-item> 元素

icon

左侧图标

end-icon

右侧图标

error-icon

验证失败状态的右侧图标

prefix

左侧文本

suffix

右侧文本

clear-button

清空按钮

clear-icon

清空按钮中的图标

helper

底部的帮助文本

CSS Parts

名称
chips

多选时,放置选中值对应的 chip 的容器

chip

多选时,每一个选中的值对应的 chip

chip__button

chip 内部的 <button> 元素

chip__label

chip 内部的文本

chip__delete-icon

chip 内部的删除图标

text-field

文本框,即 <mdui-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 内部的 <input> 元素

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

下拉菜单,即 <mdui-menu> 元素

MDUI文档English简体中文亮色模式暗色模式跟随系统
预设颜色
自选颜色
从壁纸提取颜色
请选择一张壁纸
开发指南
概述 安装 快速入门 TypeScript 支持 IDE 支持 本地化 常见问题
样式
暗色模式 动态配色 文章排版 设计令牌
与框架集成
React Vue Angular
组件
Button 按钮ButtonIcon 图标按钮Fab 浮动操作按钮SegmentedButton 分段按钮Chip 纸片Card 卡片Checkbox 复选框Radio 单选框Switch 开关切换Slider 滑块RangeSlider 范围滑块List 列表Collapse 折叠面板Tabs 选项卡Dropdown 下拉组件Menu 菜单Select 选择框TextField 文本框LinearProgress 线性进度指示器CircularProgress 圆形进度指示器Dialog 对话框Divider 分割线Avatar 头像Badge 徽标Icon 图标Tooltip 工具提示Snackbar 消息条NavigationBar 底部导航栏NavigationDrawer 侧边抽屉栏NavigationRail 侧边导航栏BottomAppBar 底部应用栏TopAppBar 顶部应用栏Layout 布局
工具函数
jq 工具库 dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
独立包
@mdui/icons 图标组件库