Checkbox核取方塊

核取方塊讓使用者可以從一組選項中選取一個或多個項目，或切換單一選項的開/關狀態。

使用方法

按需引入元件：

import 'mdui/components/checkbox.js';

按需引入元件的 TypeScript 型別：

import type { Checkbox } from 'mdui/components/checkbox.js';

使用範例：

Checkbox

<mdui-checkbox>Checkbox</mdui-checkbox>

範例

選取狀態

核取方塊被選取時，checked 屬性值為 true。加上 checked 屬性可讓核取方塊預設處於選取狀態。

Checkbox

<mdui-checkbox checked>Checkbox</mdui-checkbox>

原始碼

禁用狀態

加上 disabled 屬性可禁用核取方塊。

Checkbox

<mdui-checkbox disabled>Checkbox</mdui-checkbox>
<mdui-checkbox disabled checked>Checkbox</mdui-checkbox>

原始碼

不確定狀態

加上 indeterminate 屬性表示核取方塊處於不確定狀態。

Checkbox

<mdui-checkbox indeterminate>Checkbox</mdui-checkbox>

原始碼

圖示

透過設定 unchecked-icon、checked-icon、indeterminate-icon 屬性，可分別設定未選取、選取、不確定狀態時的核取方塊的 Material Icons 圖示。也可透過 unchecked-icon、checked-icon、indeterminate-icon slot 進行設定。

Checkbox

<mdui-checkbox
  unchecked-icon="radio_button_unchecked"
  checked-icon="check_circle"
  indeterminate-icon="playlist_add_check_circle"
>Checkbox</mdui-checkbox>

<mdui-checkbox
  indeterminate
  unchecked-icon="radio_button_unchecked"
  checked-icon="check_circle"
  indeterminate-icon="playlist_add_check_circle"
>Checkbox</mdui-checkbox>

<br/>

<mdui-checkbox>
  <mdui-icon slot="unchecked-icon" name="radio_button_unchecked"></mdui-icon>
  <mdui-icon slot="checked-icon" name="check_circle"></mdui-icon>
  <mdui-icon slot="indeterminate-icon" name="playlist_add_check_circle"></mdui-icon>
  Checkbox
</mdui-checkbox>

<mdui-checkbox indeterminate>
  <mdui-icon slot="unchecked-icon" name="radio_button_unchecked"></mdui-icon>
  <mdui-icon slot="checked-icon" name="check_circle"></mdui-icon>
  <mdui-icon slot="indeterminate-icon" name="playlist_add_check_circle"></mdui-icon>
  Checkbox
</mdui-checkbox>

原始碼

API

屬性

HTML 屬性	JavaScript 屬性	型別	預設值
`disabled`	`disabled`	`boolean`	`false`
是否為停用狀態
`checked`	`checked`	`boolean`	`false`
是否為選取狀態
	`defaultChecked`	`boolean`	`false`
預設選取狀態。在重設表單時，將恢復為此狀態。此屬性只能透過 JavaScript 屬性設定
`indeterminate`	`indeterminate`	`boolean`	`false`
是否處於不確定狀態
`required`	`required`	`boolean`	`false`
送出表單時，是否必須選取此核取方塊
`form`	`form`	`string`	-
關聯的 `<form>` 元素。此屬性值應為同一頁面中的一個 `<form>` 元素的 `id`。若未指定此屬性，則該元素必須是 `<form>` 元素的子元素。透過此屬性，你可以將元素放置在頁面的任何位置，而不僅僅是 `<form>` 元素的子元素。
`name`	`name`	`string`	`''`
核取方塊名稱，將與表單資料一起送出
`value`	`value`	`string`	`'on'`
核取方塊的值，將與表單資料一起送出
`unchecked-icon`	`uncheckedIcon`	`string`	-
未選取狀態的 Material Icons 圖示名。也可以透過 `slot="unchecked-icon"` 設定
`checked-icon`	`checkedIcon`	`string`	-
選取狀態的 Material Icons 圖示名。也可以透過 `slot="checked-icon"` 設定
`indeterminate-icon`	`indeterminateIcon`	`string`	-
不確定狀態的 Material Icons 圖示名。也可以透過 `slot="indeterminate-icon"` 設定
	`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`
選取狀態變更時觸發
`input`
選取狀態變更時觸發
`invalid`
表單欄位驗證未通過時觸發

Slots

名稱
預設
核取方塊文字
`unchecked-icon`
未選取狀態的圖示
`checked-icon`
選取狀態的圖示
`indeterminate-icon`
不確定狀態的圖示

CSS Parts

名稱
`control`
左側圖示容器
`unchecked-icon`
未選取狀態的圖示
`checked-icon`
選取狀態的圖示
`indeterminate-icon`
不確定狀態的圖示
`label`
核取方塊文字

Card 卡片

Chip 標籤