Chip標籤

標籤元件用來協助使用者輸入資訊、選擇、篩選內容或執行相關操作。

使用方法

按需引入元件：

import 'mdui/components/chip.js';

按需引入元件的 TypeScript 型別：

import type { Chip } from 'mdui/components/chip.js';

使用範例：

Chip

<mdui-chip>Chip</mdui-chip>

範例

形狀

使用 variant 屬性設定標籤的形狀。標籤共有 4 種形狀，可根據用途選擇：

assist：用於顯示與目前上下文相關的輔助操作。例如，在點餐頁面提供分享、收藏等功能。
filter：用於對內容進行篩選。例如，在搜尋結果頁面對搜尋結果進行過濾。
input：用於表示使用者輸入的資訊片段。例如，Gmail 中「收件人」欄位裡的聯絡人。
suggestion：用於提供動態產生的推薦資訊，以簡化使用者操作。例如，在聊天應用中預測使用者可能想傳送的訊息，供使用者選擇。

Assist

Filter

Input

Suggestion

<mdui-chip variant="assist">Assist</mdui-chip>
<mdui-chip variant="filter">Filter</mdui-chip>
<mdui-chip variant="input">Input</mdui-chip>
<mdui-chip variant="suggestion">Suggestion</mdui-chip>

原始碼

陰影

加上 elevated 屬性可讓標籤具有陰影。

Chip

<mdui-chip elevated>Chip</mdui-chip>

原始碼

圖示

加上 icon、end-icon 屬性，可分別在標籤左側、右側加上 Material Icons 圖示。也可透過 icon、end-icon slot 在標籤左側、右側加入元素。

Icon

End Icon

Slot

<mdui-chip icon="search">Icon</mdui-chip>
<mdui-chip end-icon="arrow_forward">End Icon</mdui-chip>
<mdui-chip>
  Slot
  <mdui-icon slot="icon" name="downloading"></mdui-icon>
  <mdui-icon slot="end-icon" name="attach_file"></mdui-icon>
</mdui-chip>

原始碼

連結

加上 href 屬性即可將標籤轉為連結，並可使用以下連結相關的屬性：download、target、rel。

Link

<mdui-chip href="https://www.mdui.org" target="_blank">Link</mdui-chip>

原始碼

禁用及載入中狀態

加上 disabled 屬性可禁用標籤；加上 loading 屬性可為標籤加上載入中狀態。

Disabled

Loading & Disabled

<mdui-chip disabled>Disabled</mdui-chip>
<mdui-chip loading>Loading</mdui-chip>
<mdui-chip loading disabled>Loading & Disabled</mdui-chip>

原始碼

可選取

加上 selectable 屬性可讓標籤變成可選取狀態。

Chip

<mdui-chip selectable>Chip</mdui-chip>

原始碼

使用 selected-icon 屬性即可指定選取狀態的 Material Icons 圖示名稱。也可以透過 selected-icon slot 指定選取狀態的圖示元素。

Chip

<mdui-chip selectable selected-icon="favorite">Chip</mdui-chip>
<mdui-chip selectable>
  Chip
  <mdui-icon slot="selected-icon" name="favorite"></mdui-icon>
</mdui-chip>

原始碼

標籤被選取後，selected 屬性會變為 true。也可以透過加上 selected 屬性，使標籤預設處於選取狀態。

Chip

<mdui-chip selectable selected>Chip</mdui-chip>

原始碼

可刪除

加上 deletable 屬性後，標籤右側會出現一個刪除圖示。點擊該圖示會觸發 delete 事件。你可以透過 delete-icon 屬性指定刪除圖示的 Material Icons 圖示名稱，或者透過 delete-icon slot 指定刪除圖示的元素。

Chip

<mdui-chip deletable>Chip</mdui-chip>
<mdui-chip deletable delete-icon="backspace">Chip</mdui-chip>
<mdui-chip deletable>
  Chip
  <mdui-icon slot="delete-icon" name="backspace"></mdui-icon>
</mdui-chip>

原始碼

API

屬性

HTML 屬性	JavaScript 屬性	型別	預設值
`variant`	`variant`	`'assist' \| 'filter' \| 'input' \| 'suggestion'`	`'assist'`
標籤的形狀。可選值包括： `assist`：用於顯示與目前脈絡相關的輔助操作，如在點餐頁面提供分享、收藏等功能 `filter`：用於對內容進行篩選，如在搜尋結果頁過濾搜尋結果 `input`：用於表示使用者輸入的資訊片段，如在 Gmail 的「收件人」欄位中的聯絡人 `suggestion`：用於提供動態產生的推薦資訊，以簡化使用者操作，如在聊天應用中預測使用者可能想傳送的資訊
`elevated`	`elevated`	`boolean`	`false`
是否顯示陰影
`selectable`	`selectable`	`boolean`	`false`
是否可選取
`selected`	`selected`	`boolean`	`false`
是否已選取
`deletable`	`deletable`	`boolean`	`false`
是否可刪除。為 `true` 時，標籤右側會顯示刪除圖示
`icon`	`icon`	`string`	-
左側的 Material Icons 圖示名。也可以透過 `slot="icon"` 設定
`selected-icon`	`selectedIcon`	`string`	-
選取狀態下左側的 Material Icons 圖示名。也可以透過 `slot="selected-icon"` 設定
`end-icon`	`endIcon`	`string`	-
右側的 Material Icons 圖示名。也可以透過 `slot="end-icon"` 設定
`delete-icon`	`deleteIcon`	`string`	-
可刪除時，右側刪除圖示的 Material Icons 圖示名。也可以透過 `slot="delete-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`
表單欄位驗證未通過時觸發
`change`
選取狀態變更時觸發
`delete`
點擊刪除圖示時觸發

Slots

名稱
預設
標籤文字
`icon`
左側元素
`end-icon`
右側元素
`selected-icon`
選取狀態下的左側元素
`delete-icon`
可刪除時的右側刪除元素

CSS Parts

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

CSS 自訂屬性

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

Checkbox 核取方塊

CircularProgress 環形進度條