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>` 元素

RangeSlider 範圍滑桿

SegmentedButton 分段按鈕