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 属性设置下拉选择的形状。

Item 1

Item 2

Item 1

Item 2

<mdui-select variant="filled" 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 variant="outlined" 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 属性来读取和设置该值。

Item 1

Item 2

Item 3

<mdui-select multiple class="example-multiple">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <mdui-menu-item value="item-3">Item 3</mdui-menu-item>
</mdui-select>

<script>
  // 默认选中 item-1 和 item-2
  const select = document.querySelector(".example-multiple");
  select.value = ["item-1", "item-2"];
</script>

源码

辅助文本

使用 label 属性设置下拉选择上方的标签文本。

Item 1

Item 2

<mdui-select label="Text Field" 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>

源码

使用 placeholder 属性设置未选中值时的占位文本。

Item 1

Item 2

<mdui-select placeholder="Placeholder">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

源码

使用 helper 属性设置下拉选择底部的帮助文本。也可以使用 helper slot 来设置帮助文本。

Item 1

Item 2

Item 1

Item 2

Supporting text

<mdui-select helper="Supporting text">
  <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>
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <span slot="helper" style="color: blue">Supporting text</span>
</mdui-select>

源码

只读模式

通过添加 readonly 属性，可以将下拉选择设置为只读模式。

Item 1

Item 2

<mdui-select readonly 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>

源码

禁用模式

通过添加 disabled 属性，可以禁用下拉选择。

Item 1

Item 2

<mdui-select disabled 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>

源码

可清空

添加 clearable 属性后，当下拉选择有值时，右侧会出现一个清空按钮。

Item 1

Item 2

<mdui-select clearable 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>

源码

也可以通过 clear slot 自定义清空按钮。

Item 1

Item 2

<mdui-select clearable 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-icon slot="clear" name="delete"></mdui-icon>
</mdui-select>

源码

下拉菜单位置

通过 placement 属性，你可以设置下拉菜单的位置。

Item 1

Item 2

<mdui-select placement="top" 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>

源码

文本右对齐

添加 end-aligned 属性，可以使文本右对齐。

Item 1

Item 2

<mdui-select end-aligned 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>

源码

前后文本及图标

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

Item 1

Item 2

Item 1

Item 2

<mdui-select value="item-1" icon="search" end-icon="mic">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<br/><br/>

<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-button-icon slot="icon" icon="search"></mdui-button-icon>
  <mdui-button-icon slot="end-icon" icon="mic"></mdui-button-icon>
</mdui-select>

源码

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

Item 1

Item 2

Item 1

Item 2

$ /100

<mdui-select value="item-1" prefix="$" suffix="/100">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<br/><br/>

<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>
  <span slot="prefix" style="color: blue">$</span>
  <span slot="suffix" style="color: blue">/100</span>
</mdui-select>

源码

API

属性

HTML 属性	JavaScript 属性	类型	默认值
`variant`	`variant`	`'filled' \| 'outlined'`	`'filled'`
选择框的样式。可选值包括： `filled`：带背景色的选择框，视觉效果较强 `outlined`：带边框的选择框，视觉效果较弱
`multiple`	`multiple`	`boolean`	`false`
是否支持多选
`name`	`name`	`string`	`''`
选择框的名称，将与表单数据一起提交
`value`	`value`	`string \| string[]`	`''`
选择框的值，将与表单数据一起提交。如果未指定 `multiple` 属性，该值为字符串；如果指定了 `multiple` 属性，该值为字符串数组。HTML 属性只能设置字符串值；如果需要设置数组值，请通过 JavaScript 属性设置。
	`defaultValue`	`string \| string[]`	`''`
默认选中的值。在重置表单时，将重置为该默认值。该属性只能通过 JavaScript 属性设置
`label`	`label`	`string`	-
标签文本
`placeholder`	`placeholder`	`string`	-
占位符文本
`helper`	`helper`	`string`	-
选择框底部的帮助文本。也可以通过 `slot="helper"` 设置
`clearable`	`clearable`	`boolean`	`false`
是否可以清空选择框
`clear-icon`	`clearIcon`	`string`	-
当选择框可清空时，显示在选择框右侧的清空按钮的 Material Icons 图标名。也可以通过 `slot="clear-icon"` 设置
`placement`	`placement`	`'auto' \| 'bottom' \| 'top'`	`'auto'`
选择框的位置。可选值包括： `auto`：自动判断位置 `bottom`：位于下方 `top`：位于上方
`end-aligned`	`endAligned`	`boolean`	`false`
文本是否右对齐
`prefix`	`prefix`	`string`	-
选择框的前缀文本。仅在聚焦状态，或选择框有值时才会显示。也可以通过 `slot="prefix"` 设置
`suffix`	`suffix`	`string`	-
选择框的后缀文本。仅在聚焦状态，或选择框有值时才会显示。也可以通过 `slot="suffix"` 设置
`icon`	`icon`	`string`	-
选择框的前缀图标的 Material Icons 图标名。也可以通过 `slot="icon"` 设置
`end-icon`	`endIcon`	`string`	-
选择框的后缀图标的 Material Icons 图标名。也可以通过 `slot="end-icon"` 设置
`error-icon`	`errorIcon`	`string`	-
表单字段验证失败时，显示在选择框右侧的 Material Icons 图标名。也可以通过 `slot="error-icon"` 设置
`form`	`form`	`string`	-
关联的 `<form>` 元素。此属性值应为同一页面中的一个 `<form>` 元素的 `id`。如果未指定此属性，则该元素必须是 `<form>` 元素的子元素。通过此属性，你可以将元素放置在页面的任何位置，而不仅仅是 `<form>` 元素的子元素。
`readonly`	`readonly`	`boolean`	`false`
是否为只读状态
`disabled`	`disabled`	`boolean`	`false`
是否为禁用状态
`required`	`required`	`boolean`	`false`
提交表单时，是否必须填写该字段
	`validity`	`ValidityState`	-
表单验证状态对象，具体参见 `ValidityState`
	`validationMessage`	`string`	-
如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
`autofocus`	`autofocus`	`boolean`	`false`
是否在页面加载完成后自动获取焦点
`tabindex`	`tabIndex`	`number`	-
元素在使用 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>` 元素

Menu 菜单

TextField 文本框