# 按鈕元件 Button 按鈕主要用來執行各種操作，例如傳送電子郵件、分享文件或按讚留言等。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/button.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Button } from 'mdui/components/button.js'; ``` 使用範例： ```html Button ``` ## 範例 {#examples} ### 形狀 {#example-variant} 使用 `variant` 屬性設定按鈕的形狀。 ```html Elevated Filled Tonal Outlined Text ``` ### 全寬 {#example-full-width} 加上 `full-width` 屬性可讓按鈕佔滿父元素的全部寬度。 ```html Button ``` ### 圖示 {#example-icon} 設定 `icon`、`end-icon` 屬性，可分別在按鈕左側、右側加上 Material Icons 圖示。也可以透過 `icon`、`end-icon` slot 在按鈕左側、右側加入元素。 ```html Icon Slot ``` ### 連結 {#example-link} 設定 `href` 屬性即可將按鈕轉為連結，並可使用以下連結相關的屬性：`download`、`target`、`rel`。 ```html Link ``` ### 禁用及載入中狀態 {#example-disabled} 加上 `disabled` 屬性可禁用按鈕；加上 `loading` 屬性可為按鈕加上載入中狀態。 ```html Disabled Loading Loading & Disabled ``` ## mdui-button API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'elevated' | 'filled' | 'tonal' | 'outlined' | 'text' 'filled'

按鈕的形狀。可選值包括：

  • elevated：帶陰影的按鈕，適用於需要將按鈕與背景視覺分離的場景
  • filled：視覺效果強烈，適用於重要流程的最終操作，如「儲存」、「確認」等
  • tonal：視覺效果介於 filled 和 outlined 之間，適用於中高優先級的操作，如流程中的「下一步」
  • outlined：帶邊框的按鈕，適用於中等優先級，且次要的操作，如「返回」
  • text：文字按鈕，適用於最低優先級的操作
full-width fullWidth true boolean false

是否填滿父元素寬度
icon icon true string

左側的 Material Icons 圖示名。也可以透過 slot="icon" 設定
end-icon endIcon true string

右側的 Material Icons 圖示名。也可以透過 slot="end-icon" 設定
href href true string

連結的目標網址。

若設定此屬性，元件內部會渲染為 <a> 元素，並可使用連結相關的屬性。
download download true string

下載目標。

Note：僅在設定了 href 屬性時，此屬性才有效。
target target true '_blank' | '_parent' | '_self' | '_top'

連結的開啟方式。可選值包括：

  • _blank：在新視窗中開啟連結
  • _parent：在父框架中開啟連結
  • _self：預設。在目前框架中開啟連結
  • _top：在整個視窗中開啟連結

Note：僅在設定了 href 屬性時，此屬性才有效。
rel rel true '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 true boolean false

是否在頁面載入完成後自動取得焦點
tabindex tabIndex false number

元素在使用 Tab 鍵切換焦點時的順序
disabled disabled true boolean false

是否停用
loading loading true boolean false

是否處於載入中狀態
name name true string ''

按鈕名稱，會與表單資料一起送出。

Note：僅在未設定 href 屬性時，此屬性才有效。
value value true string ''

按鈕初始值，會與表單資料一起送出。

Note：僅在未設定 href 屬性時，此屬性才有效。
type type true 'submit' | 'reset' | 'button' 'button'

按鈕的類型。預設類型為 button。可選類型包括：

  • submit：點擊按鈕會送出表單資料到伺服器
  • reset：點擊按鈕會將表單中的所有欄位重設為初始值
  • button：此類型的按鈕沒有預設行為

Note：僅在未指定 href 屬性時，此屬性才有效。
form form true string

關聯的 <form> 元素。此屬性值應為同一頁面中的一個 <form> 元素的 id。

若未指定此屬性，則該元素必須是 <form> 元素的子元素。透過此屬性，你可以將元素放置在頁面的任何位置，而不僅僅是 <form> 元素的子元素。

Note：僅在未指定 href 屬性時，此屬性才有效。
formaction formAction true string

指定送出表單的 URL。

若指定了此屬性，將覆蓋 <form> 元素的 action 屬性。

Note：僅在未指定 href 屬性且 type="submit" 時，此屬性才有效。
formenctype formEnctype true '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 true 'post' | 'get'

指定送出表單時使用的 HTTP 方法。可選值包括：

  • post：表單資料包含在表單內容中，送出到伺服器
  • get：表單資料以 ? 作為分隔符附加到表單的 URI 屬性中，產生的 URI 送出到伺服器。當表單沒有副作用，並且僅包含 ASCII 字元時，使用此方法

若設定了此屬性，將覆蓋 <form> 元素的 method 屬性。

Note：僅在未設定 href 屬性且 type="submit" 時，此屬性才有效。
formnovalidate formNoValidate true boolean false

若設定了此屬性，表單送出時將不執行表單驗證。

若設定了此屬性，將覆蓋 <form> 元素的 novalidate 屬性。

Note：僅在未設定 href 屬性且 type="submit" 時，此屬性才有效。
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

送出表單後接收到的回應應顯示在何處。可選值包括：

  • _self：預設，在目前框架中開啟
  • _blank：在新視窗中開啟
  • _parent：在父框架中開啟
  • _top：在整個視窗中開啟

若設定了此屬性，將覆蓋 <form> 元素的 target 屬性。

Note：僅在未設定 href 屬性且 type="submit" 時，此屬性才有效。
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false 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

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