ButtonIcon圖示按鈕

圖示按鈕主要用來執行次要操作。

使用方法

按需引入元件：

import 'mdui/components/button-icon.js';

按需引入元件的 TypeScript 型別：

import type { ButtonIcon } from 'mdui/components/button-icon.js';

使用範例：

<mdui-button-icon icon="search"></mdui-button-icon>

範例

圖示

使用 icon 屬性指定 Material Icons 圖示名稱。你也可以透過 default slot 指定圖示元素。

<mdui-button-icon icon="search"></mdui-button-icon>
<mdui-button-icon>
  <mdui-icon name="search"></mdui-icon>
</mdui-button-icon>

原始碼

形狀

使用 variant 屬性設定圖示按鈕的形狀。

<mdui-button-icon variant="standard" icon="search"></mdui-button-icon>
<mdui-button-icon variant="filled" icon="search"></mdui-button-icon>
<mdui-button-icon variant="tonal" icon="search"></mdui-button-icon>
<mdui-button-icon variant="outlined" icon="search"></mdui-button-icon>

原始碼

可選取

加上 selectable 屬性即可讓圖示按鈕變成可選取狀態。

<mdui-button-icon selectable icon="favorite_border"></mdui-button-icon>

原始碼

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

<mdui-button-icon selectable icon="favorite_border" selected-icon="favorite"></mdui-button-icon>
<mdui-button-icon selectable icon="favorite_border">
  <mdui-icon slot="selected-icon" name="favorite"></mdui-icon>
</mdui-button-icon>

原始碼

圖示按鈕被選取後，selected 屬性會變為 true。你也可以透過加上 selected 屬性，使圖示按鈕預設處於選取狀態。

<mdui-button-icon selectable selected icon="favorite_border" selected-icon="favorite"></mdui-button-icon>

原始碼

連結

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

<mdui-button-icon icon="search" href="https://www.mdui.org" target="_blank"></mdui-button-icon>

原始碼

禁用及載入中狀態

加上 disabled 屬性即可停用圖示按鈕；加上 loading 屬性即可為圖示按鈕加入載入中狀態。

<mdui-button-icon disabled icon="search" variant="tonal"></mdui-button-icon>
<mdui-button-icon loading icon="search" variant="tonal"></mdui-button-icon>
<mdui-button-icon loading disabled icon="search" variant="tonal"></mdui-button-icon>

原始碼

API

屬性

HTML 屬性	JavaScript 屬性	型別	預設值
`variant`	`variant`	`'standard' \| 'filled' \| 'tonal' \| 'outlined'`	`'standard'`
圖示按鈕的形狀。可選值包括： `standard`：適用於最低優先級的操作 `filled`：視覺效果強烈，適用於高優先級的操作 `tonal`：視覺效果介於 `filled` 和 `outlined` 之間，適用於中高優先級的操作 `outlined`：適用於中等優先級的操作
`icon`	`icon`	`string`	-
Material Icons 圖示名。也可以透過 default slot 設定
`selected-icon`	`selectedIcon`	`string`	-
選取狀態的 Material Icons 圖示名。也可以透過 `slot="selected-icon"` 設定
`selectable`	`selectable`	`boolean`	`false`
是否可選取
`selected`	`selected`	`boolean`	`false`
是否已被選取
`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`
失去焦點時觸發
`change`
選取狀態變更時觸發
`invalid`
表單欄位驗證未通過時觸發

Slots

名稱
預設
圖示元件
`selected-icon`
選取狀態顯示的圖示元素

CSS Parts

名稱
`button`
內部的 `<button>` 或 `<a>` 元素
`icon`
未選取狀態的圖示
`selected-icon`
選取狀態的圖示
`loading`
載入中狀態的 `<mdui-circular-progress>` 元素

CSS 自訂屬性

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

Button 按鈕

Card 卡片