SegmentedButton分段按鈕

分段按鈕元件封裝了一組按鈕，用於提供選項、切換視圖或對元素進行排序等。

使用方法

按需引入元件：

import 'mdui/components/segmented-button-group.js';
import 'mdui/components/segmented-button.js';

按需引入元件的 TypeScript 型別：

import type { SegmentedButtonGroup } from 'mdui/components/segmented-button-group.js';
import type { SegmentedButton } from 'mdui/components/segmented-button.js';

使用範例：

Day

Week

Month

<mdui-segmented-button-group>
  <mdui-segmented-button>Day</mdui-segmented-button>
  <mdui-segmented-button>Week</mdui-segmented-button>
  <mdui-segmented-button>Month</mdui-segmented-button>
</mdui-segmented-button-group>

範例

全寬顯示

在 <mdui-segmented-button-group> 元素上加上 full-width 屬性，可使元件佔滿整個寬度。

Day

Week

Month

<mdui-segmented-button-group full-width>
  <mdui-segmented-button>Day</mdui-segmented-button>
  <mdui-segmented-button>Week</mdui-segmented-button>
  <mdui-segmented-button>Month</mdui-segmented-button>
</mdui-segmented-button-group>

原始碼

單選模式

在 <mdui-segmented-button-group> 元素上指定 selects 屬性為 single，即可做成單選模式。此時 <mdui-segmented-button-group> 的 value 屬性值即為目前選取的 <mdui-segmented-button> 的 value 屬性的值。

Day

Week

Month

Day

Week

Month

<mdui-segmented-button-group selects="single">
  <mdui-segmented-button value="day">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">Week</mdui-segmented-button>
  <mdui-segmented-button value="month">Month</mdui-segmented-button>
</mdui-segmented-button-group>

<mdui-segmented-button-group selects="single" value="week">
  <mdui-segmented-button value="day">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">Week</mdui-segmented-button>
  <mdui-segmented-button value="month">Month</mdui-segmented-button>
</mdui-segmented-button-group>

原始碼

多選模式

在 <mdui-segmented-button-group> 元素上指定 selects 屬性為 multiple，即可做成多選模式。此時 <mdui-segmented-button-group> 的 value 屬性值為目前選取的 <mdui-segmented-button> 的 value 屬性的值所組成的陣列。

注意：在多選模式下，<mdui-segmented-button-group> 的 value 屬性值為陣列，只能透過 JavaScript 屬性來讀取和設定該值。

Day

Week

Month

Day

Week

Month

<mdui-segmented-button-group selects="multiple">
  <mdui-segmented-button value="day">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">Week</mdui-segmented-button>
  <mdui-segmented-button value="month">Month</mdui-segmented-button>
</mdui-segmented-button-group>

<mdui-segmented-button-group selects="multiple" class="demo-multiple">
  <mdui-segmented-button value="day">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">Week</mdui-segmented-button>
  <mdui-segmented-button value="month">Month</mdui-segmented-button>
</mdui-segmented-button-group>

<script>
  // 設定預設選取 week 和 month
  const group = document.querySelector(".demo-multiple");
  group.value = ["week", "month"];
</script>

原始碼

圖示

在 <mdui-segmented-button> 元素上，透過設定 icon 和 end-icon 屬性，可以在按鈕的左側和右側加入 Material Icons 圖示。另外，也可以透過 icon 和 end-icon slot 在按鈕的左側和右側加入元素。

Day

Week

Month

<mdui-segmented-button-group>
  <mdui-segmented-button icon="search">Day</mdui-segmented-button>
  <mdui-segmented-button end-icon="arrow_forward">Week</mdui-segmented-button>
  <mdui-segmented-button>
    Month
    <mdui-icon slot="icon" name="downloading"></mdui-icon>
    <mdui-icon slot="end-icon" name="attach_file"></mdui-icon>
  </mdui-segmented-button>
</mdui-segmented-button-group>

原始碼

在 <mdui-segmented-button> 元素上，透過加上 selected-icon 屬性，可以設定選取狀態的 Material Icons 圖示。也可以透過 selected-icon slot 進行設定。

Day

Week

<mdui-segmented-button-group selects="multiple">
  <mdui-segmented-button value="day" selected-icon="cloud_done">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">
    <mdui-icon slot="selected-icon" name="cloud_done"></mdui-icon>
    Week
  </mdui-segmented-button>
</mdui-segmented-button-group>

原始碼

連結

在 <mdui-segmented-button> 元素上，透過設定 href 屬性，即可將按鈕轉換為連結。此時，還可使用下列與連結相關的屬性：download、target、rel。

Link

Week

Month

<mdui-segmented-button-group>
  <mdui-segmented-button href="https://www.mdui.org" target="_blank">Link</mdui-segmented-button>
  <mdui-segmented-button>Week</mdui-segmented-button>
  <mdui-segmented-button>Month</mdui-segmented-button>
</mdui-segmented-button-group>

原始碼

停用及載入中狀態

在 <mdui-segmented-button-group> 元素上，透過加上 disabled 屬性，即可停用整個分段按鈕組。

Day

Week

Month

<mdui-segmented-button-group disabled>
  <mdui-segmented-button>Day</mdui-segmented-button>
  <mdui-segmented-button>Week</mdui-segmented-button>
  <mdui-segmented-button>Month</mdui-segmented-button>
</mdui-segmented-button-group>

原始碼

在 <mdui-segmented-button> 元素上，透過加上 disabled 屬性，即可停用特定按鈕；透過加上 loading 屬性，則可為特定按鈕加入載入中狀態。

Day

Week

Month

Year

<mdui-segmented-button-group>
  <mdui-segmented-button>Day</mdui-segmented-button>
  <mdui-segmented-button disabled>Week</mdui-segmented-button>
  <mdui-segmented-button loading>Month</mdui-segmented-button>
  <mdui-segmented-button disabled loading>Year</mdui-segmented-button>
</mdui-segmented-button-group>

原始碼

`mdui-segmented-button-group` API

屬性

HTML 屬性	JavaScript 屬性	型別	預設值
`full-width`	`fullWidth`	`boolean`	`false`
是否填滿父元素寬度
`selects`	`selects`	`'single' \| 'multiple'`	-
分段按鈕的可選取狀態，預設為不可選取。可選值包括： `single`：單選 `multiple`：多選
`disabled`	`disabled`	`boolean`	`false`
是否為停用狀態
`required`	`required`	`boolean`	`false`
送出表單時，是否必須選取
`form`	`form`	`string`	-
關聯的 `<form>` 元素。此屬性值應為同一頁面中的一個 `<form>` 元素的 `id`。若未指定此屬性，則該元素必須是 `<form>` 元素的子元素。透過此屬性，你可以將元素放置在頁面的任何位置，而不僅僅是 `<form>` 元素的子元素。
`name`	`name`	`string`	`''`
送出表單時的名稱，將與表單資料一起送出
`value`	`value`	`string \| string[]`	`''`
目前選取的 `<mdui-segmented-button>` 的值。 Note：該屬性的 HTML 屬性始終為字串，且僅在 `selects="single"` 時可以透過 HTML 屬性設定初始值。該屬性的 JavaScript 屬性值在 `selects="single"` 時為字串，在 `selects="multiple"` 時為字串陣列。所以，在 `selects="multiple"` 時，如果要修改該值，只能透過修改 JavaScript 屬性值來實作。
	`defaultValue`	`string \| string[]`	`''`
預設選取的值。在重設表單時，將重設為該預設值。該屬性只能透過 JavaScript 屬性設定
	`validity`	`ValidityState`	-
表單驗證狀態物件，具體參見 `ValidityState`
	`validationMessage`	`string`	-
如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串

方法

名稱	參數	回傳值
`checkValidity`		`boolean`
檢查表單欄位是否通過驗證。如果未通過，回傳 `false` 並觸發 `invalid` 事件；如果通過，回傳 `true`
`reportValidity`		`boolean`
檢查表單欄位是否通過驗證。如果未通過，回傳 `false` 並觸發 `invalid` 事件；如果通過，回傳 `true`。如果驗證未通過，還會在元件上顯示驗證失敗的提示。
`setCustomValidity`	`message: string`	`void`
設定自訂的錯誤提示文字。只要這個文字不為空，就表示欄位未通過驗證

事件

名稱
`change`
選取的值變更時觸發
`invalid`
表單欄位驗證未通過時觸發

Slots

名稱
預設
`<mdui-segmented-button>` 元件

CSS 自訂屬性

名稱
`--shape-corner`
元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌

`mdui-segmented-button` API

屬性

HTML 屬性	JavaScript 屬性	型別	預設值
`icon`	`icon`	`string`	-
左側的 Material Icons 圖示名。也可以透過 `slot="icon"` 設定
`end-icon`	`endIcon`	`string`	-
右側的 Material Icons 圖示名。也可以透過 `slot="end-icon"` 設定
`selected-icon`	`selectedIcon`	`string`	-
選取狀態的 Material Icons 圖示名。也可以透過 `slot="selected-icon"` 設定
`href`	`href`	`string`	-
連結的目標網址。若設定此屬性，元件內部會渲染為 `<a>` 元素，並可使用連結相關的屬性。
`download`	`download`	`string`	-
下載目標。 Note：僅在設定了 `href` 屬性時，此屬性才有效。
`target`	`target`	`'_blank' \| '_parent' \| '_self' \| '_top'`	-
連結的開啟方式。可選值包括： `_blank`：在新視窗中開啟連結 `_parent`：在父框架中開啟連結 `_self`：預設。在目前框架中開啟連結 `_top`：在整個視窗中開啟連結 Note：僅在設定了 `href` 屬性時，此屬性才有效。
`rel`	`rel`	`'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'`	-
目前文件與被連結文件之間的關係。可選值包括： `alternate`：目前文件的替代版本 `author`：目前文件或文章的作者 `bookmark`：永久連結到最近的祖先章節 `external`：引用的文件與目前文件不在同一站點 `help`：連結到相關的說明文件 `license`：目前文件的主要內容由被引用文件的版權許可覆蓋 `me`：目前文件代表連結內容的所有者 `next`：目前文件是系列中的一部分，被引用的文件是系列的下一個文件 `nofollow`：目前文件的作者或發布者不認可被引用的文件 `noreferrer`：不包含 `Referer` 標頭。類似於 `noopener` 的效果 `opener`：如果超連結會建立一個頂級瀏覽上下文（即 `target` 屬性值為 `_blank`），則建立一個輔助瀏覽上下文 `prev`：目前文件是系列的一部分，被引用的文件是系列的上一個文件 `search`：提供一個資源連結，可用於搜尋目前檔案及其相關頁面 `tag`：提供一個適用於目前文件的標籤（由給定位址識別） Note：僅在指定了 `href` 屬性時可用。
`autofocus`	`autofocus`	`boolean`	`false`
是否在頁面載入完成後自動取得焦點
`tabindex`	`tabIndex`	`number`	-
元素在使用 Tab 鍵切換焦點時的順序
`disabled`	`disabled`	`boolean`	`false`
是否停用
`loading`	`loading`	`boolean`	`false`
是否處於載入中狀態
`name`	`name`	`string`	`''`
按鈕名稱，會與表單資料一起送出。 Note：僅在未設定 `href` 屬性時，此屬性才有效。
`value`	`value`	`string`	`''`
按鈕初始值，會與表單資料一起送出。 Note：僅在未設定 `href` 屬性時，此屬性才有效。
`type`	`type`	`'submit' \| 'reset' \| 'button'`	`'button'`
按鈕的類型。預設類型為 `button`。可選類型包括： `submit`：點擊按鈕會送出表單資料到伺服器 `reset`：點擊按鈕會將表單中的所有欄位重設為初始值 `button`：此類型的按鈕沒有預設行為 Note：僅在未指定 `href` 屬性時，此屬性才有效。
`form`	`form`	`string`	-
關聯的 `<form>` 元素。此屬性值應為同一頁面中的一個 `<form>` 元素的 `id`。若未指定此屬性，則該元素必須是 `<form>` 元素的子元素。透過此屬性，你可以將元素放置在頁面的任何位置，而不僅僅是 `<form>` 元素的子元素。 Note：僅在未指定 `href` 屬性時，此屬性才有效。
`formaction`	`formAction`	`string`	-
指定送出表單的 URL。若指定了此屬性，將覆蓋 `<form>` 元素的 `action` 屬性。 Note：僅在未指定 `href` 屬性且 `type="submit"` 時，此屬性才有效。
`formenctype`	`formEnctype`	`'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'`	-
指定送出表單到伺服器的內容類型。可選值包括： `application/x-www-form-urlencoded`：未指定該屬性時的預設值 `multipart/form-data`：當表單包含 `<input type="file">` 元素時使用 `text/plain`：HTML5 新增，用於除錯若指定了此屬性，將覆蓋 `<form>` 元素的 `enctype` 屬性。 Note：僅在未指定 `href` 屬性且 `type="submit"` 時，此屬性才有效。
`formmethod`	`formMethod`	`'post' \| 'get'`	-
指定送出表單時使用的 HTTP 方法。可選值包括： `post`：表單資料包含在表單內容中，送出到伺服器 `get`：表單資料以 `?` 作為分隔符附加到表單的 URI 屬性中，產生的 URI 送出到伺服器。當表單沒有副作用，並且僅包含 ASCII 字元時，使用此方法若設定了此屬性，將覆蓋 `<form>` 元素的 `method` 屬性。 Note：僅在未設定 `href` 屬性且 `type="submit"` 時，此屬性才有效。
`formnovalidate`	`formNoValidate`	`boolean`	`false`
若設定了此屬性，表單送出時將不執行表單驗證。若設定了此屬性，將覆蓋 `<form>` 元素的 `novalidate` 屬性。 Note：僅在未設定 `href` 屬性且 `type="submit"` 時，此屬性才有效。
`formtarget`	`formTarget`	`'_self' \| '_blank' \| '_parent' \| '_top'`	-
送出表單後接收到的回應應顯示在何處。可選值包括： `_self`：預設，在目前框架中開啟 `_blank`：在新視窗中開啟 `_parent`：在父框架中開啟 `_top`：在整個視窗中開啟若設定了此屬性，將覆蓋 `<form>` 元素的 `target` 屬性。 Note：僅在未設定 `href` 屬性且 `type="submit"` 時，此屬性才有效。
	`validity`	`ValidityState`	-
表單驗證狀態物件，具體參見 `ValidityState`
	`validationMessage`	`string`	-
如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串

方法

名稱	參數	回傳值
`click`		`void`
模擬滑鼠點擊元素
`focus`	`options: FocusOptions` (選配)	`void`
將焦點設定到目前元素。可以傳入一個物件作為引數，該物件的屬性包括： `preventScroll`：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 `true`。
`blur`		`void`
移除目前元素的焦點
`checkValidity`		`boolean`
檢查表單欄位是否通過驗證。如果未通過，回傳 `false` 並觸發 `invalid` 事件；如果通過，回傳 `true`
`reportValidity`		`boolean`
檢查表單欄位是否通過驗證。如果未通過，回傳 `false` 並觸發 `invalid` 事件；如果通過，回傳 `true`。如果驗證未通過，還會在元件上顯示驗證失敗的提示。
`setCustomValidity`	`message: string`	`void`
設定自訂的錯誤提示文字。只要這個文字不為空，就表示欄位未通過驗證

事件

名稱
`focus`
取得焦點時觸發
`blur`
失去焦點時觸發
`invalid`
表單欄位驗證未通過時觸發

Slots

名稱
預設
分段按鈕項目的文字內容
`icon`
分段按鈕項目的左側圖示
`selected-icon`
選取狀態的左側圖示
`end-icon`
分段按鈕項目的右側圖示

CSS Parts

名稱
`button`
內部的 `<button>` 或 `<a>` 元素
`icon`
左側的圖示
`selected-icon`
選取狀態的左側圖示
`end-icon`
右側的圖示
`label`
文字內容
`loading`
載入中狀態的 `<mdui-circular-progress>` 元素

Select 選擇框

Slider 滑桿