Button按鈕

按鈕主要用來執行各種操作，例如傳送電子郵件、分享文件或按讚留言等。

使用方法

按需引入元件：

import 'mdui/components/button.js';

按需引入元件的 TypeScript 型別：

import type { Button } from 'mdui/components/button.js';

使用範例：

Button

<mdui-button>Button</mdui-button>

範例

形狀

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

Elevated

Filled

Tonal

Outlined

Text

<mdui-button variant="elevated">Elevated</mdui-button>
<mdui-button variant="filled">Filled</mdui-button>
<mdui-button variant="tonal">Tonal</mdui-button>
<mdui-button variant="outlined">Outlined</mdui-button>
<mdui-button variant="text">Text</mdui-button>

原始碼

全寬

加上 full-width 屬性可讓按鈕佔滿父元素的全部寬度。

Button

<mdui-button full-width>Button</mdui-button>

原始碼

圖示

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

Icon

Slot

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

原始碼

連結

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

Link

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

原始碼

禁用及載入中狀態

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

Disabled

Loading & Disabled

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

原始碼

API

屬性

HTML 屬性	JavaScript 屬性	型別	預設值
`variant`	`variant`	`'elevated' \| 'filled' \| 'tonal' \| 'outlined' \| 'text'`	`'filled'`
按鈕的形狀。可選值包括： `elevated`：帶陰影的按鈕，適用於需要將按鈕與背景視覺分離的場景 `filled`：視覺效果強烈，適用於重要流程的最終操作，如「儲存」、「確認」等 `tonal`：視覺效果介於 `filled` 和 `outlined` 之間，適用於中高優先級的操作，如流程中的「下一步」 `outlined`：帶邊框的按鈕，適用於中等優先級，且次要的操作，如「返回」 `text`：文字按鈕，適用於最低優先級的操作
`full-width`	`fullWidth`	`boolean`	`false`
是否填滿父元素寬度
`icon`	`icon`	`string`	-
左側的 Material Icons 圖示名。也可以透過 `slot="icon"` 設定
`end-icon`	`endIcon`	`string`	-
右側的 Material Icons 圖示名。也可以透過 `slot="end-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`
按鈕左側的元素
`end-icon`
按鈕右側的元素

CSS Parts

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

CSS 自訂屬性

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

BottomAppBar 底部應用程式列

ButtonIcon 圖示按鈕