# 概述 讓我們透過 mdui 的 CDN 和一個最簡單的頁面範本來開始使用 mdui。 > 你正在閱讀的是 mdui 2 的文件！ > > 若要閱讀 mdui 1 的文件，請訪問 [www.mdui.org/docs/](https://www.mdui.org/docs/)。 ## 快速入門 {#getting-started} 使用 mdui 最簡單的方式是直接從 CDN 引入 CSS 和 JS 檔案。 如果你想使用 npm 安裝 mdui，請參考 [安裝](/zh-tw/docs/2/getting-started/installation) 章節。 **引入檔案** 將下面程式碼加入頁面的``標籤中： ```html ``` 如果你需要使用元件的圖示屬性（例如``中的`icon` 屬性），則還需要引入圖示的 CSS 檔案，參見 [使用 Material Icons 圖示](/zh-tw/docs/2/components/icon#usage-material-icons)。 mdui 不依賴任何第三方函式庫，引入上述檔案後，就能正常工作了。 ## 最簡單的頁面範本 {#template} 下面是一個最簡單的頁面範本，你可以在其中加入更多元件和內容，來建置一個網站。 ```html Hello, world! Hello, world! ``` # 安裝 你可以選擇透過 npm 安裝 mdui，或從 CDN 引入。建議優先使用 npm 安裝。 ## npm 安裝 {#npm} ```bash npm install mdui --save ``` ### 全量引入 {#full-import} 在專案的進入點檔案中引入下面兩個檔案，即可使用所有 mdui 元件： ```js import 'mdui/mdui.css'; import 'mdui'; ``` 也可以直接從 mdui 按需引入所需函式。例如，要引入 [`snackbar`](/zh-tw/docs/2/functions/snackbar) 函式，可以這樣做： ```js import { snackbar } from 'mdui'; ``` 顯示所有可從 mdui 按需引入的函式 
import {
  $,
  dialog,
  alert,
  confirm,
  prompt,
  snackbar,
  getTheme,
  setTheme,
  getColorFromImage,
  setColorScheme,
  removeColorScheme,
  loadLocale,
  setLocale,
  getLocale,
  throttle,
  observeResize,
  breakpoint
} from 'mdui';
 ### 按需引入 {#cherry-picking} 為了控制專案體積，可以只引入需要的元件和函式。例如，如果你只需要使用 [``](/zh-tw/docs/2/components/button) 元件和 [`snackbar`](/zh-tw/docs/2/functions/snackbar) 函式，可以按照以下方式引入： ```js // CSS 檔案始終需要引入 import 'mdui/mdui.css'; // 引入 元件 import 'mdui/components/button.js'; // 引入 snackbar 函式 import { snackbar } from 'mdui/functions/snackbar.js'; ``` 每個元件或函式的文件頁面都會詳細說明如何按需引入。 顯示所有支援按需引入的元件和函式 
import 'mdui/components/avatar.js';
import 'mdui/components/badge.js';
import 'mdui/components/bottom-app-bar.js';
import 'mdui/components/button.js';
import 'mdui/components/button-icon.js';
import 'mdui/components/card.js';
import 'mdui/components/checkbox.js';
import 'mdui/components/chip.js';
import 'mdui/components/circular-progress.js';
import 'mdui/components/collapse.js';
import 'mdui/components/collapse-item.js';
import 'mdui/components/dialog.js';
import 'mdui/components/divider.js';
import 'mdui/components/dropdown.js';
import 'mdui/components/fab.js';
import 'mdui/components/icon.js';
import 'mdui/components/layout.js';
import 'mdui/components/layout-item.js';
import 'mdui/components/layout-main.js';
import 'mdui/components/linear-progress.js';
import 'mdui/components/list.js';
import 'mdui/components/list-item.js';
import 'mdui/components/list-subheader.js';
import 'mdui/components/menu.js';
import 'mdui/components/menu-item.js';
import 'mdui/components/navigation-bar.js';
import 'mdui/components/navigation-bar-item.js';
import 'mdui/components/navigation-drawer.js';
import 'mdui/components/navigation-rail.js';
import 'mdui/components/navigation-rail-item.js';
import 'mdui/components/radio.js';
import 'mdui/components/radio-group.js';
import 'mdui/components/range-slider.js';
import 'mdui/components/ripple.js';
import 'mdui/components/segmented-button.js';
import 'mdui/components/segmented-button-group.js';
import 'mdui/components/select.js';
import 'mdui/components/slider.js';
import 'mdui/components/snackbar.js';
import 'mdui/components/switch.js';
import 'mdui/components/tab.js';
import 'mdui/components/tab-panel.js';
import 'mdui/components/tabs.js';
import 'mdui/components/text-field.js';
import 'mdui/components/tooltip.js';
import 'mdui/components/top-app-bar.js';
import 'mdui/components/top-app-bar-title.js';
import { $ } from 'mdui/jq.js';
import { alert } from 'mdui/functions/alert.js';
import { breakpoint } from 'mdui/functions/breakpoint.js';
import { confirm } from 'mdui/functions/confirm.js';
import { dialog } from 'mdui/functions/dialog.js';
import { getColorFromImage } from 'mdui/functions/getColorFromImage.js';
import { getLocale } from 'mdui/functions/getLocale.js';
import { getTheme } from 'mdui/functions/getTheme.js';
import { loadLocale } from 'mdui/functions/loadLocale.js';
import { observeResize } from 'mdui/functions/observeResize.js';
import { prompt } from 'mdui/functions/prompt.js';
import { removeColorScheme } from 'mdui/functions/removeColorScheme.js';
import { setColorScheme } from 'mdui/functions/setColorScheme.js';
import { setLocale } from 'mdui/functions/setLocale.js';
import { setTheme } from 'mdui/functions/setTheme.js';
import { snackbar } from 'mdui/functions/snackbar.js';
import { throttle } from 'mdui/functions/throttle.js';
 ## CDN {#cdn} 你可以直接透過 `` 和 ` 點我 ``` ### 使用 ES 模組建構版本 {#es-module} 下面的範例示範如何使用 mdui 的 ES 模組建構版本。在這個版本中，你可以使用 ES 模組語法從 CDN 載入 mdui： ```html 點我 ``` # 快速入門 mdui 的元件都是標準的 Web Components 元件，你可以像使用 `
` 標籤一樣使用 mdui 元件。每個元件的文件中都詳細描述了其完整的 API，包括屬性、方法、事件、Slot、CSS Part、CSS 自訂屬性等。 本章將介紹 Web Components 的使用方法。 ## 屬性 {#attribute} 屬性分為 HTML 屬性和 JavaScript 屬性，它們通常是一一對應的，並且會保持同步。也就是說，當你更新 HTML 屬性值時，JavaScript 屬性值也會隨之更新；反之亦然。 HTML 屬性可以直接在元件的 HTML 字串中設定，並透過 `getAttribute` 和 `setAttribute` 方法進行讀取和修改： ```html 點我 ``` JavaScript 屬性則可以直接讀取或設定元件實例的屬性值： ```html 點我 ``` 某些屬性是布林型別，這些屬性的 HTML 屬性存在時，JavaScript 屬性為 `true`，否則為 `false`。但是，為了相容某些框架，mdui 會把字串 `false` 值也判定為布林值 `false`。 ```html ``` 有時屬性值是陣列、物件或函式，這時只有 JavaScript 屬性，沒有對應的 HTML 屬性，例如 [``](/zh-tw/docs/2/components/slider) 元件的 [`labelFormatter`](/zh-tw/docs/2/components/slider#attributes-labelFormatter) 屬性是一個函式，你只能透過 JavaScript 來設定該屬性： ```html ``` 以下以 [``](/zh-tw/docs/2/components/slider) 元件屬性文件的一部分為例： | HTML 屬性 | JavaScript 屬性 | reflect | | --------- | ---------------- | -------------------------------------------------------------------------------------- | | `name` | `name` | | | `value` | `value` | | | | `labelFormatter` | | 這個元件的 `name` 屬性同時具有 HTML 屬性和 JavaScript 屬性，而 reflect 一欄表示更新 JavaScript 屬性時會同步更新 HTML 屬性。`value` 屬性在更新 JavaScript 屬性時不會更新 HTML 屬性，`labelFormatter` 屬性則只有 JavaScript 屬性。 ## 方法 {#method} 部分元件提供了公用方法，你可以透過呼叫這些方法來實作不同的功能。例如，[``](/zh-tw/docs/2/components/text-field) 元件的 [`focus()`](/zh-tw/docs/2/components/text-field#methods-focus) 方法可讓文字框取得焦點。 ```html ``` 可在各個元件的文件頁面查看所有可用的方法及其參數。 ## 事件 {#event} 部分元件在執行特定操作時會觸發事件。例如，[``](/zh-tw/docs/2/components/dialog) 元件在開啟時會觸發 [`open`](/zh-tw/docs/2/components/dialog#events-open) 事件，你可以監聽這個事件來執行自訂操作。 ```html Dialog ``` 可在各個元件的文件頁面查看所有可用的事件及其參數。 如果你在其他框架（如 Vue、React、Angular 等）中使用 mdui，你可以使用框架提供的語法來繫結事件。但是，一些框架（如 React）的事件繫結語法只能用於繫結標準事件（如 `click` 事件），而無法用於繫結自訂事件（如 `open` 事件）。因此，在 React 中繫結自訂事件時，你需要先取得元素的參考，然後使用 `addEventListener` 方法來繫結事件。 關於在 React 中使用 mdui 的更多資訊，參見 [與框架整合 - React](/zh-tw/docs/2/frameworks/react)。 ## Slot {#slot} 許多元件都提供了 Slot，用於將自訂的 HTML 內容插入到元件內部。 最常見的是預設 Slot，它是位於元件內部的一段普通 HTML 或純文字。例如 [``](/zh-tw/docs/2/components/button) 元件的預設 Slot 用於設定按鈕的文字。範例中的「點我」就是預設 Slot 的內容： ```html 點我 ``` 部分元件還提供了具名 Slot，具名 Slot 需要在 HTML 的 `slot` 屬性中指定 Slot 名稱。下面的範例中，[``](/zh-tw/docs/2/components/icon) 元件指定了 `slot="start"`，表示這是名為 [`start`](/zh-tw/docs/2/components/button#slots-icon) 的具名 Slot，即這個圖示將被插入到元件內部的左側： ```html 設定 ``` 如果一個元件使用了多個具名 Slot，那麼各個具名 Slot 之間的順序並不重要，只要它們位於元件內部，瀏覽器就會自動將它們放置到正確的位置。 可在各個元件的文件頁面查看所有支援的 Slot。 ## CSS 自訂屬性 {#css-custom-properties} CSS 自訂屬性是 CSS 中的變數。mdui 定義了一系列[全域 CSS 自訂屬性](/zh-tw/docs/2/styles/design-tokens)，這些屬性在各個元件內部被參照，因此你可以透過修改這些 CSS 自訂屬性來全域修改 mdui 元件的樣式。 例如，下面的程式碼會縮小所有元件的圓角大小： ```css :root { --mdui-shape-corner-extra-small: 0.125rem; --mdui-shape-corner-small: 0.25rem; --mdui-shape-corner-medium: 0.375rem; --mdui-shape-corner-large: 0.5rem; --mdui-shape-corner-extra-large: 0.875rem; } ``` 也可以在局部作用域上修改 CSS 自訂屬性。例如，下面的程式碼只會在含 `class="sharp"` 的元素及其子元素中縮小圓角大小： ```css .sharp { --mdui-shape-corner-extra-small: 0.125rem; --mdui-shape-corner-small: 0.25rem; --mdui-shape-corner-medium: 0.375rem; --mdui-shape-corner-large: 0.5rem; --mdui-shape-corner-extra-large: 0.875rem; } ``` 一些元件還提供了該元件特有的 CSS 自訂屬性，這些屬性的作用域為特定元件，所以不包含 `--mdui` 前綴。例如，下面的程式碼透過修改 [``](/zh-tw/docs/2/components/dialog) 元件的 `--z-index` 屬性，實作了修改 `z-index` 樣式： ```css mdui-dialog { --z-index: 3000; } ``` 可在各個元件的文件頁面查看元件支援的 CSS 自訂屬性。 ## CSS Part {#css-part} mdui 元件使用 shadow DOM 來封裝樣式和行為，但是常規 CSS 選擇器無法選擇到 shadow DOM 內部的元素。因此，一些元件為 Shadow DOM 元素加入了 `part` 屬性，你可以使用 `::part` CSS 選擇器來選擇到對應的元素，並重寫部分樣式。 例如，下面的程式碼使用 [`button`](/zh-tw/docs/2/components/button#cssParts-button) part 修改了按鈕的內邊距，且使用 [`label`](/zh-tw/docs/2/components/button#cssParts-label)、[`icon`](/zh-tw/docs/2/components/button#cssParts-icon)、[`end-icon`](/zh-tw/docs/2/components/button#cssParts-end-icon) part 分別修改了文字、左右圖示的顏色： ```html Button ``` 關於元件 shadow DOM 元素的結構和預設樣式，你可以開啟瀏覽器的開發人員工具進行查看。 在使用 CSS Part 之前，你應該先判斷使用全域 CSS 自訂屬性、及元件特有的 CSS 自訂屬性能否滿足你的需求，如果能滿足需求，則應優先使用 CSS 自訂屬性來訂製樣式。 可在各個元件的文件頁面查看元件公開的所有 `part` 屬性。 ## 元件更新機制 {#update-mechanism} mdui 元件是基於 [Lit](https://lit.dev/) 開發的。Lit 是一個輕量級的函式庫，它使 Web Components 的開發更加簡單。在使用 mdui 元件時，你可能需要了解其渲染和更新機制。 當你修改 mdui 元件的屬性時，元件會進行重新渲染。但是，這個重新渲染過程並不是同步進行的。當你同時修改了多個屬性值時，Lit 會將這些變更快取起來，直到下一個更新週期，以確保無論你修改了多少次屬性值，每個元件只會重新渲染一次。並且，只有 shadow DOM 中發生變更的部分會被重新渲染。 在下面的範例中，我們將按鈕的 `disabled` JavaScript 屬性值設定為 `true`，然後立即查詢其 HTML 屬性。但是，由於此時元件還沒有進行重新渲染，因此查詢到的 HTML 屬性仍然是 `false`： ```js const button = document.querySelector('mdui-button'); button.disabled = true; console.log(button.hasAttribute('disabled')); // false ``` 如果要等待一個屬性值變更後的重新渲染完成，可以使用元件的 `updateComplete` 屬性。該屬性回傳 Promise，resolve 後即表示元件已完成重新渲染： ```js const button = document.querySelector('mdui-button'); button.disabled = true; button.updateComplete.then(() => { console.log(button.hasAttribute('disabled')); // true }); ``` # TypeScript 支援 mdui 是用 TypeScript 開發的，因此對 TypeScript 提供了良好的支援。所有的 mdui 官方庫都自帶型別宣告檔案，可以直接使用。 ## 元件的實例型別 {#instance} 有時，你可能需要將一個 JavaScript 變數斷言為 mdui 的元件實例，這時你可以直接從 mdui 引入對應的元件型別。 例如，從元件檔案中引入 Tooltip 元件的型別： ```ts import type { Tooltip } from 'mdui/components/tooltip.js'; ``` 或者直接從 mdui 引入 Tooltip 元件的型別： ```ts import type { Tooltip } from 'mdui'; ``` 然後，你就可以將一個 JavaScript 變數斷言成 Tooltip 型別： ```ts const tooltip = document.querySelector('mdui-tooltip') as Tooltip; ``` 此時，IDE 會自動提示 `tooltip` 變數的屬性和方法。 如果在 `tooltip` 變數上新增事件監聽，也會自動提示事件名稱、事件型別，以及回呼函式中 `this` 的指向： ```ts tooltip.addEventListener('open', function (event) {}); ``` ## 事件型別 {#event} 每個元件都會匯出一個介面，對應元件的事件名稱和事件物件型別，介面名為 `${元件名}EventMap`。 例如，Tooltip 元件會匯出一個名為 `TooltipEventMap` 的介面： ```ts export interface TooltipEventMap { open: CustomEvent; opened: CustomEvent; close: CustomEvent; closed: CustomEvent; } ``` 你可以從元件檔案中引入該介面： ```ts import type { TooltipEventMap } from 'mdui/components/tooltip.js'; ``` 或者直接從 mdui 引入該介面： ```ts import type { TooltipEventMap } from 'mdui'; ``` 請注意，該介面只包含元件特有的事件，但 mdui 元件都繼承自 `HTMLElement`，所以也支援 `HTMLElement` 的事件，你可以使用交集型別來取得元件的所有事件型別： ```ts type TooltipAndHTMLElementEventMap = TooltipEventMap & HTMLElementEventMap; ``` # IDE 支援 mdui 針對 VS Code 和 WebStorm 做了最佳化，在這些 IDE 中可用程式碼自動完成、懸停提示等功能。 ## VS Code {#vscode} ### 透過 npm 安裝的 mdui {#vscode-npm} 如果你是透過 npm 安裝 mdui，可依下列步驟在目前專案中啟用 VS Code 的 IDE 支援： 1. 在專案的根目錄中建立 `.vscode` 目錄。 2. 在 `.vscode` 目錄中建立 `settings.json` 檔案。 3. 將以下程式碼加入 `settings.json` 檔案中： ```json { "html.customData": ["./node_modules/mdui/html-data.zh-cn.json"], "css.customData": ["./node_modules/mdui/css-data.zh-cn.json"] } ``` 如果 `settings.json` 檔案已經存在，只要將上述兩行程式碼加入 JSON 內容的根節點即可。修改完成後，重新啟動 VS Code。 ### 透過 CDN 使用的 mdui {#vscode-cdn} 如果你是透過 CDN 使用 mdui，可安裝 mdui 的 VS Code 擴充功能來取得 IDE 支援。 在 VS Code 的擴充功能市集中搜尋 `mdui`，選擇第一筆搜尋結果進行安裝，或[點擊此處安裝](vscode:extension/zdhxiong.mdui)。安裝完成後，所有專案都會啟用 mdui 的 IDE 支援。 建議優先透過 npm 安裝並設定 `settings.json` 檔案，而非安裝 VS Code 擴充功能，以確保 IDE 支援與目前使用的 mdui 版本保持一致。 ## WebStorm {#webstorm} ### 透過 npm 安裝的 mdui {#webstorm-npm} 如果你是透過 npm 安裝 mdui，可依下列步驟在目前專案中啟用 WebStorm 的 IDE 支援： 1. 在專案根目錄的 `package.json` 檔案的根節點中加入以下程式碼： ```json { "web-types": ["./node_modules/mdui/web-types.zh-cn.json"] } ``` 如果 `package.json` 檔案的根節點已存在 `web-types` 屬性，只需將 `./node_modules/mdui/web-types.zh-cn.json` 加入 `web-types` 陣列中即可。修改完成後，重新啟動 WebStorm。 ### 透過 CDN 使用的 mdui {#webstorm-cdn} 如果你是透過 CDN 引入的 mdui，可以透過安裝 mdui 的 WebStorm 擴充功能來獲得 IDE 支援。 在 WebStorm 的外掛市集中搜尋 `mdui`，選擇第一筆搜尋結果進行安裝。安裝完成後，所有專案都會啟用 mdui 的 IDE 支援。 建議優先透過 npm 安裝來取得 IDE 支援，而非安裝 WebStorm 擴充功能，以確保 IDE 支援與目前使用的 mdui 版本保持一致。 ## 對 VS Code 和 WebStorm 的支援差異 {#difference} mdui 對 VS Code 和 WebStorm 的支援存在一些差異。以下表格列出了詳細的差異： | 具有程式碼自動完成及懸停提示的位置 | VS Code | WebStorm | | ------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | HTML 標籤名 | | | | HTML 標籤中的屬性名稱 | | | | HTML 標籤中屬性值的列舉值 | | （不支援顯示列舉值的註解） | | HTML 標籤中的事件名稱 | | | | HTML 中 slot 的 `name` 屬性值 | | | | CSS 中 `::part()` 選擇器的 `part` 屬性名稱 | | | | CSS 中元件內的 CSS 自訂屬性名稱 | | | | CSS 中的全域 CSS 自訂屬性名稱 | | | | CSS 中的全域 class 名稱 | | | # 在地化 mdui 內部預設使用英文，如果要使用其他語言，則需要進行多語言設定。 ## 使用方法 {#usage} mdui 提供三個函式來實作多語言功能： - [`loadLocale`](/zh-tw/docs/2/functions/loadLocale)：載入語言包。參數為一個函式，接收一個語言代碼作為參數，回傳 Promise，語言包載入完成時會 resolve 為對應的語言包。請確保在專案進入點呼叫該函式。 - [`setLocale`](/zh-tw/docs/2/functions/setLocale)：切換到指定的語言。參數為新的語言代碼，回傳 Promise，在新的語言包載入完成後會 resolve。 - [`getLocale`](/zh-tw/docs/2/functions/getLocale)：取得目前的語言代碼。 範例如下： ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; import { setLocale } from 'mdui/functions/setLocale.js'; import { getLocale } from 'mdui/functions/getLocale.js'; // 在專案進入點處呼叫 loadLocale 載入語言包 loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`)); // 在需要切換語言時呼叫該函式。在 Promise resolve 後，語言切換成功 setLocale('zh-cn').then(() => { // 呼叫 getLocale 可取得目前的語言代碼 console.log(getLocale()); // zh-cn }); ``` ## 狀態事件 {#event} 在語言切換開始、結束、失敗時，會在 `window` 上觸發 `mdui-localize-status` 事件，你可以監聽該事件來執行自訂操作，例如在語言切換成功後將語言代碼寫入 Cookie。 事件的`detail.status` 屬性描述了目前發生何種狀態的變更，可能的值包括：`loading`、`ready`、`error`：
detail.status 描述
loading

開始載入新的語言包。

detail 物件包含：

  • loadingLocale：新載入語言的語言代碼。
ready

新的語言包載入成功。

detail 物件包含：

  • readyLocale：新載入語言的語言代碼。
error

新的語言包載入失敗。

detail 物件包含：

  • errorLocale：載入失敗的語言的語言代碼。
  • errorMessage：載入失敗的錯誤資訊。
範例如下： ```js window.addEventListener('mdui-localize-status', (event) => { if (event.detail.status === 'loading') { console.log(`開始載入新的語言包：${event.detail.loadingLocale}`); } else if (event.detail.status === 'ready') { console.log(`新語言包 ${event.detail.readyLocale} 載入成功`); } else if (event.detail.status === 'error') { console.error( `新語言包 ${event.detail.errorLocale} 載入失敗：${event.detail.errorMessage}`, ); } }); ``` ## 語言包載入方式 {#load-locale} ### 延遲載入 {#lazy-load} 使用[動態引入](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Operators/import)可以在切換到對應語言時，才下載對應的語言包。這是最為推薦的方法。 ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`)); ``` ### 預載入 {#pre-load} 在頁面載入時先預先下載所有需要的語言包。這樣在切換語言時就不必重新下載，切換也會更快。 ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; const localizedTemplates = new Map([ ['zh-cn', import(`../node_modules/mdui/locales/zh-cn.js`)], ['zh-tw', import(`../node_modules/mdui/locales/zh-tw.js`)], ]); loadLocale(async (locale) => localizedTemplates.get(locale)); ``` ### 靜態引入 {#static-imports} 使用此方法可將所有需要的語言包與專案程式碼打包成同一個檔案，不必另外下載語言包。 ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; import * as locale_zh_cn from 'mdui/locales/zh-cn.js'; import * as locale_zh_tw from 'mdui/locales/zh-tw.js'; const localizedTemplates = new Map([ ['zh-cn', locale_zh_cn], ['zh-tw', locale_zh_tw], ]); loadLocale(async (locale) => localizedTemplates.get(locale)); ``` ## 透過 CDN 載入語言包 {#cdn} 如果你是透過 CDN 使用 mdui，可以直接從 CDN 載入語言包。範例如下： ```html ``` ## 支援的語言 {#languages} 目前，mdui 支援以下語言： | 語言 | 語言代碼 | | -------------------- | -------- | | 阿拉伯語 | ar-eg | | 亞塞拜然語 | az-az | | 保加利亞語 | bg-bg | | 孟加拉語（孟加拉國） | bn-bd | | 白俄羅斯語 | be-by | | 加泰隆尼亞語 | ca-es | | 捷克語 | cs-cz | | 丹麥語 | da-dk | | 德語 | de-de | | 希臘語 | el-gr | | 英語 | en-gb | | 英語（美式） | en-us | | 西班牙語 | es-es | | 愛沙尼亞語 | et-ee | | 波斯語 | fa-ir | | 芬蘭語 | fi-fi | | 法語（比利時） | fr-be | | 法語（加拿大） | fr-ca | | 法語（法國） | fr-fr | | 愛爾蘭語 | ga-ie | | 加利西亞語（西班牙） | gl-es | | 希伯來語 | he-il | | 印地語 | hi-in | | 克羅埃西亞語 | hr-hr | | 匈牙利語 | hu-hu | | 亞美尼亞 | hy-am | | 印尼語 | id-id | | 義大利語 | it-it | | 冰島語 | is-is | | 日語 | ja-jp | | 喬治亞語 | ka-ge | | 高棉語 | km-kh | | 北庫德語 | kmr-iq | | 卡納達語 | kn-in | | 哈薩克語 | kk-kz | | 韓語/朝鮮語 | ko-kr | | 立陶宛語 | lt-lt | | 拉脫維亞語 | lv-lv | | 馬其頓語 | mk-mk | | 馬拉雅拉姆語 | ml-in | | 蒙古語 | mn-mn | | 馬來語（馬來西亞） | ms-my | | 挪威語 | nb-no | | 尼泊爾語 | ne-np | | 荷蘭語（比利時） | nl-be | | 荷蘭語 | nl-nl | | 波蘭語 | pl-pl | | 葡萄牙語（巴西） | pt-br | | 葡萄牙語 | pt-pt | | 羅馬尼亞語 | ro-ro | | 俄語 | ru-ru | | 斯洛伐克語 | sk-sk | | 塞爾維亞語 | sr-rs | | 斯洛維尼亞語 | sl-si | | 瑞典語 | sv-se | | 坦米爾語 | ta-in | | 泰語 | th-th | | 土耳其語 | tr-tr | | 烏爾都語（巴基斯坦） | ur-pk | | 烏克蘭語 | uk-ua | | 越南語 | vi-vn | | 簡體中文 | zh-cn | | 繁體中文（中國香港） | zh-hk | | 繁體中文（台灣） | zh-tw | ## 提交新的翻譯 {#contribute} 要貢獻新的翻譯、或對現有翻譯進行改進，請在 GitHub 上發起一個 Pull Request。語言包位於 [`packages/mdui/src/xliff`](https://github.com/zdhxiong/mdui/tree/v2/packages/mdui/src/xliff)，你可以直接在 GitHub 上進行編輯。 # 常見問題 以下整理了一些 mdui 社群的常見問題與官方解答，建議在提問前先找找有沒有類似的問題。 ## 使用自閉合標籤為何無法顯示元件？ {#no-self-closing} mdui 是基於 Web Components 開發的元件庫，Web Components 規範不支援自閉合標籤，因此請確保為 mdui 元件加上結束標籤。 ```html ``` ## 如何在元件載入完成前隱藏元件？ {#waiting-load} 由於 mdui 元件是透過 JavaScript 進行註冊的，因此在 js 檔案載入並註冊元件之前，元件可能會暫時顯示為無樣式狀態。以下兩種方法可以解決這個問題： 一種方法是使用 CSS 的 [`:defined`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Reference/Selectors/:defined) 虛擬類別來隱藏未註冊的 mdui 元件。以下 CSS 程式碼將隱藏所有未註冊的 mdui 元件，並在元件註冊完成後立即顯示： ```css :not(:defined) { visibility: hidden; } ``` 另一種方法是使用 JavaScript 的 [`customElements.whenDefined()`](https://developer.mozilla.org/zh-CN/docs/Web/API/CustomElementRegistry/whenDefined) 方法。這個方法回傳 Promise，當指定的元件註冊完成後，Promise 會被 resolve。為了處理某些元件因特殊原因無法載入的情況，你可以搭配使用 [`Promise.allSettled()`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) 方法。 以下範例首先透過 `opacity: 0` 將 `` 隱藏，然後在元件註冊完成後，使頁面淡入顯示。同時，範例使用了 `Promise.allSettled()` 來等待所有 promise 完成，確保即使某個元件無法載入，頁面也能正常顯示： ```html ``` # LLMs.txt mdui 提供了 `llms.txt` 與 `llms-full.txt`，用於為 LLM（大型語言模型）提供準確、可引用的上下文，幫助 AI 更可靠地回答 mdui 相關問題。 ## 使用 llms.txt 為 AI 提供上下文 {#context} 兩個入口： - `llms.txt`：https://www.mdui.org/zh-tw/docs/2/llms.txt - `llms-full.txt`：https://www.mdui.org/zh-tw/docs/2/llms-full.txt `llms.txt` 是精簡索引，適合讓可連網的模型依連結抓取所需的 Markdown 頁面，或先快速掌握專案概覽。 `llms-full.txt` 則包含完整上下文，涵蓋 `llms.txt` 中的所有頁面內容，適合模型無法連網或需一次性提供完整上下文的情境。 ## 文件的 Markdown 版本 {#md-mirror} 每個文件頁面都提供了對應的 Markdown 版本：在頁面網址結尾加上 `.md` 即可（首頁則加上 `index.md`）。 例如： https://www.mdui.org/zh-tw/docs/2/components/button → https://www.mdui.org/zh-tw/docs/2/components/button.md https://www.mdui.org/zh-tw/docs/2/ → https://www.mdui.org/zh-tw/docs/2/index.md 可直接將該 Markdown 連結或其純文字作為上下文，以獲得更聚焦、準確的回答。 ## 在 ChatGPT、Claude 等 LLM 中如何使用 {#how-to-use} 根據模型是否支援連網/檔案上傳，可選擇以下一種或組合使用： 1. 直接貼上：將 `llms-full.txt` 的內容作為系統提示或第一則訊息。 範例：“以下是 mdui 的上下文。請嚴格依據它回答後續問題；若有衝突，以該上下文為準：\n\n[貼上 llms-full.txt 內容]”。 2. 上傳檔案：上傳 `llms-full.txt`（或 `llms.txt`），並在第一則提示說明“以附件為主要上下文”。 範例：“請基於附件中的 mdui 文件，給出 `` 的用法與常見的陷阱”。 3. 線上讀取：在對話中提供 `llms.txt` 或 `llms-full.txt` 的連結。 範例：“請讀取並遵循 https://www.mdui.org/zh-tw/docs/2/llms-full.txt 作為上下文，回答我關於 mdui 的問題”。 4. 指向特定頁面：只討論特定元件/函式時，直接提供該頁面的 Markdown 網址。 範例：“請閱讀 https://www.mdui.org/zh-tw/docs/2/components/button.md ，並根據該文件給出三項最佳實踐”。 **提示**：你可以點選頁面右上角的 圖示，一鍵複製上述連結、開啟目前頁面的 Markdown 版本，或將目前頁面或 `llms-full.txt` 作為上下文在 ChatGPT 中開啟。 # MCP 伺服器 mdui 提供專用的 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 伺服器 `@mdui/mcp`，可在本地提供 AI 代理查詢元件、圖示、CSS 自訂屬性及文件的能力。 它可與 Claude Code、Cursor、GitHub Copilot 等開發工具搭配，輔助產生程式碼，並更好地運用 mdui 的元件與樣式。 ## 工具 {#tools} mdui 的 MCP 伺服器向 AI 代理開放以下工具： - `list_components`：列出所有 mdui 元件。 - `get_component_metadata`：取得單一元件的詳細 API 元資料。 - `list_css_classes`：列出全域 CSS 類別名稱。 - `list_css_variables`：列出全域 CSS 自訂屬性。 - `list_documents`：列出所有文件。 - `get_document`：取得單一文件的完整內容。 - `list_icon_codes`：列出可用於屬性或 API 的圖示代碼。 - `list_icon_components`：列出獨立的圖示元件及其 ESM 引入語句。 ## 使用方式 {#usage} MCP 伺服器僅支援 [stdio 傳輸](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio)，可在 VS Code、Cursor、Claude Code、Windsurf、Zed 等客戶端，以及支援 stdio 協定的 AI 代理中直接使用。 ### VS Code {#vscode} > 請確保已安裝 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 與 [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) 擴充功能。 1. 在專案根目錄建立 `.vscode/mcp.json`，加入以下設定： ```json { "servers": { "mdui": { "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` 2. 點擊 `mcp.json` 檔案中的“啟動”按鈕。 3. 在 GitHub Copilot Chat 中開始對話。 ### Cursor {#cursor} 1. 在專案根目錄建立或編輯 `.cursor/mcp.json`，加入以下設定： ```json { "mcpServers": { "mdui": { "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` 2. 前往 Settings > Cursor Settings > MCP & Integrations，啟用 mdui 伺服器。 3. 在 Cursor Chat 中開始對話。 ### Claude Code {#claude-code} 1. 在終端機中執行以下指令來新增 mdui MCP 伺服器： ```bash claude mcp add mdui -- npx -y @mdui/mcp ``` 2. 接著執行 `claude` 啟動會話。 3. 輸入提示詞即可開始使用。 ### Windsurf {#windsurf} 1. 前往 Settings > Windsurf Settings > Cascade 2. 點擊 Manage MCPs，再點擊 “View raw config”，在設定檔中加入： ```json { "mcpServers": { "mdui": { "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` > 如果 MCP 伺服器未自動出現，可點擊 Refresh 重新整理清單。 3. 輸入提示詞開始對話。 ### Zed {#zed} 1. 開啟 Settings > Open Settings，在 `settings.json` 檔案中加入以下設定： ```json { "context_servers": { "mdui": { "source": "custom", "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` 2. 輸入提示詞即可開始使用。 ### 自訂 MCP 客戶端 {#custom} 在本地或開發環境中使用自訂 MCP 客戶端時，只需將該伺服器加入客戶端的設定檔即可。例如： ```json { "mcpServers": { "mdui": { "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` # 深色模式 mdui 的所有元件都支援深色模式，並且支援根據作業系統的設定自動切換主題。 你可以隨時點擊文件頁面右上角的 圖示切換主題，查看各個元件在不同主題下的顯示效果。 如果要使用深色模式，只需在 `` 標籤上加入`mdui-theme-dark` 類別即可： ```html ``` 如果要讓主題根據作業系統設定自動切換，只需在 `` 標籤上加入 `mdui-theme-auto` 類別即可： ```html ``` 也可以在頁面的不同部分使用不同的主題。例如下面的範例，在 `` 上設定深色模式，但在頁面中的一個 `
` 上加入了 `mdui-theme-light` 類別，這樣該 div 中的元素將顯示為淺色模式，而頁面其餘部分則為深色模式： ```html
``` 除了直接加入 CSS 類別外，mdui 還提供了兩個函式，可以更方便地操作主題： - [`getTheme`](/zh-tw/docs/2/functions/getTheme)：取得目前頁面、或指定元素上的主題。 - [`setTheme`](/zh-tw/docs/2/functions/setTheme)：設定目前頁面、或指定元素上的主題。 --- 需要注意的是，mdui 在 `:root` 及 `.mdui-theme-light`、`.mdui-theme-dark`、`.mdui-theme-auto` 選擇器上設定了 `color` 和 `background-color` 樣式，如果你不喜歡這些預設樣式，可以自行覆蓋。 下面範例將淺色模式下的頁面背景設為純白，文字設為純黑；且深色模式下頁面背景設為純黑，文字設為純白： ```css :root, .mdui-theme-light { color: #000; background-color: #fff; } .mdui-theme-dark { color: #fff; background-color: #000; } @media (prefers-color-scheme: dark) { .mdui-theme-auto { color: #fff; background-color: #000; } } ``` # 動態配色 mdui 提供了動態配色功能。只要提供一個顏色值，mdui 就能自動產生一套完整的配色方案。此外，mdui 也支援從指定的桌布中擷取主色調，並據此產生配色方案。 你可以隨時點擊文件頁面右上角的 圖示，切換配色方案，查看各個元件在不同配色方案下的顯示效果。 一套配色方案實際上是一組 CSS 自訂屬性。mdui 元件中的顏色值都會參考這組 CSS 自訂屬性，因此可以一次更新所有元件的配色。完整的 CSS 自訂屬性清單請參見 [設計令牌 - 顏色](/zh-tw/docs/2/styles/design-tokens#color)。 ## 產生配色方案 {#color-scheme} 你可以使用 [`setColorScheme`](/zh-tw/docs/2/functions/setColorScheme) 函式來產生配色方案。該函式接受一個十六進位顏色值作為參數，產生一套配色方案，並將頁面的 `` 元素套用該配色方案。例如： ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // 根據 #0061a4 產生一套配色方案，並將 套用該配色方案 setColorScheme('#0061a4'); ``` 你還可以在第二個參數中指定 `target` 屬性，用來指定要套用配色方案的元素。例如： ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // 根據 #0061a4 產生一套配色方案，並將 .foo 元素設為該配色方案 setColorScheme('#0061a4', { target: document.querySelector('.foo'), }); ``` 預設情況下產生的配色方案僅包含 [設計令牌 - 顏色](/zh-tw/docs/2/styles/design-tokens#color) 中所列出的顏色。你可以在第二個參數中指定`customColors`屬性，mdui 會根據你指定的自訂顏色名和顏色值產生一組自訂顏色組。例如： ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // 根據 #0061a4 產生一套配色方案，並修改了原有的 error 顏色組的值，並加入了一組新的 music 顏色組 setColorScheme('#0061a4', { customColors: [ { name: 'error', value: '#69F0AE', }, { name: 'music', value: '#FFC107', }, ], }); ``` 一組自訂顏色組包含四個 CSS 自訂屬性： - `--mdui-color-{name}` - `--mdui-color-on-{name}` - `--mdui-color-{name}-container` - `--mdui-color-on-{name}-container` 其中的 `{name}`為你傳入的`customColors`中的`name`欄位名，即自訂顏色名。 自訂顏色名可以是預設配色方案中的已有顏色名，如`primary`、`secondary`、`tertiary`、`error`這些都是預設配色方案中已包含的。如果你指定了這些值作為自訂顏色名，則配色方案中對應的四個 CSS 自訂屬性會使用你指定的顏色值來產生。例如上面範例中指定了名為`error`的自訂顏色名，因為`error`是預設配色方案中已有的顏色名，且其對應的 CSS 自訂屬性被 mdui 元件用來表示錯誤狀態，因為現在顏色值被設為一個綠色的值，所以 mdui 元件中的錯誤狀態也將變為綠色。 自訂顏色名也可以是新增的，例如上面範例中的`music`，是預設配色方案中不存在的，則產生的配色方案會額外包含四個 CSS 自訂屬性。可以在你自己的樣式中參考這些 CSS 自訂屬性： ```html
Music
Music Container
``` 你還可以使用 [`removeColorScheme`](/zh-tw/docs/2/functions/removeColorScheme) 函式來移除透過上述方法產生的配色方案。你可以傳入參數來指定移除哪個元素上的配色方案，預設情況下，它會移除 `` 上的配色方案。 ## 從桌布中擷取顏色 {#from-wallpaper} mdui 提供了 [`getColorFromImage`](/zh-tw/docs/2/functions/getColorFromImage) 函式，用來從給定的 `Image` 實例中擷取主色調。該函式的回傳值是一個 Promise，resolve 後的值就是擷取出的十六進位顏色值。 你可以使用從該函式獲得的顏色值，然後呼叫上述文件中介紹的 [`setColorScheme`](/zh-tw/docs/2/functions/setColorScheme) 函式來設定配色方案。例如： ```js import { getColorFromImage } from 'mdui/functions/getColorFromImage.js'; import { setColorScheme } from 'mdui/functions/setColorScheme.js'; const image = new Image(); image.src = 'image1.png'; getColorFromImage(image).then((color) => setColorScheme(color)); ``` # 文章排版 mdui 提供了 `mdui-prose` 和 `mdui-table` CSS 類，專門用於最佳化文章和表格的樣式。 ## 文章排版 {#prose} 可以在文章的父元素上加入 `mdui-prose` 類，這樣可以最佳化整篇文章的顯示樣式，包括文章中的 `` 表格樣式。例如： ```html

標題

內文

``` ## 表格樣式 {#table} 在 `` 元素上加入 `mdui-table` 類，可以最佳化表格的顯示樣式。例如： ```html
``` 如果你希望表格能在其父元素內橫向捲動，可以在 `` 元素的父元素上加入 `mdui-table` 類。例如： ```html
``` # 設計令牌 設計令牌（Design Tokens）是一種用於管理設計系統的策略。 它將設計系統中的所有可重複使用元素（例如顏色、字體、間距等）抽象為獨立的變數，以便在整個設計系統中進行統一的管理和應用。 mdui 使用全域 CSS 自訂屬性來實作設計令牌。這意味著，你只需修改 CSS 自訂屬性，就能全域修改所有 mdui 元件的樣式。同時，對於你自己開發的樣式，也推薦優先參照 CSS 自訂屬性，以確保你的樣式與 mdui 元件的樣式保持統一，此外，在修改動態配色時，你自己的樣式也能同步更新配色。 ## 顏色 {#color} mdui 為淺色模式和深色模式分別提供了一組 CSS 自訂屬性。在淺色模式下，CSS 自訂屬性名為`--mdui-color-{name}-light`，其中 `{name}`為顏色名稱；在深色模式下則為`--mdui-color-{name}-dark`。 此外，mdui 還提供了一組名為 `--mdui-color-{name}`的 CSS 自訂屬性，該屬性在淺色模式下會參照`--mdui-color-{name}-light`，在深色模式下會參照 `--mdui-color-{name}-dark`，因此能根據目前淺色模式和深色模式自動切換顏色。 如果你需要修改部分顏色的 CSS 自訂屬性，需要同時修改 `--mdui-color-{name}-light`和`--mdui-color-{name}-dark`兩個屬性。而在讀取 CSS 自訂屬性時，直接使用`--mdui-color-{name}`屬性即可。 CSS 自訂屬性的屬性值為 RGB 的三個顏色使用`,` 分隔，下面的範例演示了顏色的 CSS 自訂屬性的用法： ```css /* 修改 primary 的顏色值 */ :root { --mdui-color-primary-light: 103, 80, 164; --mdui-color-primary-dark: 208, 188, 255; } /* 把 foo 元素的背景色設為 primary */ .foo { background-color: rgb(var(--mdui-color-primary)); } /* 把 bar 元素的背景色設為含 0.8 不透明度的 primary */ .bar { background-color: rgba(var(--mdui-color-primary), 0.8); } ``` 如果你需要建立一套全新的配色，推薦使用 [`setColorScheme`](/zh-tw/docs/2/functions/setColorScheme) 函式，該函式能根據你指定的一個顏色值產生一整套配色方案。
顏色名 CSS 自訂屬性 預設值 範例
Primary --mdui-color-primary-light 103, 80, 164
--mdui-color-primary-dark 208, 188, 255
--mdui-color-primary
Primary container --mdui-color-primary-container-light 234, 221, 255
--mdui-color-primary-container-dark 79, 55, 139
--mdui-color-primary-container
On primary --mdui-color-on-primary-light 255, 255, 255
--mdui-color-on-primary-dark 55, 30, 115
--mdui-color-on-primary
On primary container --mdui-color-on-primary-container-light 33, 0, 94
--mdui-color-on-primary-container-dark 234, 221, 255
--mdui-color-on-primary-container
Inverse primary --mdui-color-inverse-primary-light 208, 188, 255
--mdui-color-inverse-primary-dark 103, 80, 164
--mdui-color-inverse-primary
Secondary --mdui-color-secondary-light 98, 91, 113
--mdui-color-secondary-dark 204, 194, 220
--mdui-color-secondary
Secondary container --mdui-color-secondary-container-light 232, 222, 248
--mdui-color-secondary-container-dark 74, 68, 88
--mdui-color-secondary-container
On secondary --mdui-color-on-secondary-light 255, 255, 255
--mdui-color-on-secondary-dark 51, 45, 65
--mdui-color-on-secondary
On secondary container --mdui-color-on-secondary-container-light 30, 25, 43
--mdui-color-on-secondary-container-dark 232, 222, 248
--mdui-color-on-secondary-container
Tertiary --mdui-color-tertiary-light 125, 82, 96
--mdui-color-tertiary-dark 239, 184, 200
--mdui-color-tertiary
Tertiary container --mdui-color-tertiary-container-light 255, 216, 228
--mdui-color-tertiary-container-dark 99, 59, 72
--mdui-color-tertiary-container
On tertiary --mdui-color-on-tertiary-light 255, 255, 255
--mdui-color-on-tertiary-dark 73, 37, 50
--mdui-color-on-tertiary
On tertiary container --mdui-color-on-tertiary-container-light 55, 11, 30
--mdui-color-on-tertiary-container-dark 255, 216, 228
--mdui-color-on-tertiary-container
Surface --mdui-color-surface-light 254, 247, 255
--mdui-color-surface-dark 20, 18, 24
--mdui-color-surface
Surface dim --mdui-color-surface-dim-light 222, 216, 225
--mdui-color-surface-dim-dark 20, 18, 24
--mdui-color-surface-dim
Surface bright --mdui-color-surface-bright-light 254, 247, 255
--mdui-color-surface-bright-dark 59, 56, 62
--mdui-color-surface-bright
Surface container lowest --mdui-color-surface-container-lowest-light 255, 255, 255
--mdui-color-surface-container-lowest-dark 15, 13, 19
--mdui-color-surface-container-lowest
Surface container low --mdui-color-surface-container-low-light 247, 242, 250
--mdui-color-surface-container-low-dark 29, 27, 32
--mdui-color-surface-container-low
Surface container --mdui-color-surface-container-light 243, 237, 247
--mdui-color-surface-container-dark 33, 31, 38
--mdui-color-surface-container
Surface container high --mdui-color-surface-container-high-light 236, 230, 240
--mdui-color-surface-container-high-dark 43, 41, 48
--mdui-color-surface-container-high
Surface container highest --mdui-color-surface-container-highest-light 230, 224, 233
--mdui-color-surface-container-highest-dark 54, 52, 59
--mdui-color-surface-container-highest
Surface variant --mdui-color-surface-variant-light 231, 224, 236
--mdui-color-surface-variant-dark 73, 69, 79
--mdui-color-surface-variant
On surface --mdui-color-on-surface-light 28, 27, 31
--mdui-color-on-surface-dark 230, 225, 229
--mdui-color-on-surface
On surface variant --mdui-color-on-surface-variant-light 73, 69, 78
--mdui-color-on-surface-variant-dark 202, 196, 208
--mdui-color-on-surface-variant
Inverse surface --mdui-color-inverse-surface-light 49, 48, 51
--mdui-color-inverse-surface-dark 230, 225, 229
--mdui-color-inverse-surface
Inverse on surface --mdui-color-inverse-on-surface-light 244, 239, 244
--mdui-color-inverse-on-surface-dark 49, 48, 51
--mdui-color-inverse-on-surface
Background --mdui-color-background-light 254, 247, 255
--mdui-color-background-dark 20, 18, 24
--mdui-color-background
On background --mdui-color-on-background-light 28, 27, 31
--mdui-color-on-background-dark 230, 225, 229
--mdui-color-on-background
Error --mdui-color-error-light 179, 38, 30
--mdui-color-error-dark 242, 184, 181
--mdui-color-error
Error container --mdui-color-error-container-light 249, 222, 220
--mdui-color-error-container-dark 140, 29, 24
--mdui-color-error-container
On error --mdui-color-on-error-light 255, 255, 255
--mdui-color-on-error-dark 96, 20, 16
--mdui-color-on-error
On error container --mdui-color-on-error-container-light 65, 14, 11
--mdui-color-on-error-container-dark 249, 222, 220
--mdui-color-on-error-container
Outline --mdui-color-outline-light 121, 116, 126
--mdui-color-outline-dark 147, 143, 153
--mdui-color-outline
Outline variant --mdui-color-outline-variant-light 196, 199, 197
--mdui-color-outline-variant-dark 68, 71, 70
--mdui-color-outline-variant
Shadow --mdui-color-shadow-light 0, 0, 0
--mdui-color-shadow-dark 0, 0, 0
--mdui-color-shadow
Surface tint --mdui-color-surface-tint-color-light 103, 80, 164
--mdui-color-surface-tint-color-dark 208, 188, 255
--mdui-color-surface-tint-color
Scrim --mdui-color-scrim-light 0, 0, 0
--mdui-color-scrim-dark 0, 0, 0
--mdui-color-scrim
## 圓角 {#shape-corner} mdui 提供了 7 種不同大小的圓角。以下是如何使用這些圓角的 CSS 自訂屬性的範例： ```css /* 修改 extra-small 的圓角大小 */ :root { --mdui-shape-corner-extra-small: 0.3rem; } /* 把 foo 元素的圓角設為 extra-small */ .foo { border-radius: var(--mdui-shape-corner-extra-small); } ``` | CSS 自訂屬性 | 預設值 | 範例 | | --------------------------------- | --------- | --------------------------------------------------------------------------------------------------------- | | `--mdui-shape-corner-none` | `0` |
| | `--mdui-shape-corner-extra-small` | `0.25rem` |
| | `--mdui-shape-corner-small` | `0.5rem` |
| | `--mdui-shape-corner-medium` | `0.75rem` |
| | `--mdui-shape-corner-large` | `1rem` |
| | `--mdui-shape-corner-extra-large` | `1.75rem` |
| | `--mdui-shape-corner-full` | `1000rem` |
| ## 排版 {#typescale} mdui 提供了 15 種不同的文字樣式，包括 Display large、Display medium、Display small、Headline large、Headline medium、Headline small、Title large、Title medium、Title small、Label large、Label medium、Label small、Body large、Body medium、Body small。 下面是使用範例： ```css /* 修改 Body large 的文字樣式 */ :root { --mdui-typescale-body-large-line-height: 1.6rem; --mdui-typescale-body-large-size: 1.2rem; --mdui-typescale-body-large-tracking: 0.01rem; --mdui-typescale-body-large-weight: 400; } /* 把 foo 元素的文字樣式設為 Body large */ .foo { line-height: var(--mdui-typescale-body-large-line-height); font-size: var(--mdui-typescale-body-large-size); letter-spacing: var(--mdui-typescale-body-large-tracking); font-weight: var(--mdui-typescale-body-large-weight); } ```
CSS 自訂屬性 預設值 範例
--mdui-typescale-display-large-line-height 4rem
Display large
--mdui-typescale-display-large-size 3.5625rem
--mdui-typescale-display-large-tracking 0
--mdui-typescale-display-large-weight 400
--mdui-typescale-display-medium-line-height 3.25rem
Display medium
--mdui-typescale-display-medium-size 2.8125rem
--mdui-typescale-display-medium-tracking 0
--mdui-typescale-display-medium-weight 400
--mdui-typescale-display-small-line-height 2.75rem
Display small
--mdui-typescale-display-small-size 2.25rem
--mdui-typescale-display-small-tracking 0
--mdui-typescale-display-small-weight 400
--mdui-typescale-headline-large-line-height 2.5rem
Headline large
--mdui-typescale-headline-large-size 2rem
--mdui-typescale-headline-large-tracking 0
--mdui-typescale-headline-large-weight 400
--mdui-typescale-headline-medium-line-height 2.25rem
Headline medium
--mdui-typescale-headline-medium-size 1.75rem
--mdui-typescale-headline-medium-tracking 0
--mdui-typescale-headline-medium-weight 400
--mdui-typescale-headline-small-line-height 2rem
Headline small
--mdui-typescale-headline-small-size 1.5rem
--mdui-typescale-headline-small-tracking 0
--mdui-typescale-headline-small-weight 400
--mdui-typescale-title-large-line-height 1.75rem
Title large
--mdui-typescale-title-large-size 1.375rem
--mdui-typescale-title-large-tracking 0
--mdui-typescale-title-large-weight 400
--mdui-typescale-title-medium-line-height 1.5rem
Title medium
--mdui-typescale-title-medium-size 1rem
--mdui-typescale-title-medium-tracking 0.009375rem
--mdui-typescale-title-medium-weight 500
--mdui-typescale-title-small-line-height 1.25rem
Title small
--mdui-typescale-title-small-size 0.875rem
--mdui-typescale-title-small-tracking 0.00625rem
--mdui-typescale-title-small-weight 500
--mdui-typescale-label-large-line-height 1.25rem
Label large
--mdui-typescale-label-large-size 0.875rem
--mdui-typescale-label-large-tracking 0.00625rem
--mdui-typescale-label-large-weight 500
--mdui-typescale-label-medium-line-height 1rem
Label medium
--mdui-typescale-label-medium-size 0.75rem
--mdui-typescale-label-medium-tracking 0.03125rem
--mdui-typescale-label-medium-weight 500
--mdui-typescale-label-small-line-height 0.375rem
Label small
--mdui-typescale-label-small-size 0.6875rem
--mdui-typescale-label-small-tracking 0.03125rem
--mdui-typescale-label-small-weight 500
--mdui-typescale-body-large-line-height 1.5rem
Body large
--mdui-typescale-body-large-size 1rem
--mdui-typescale-body-large-tracking 0.009375rem
--mdui-typescale-body-large-weight 400
--mdui-typescale-body-medium-line-height 1.25rem
Body medium
--mdui-typescale-body-medium-size 0.875rem
--mdui-typescale-body-medium-tracking 0.015625rem
--mdui-typescale-body-medium-weight 400
--mdui-typescale-body-small-line-height 1rem
Body small
--mdui-typescale-body-small-size 0.75rem
--mdui-typescale-body-small-tracking 0.025rem
--mdui-typescale-body-small-weight 400
## 狀態層不透明度 {#state-layer} 部分 mdui 元件在互動時會在其上加上一層半透明遮罩。例如 [``](/zh-tw/docs/2/components/button) 元件，在滑鼠懸停、聚焦、按下或拖曳時，都會出現半透明遮罩。你可以透過修改 CSS 自訂屬性來調整這些遮罩的不透明度。 下面是使用範例： ```css /* 修改狀態層不透明度 */ :root { --mdui-state-layer-hover: 0.08; --mdui-state-layer-focus: 0.12; --mdui-state-layer-pressed: 0.12; --mdui-state-layer-dragged: 0.16; } ``` | CSS 自訂屬性 | 預設值 | 範例 | | ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | `--mdui-state-layer-hover` | `0.08` |
| | `--mdui-state-layer-focus` | `0.12` |
| | `--mdui-state-layer-pressed` | `0.12` |
| | `--mdui-state-layer-dragged` | `0.16` |
| ## 抬升高度（陰影） {#elevation} 部分 mdui 元件具有陰影效果，以模擬元件在頁面上的抬升感。你可以透過修改 CSS 自訂屬性來調整元件的陰影效果。 下面是使用範例： ```css /* 修改 level1 級別的陰影 */ :root { --mdui-elevation-level1: 0 0.5px 1.5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0 1px 0 rgba(var(--mdui-color-shadow), 3.9%); } /* 把 foo 元素的陰影設為 level1 */ .foo { box-shadow: var(--mdui-elevation-level1); } ``` | CSS 自訂屬性 | 預設值 | 範例 | | ------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `--mdui-elevation-level0` | `none` |
| | `--mdui-elevation-level1` | `0 0.5px 1.5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0 1px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| | `--mdui-elevation-level2` | `0 0.85px 3px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.25px 1px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| | `--mdui-elevation-level3` | `0 1.25px 5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.3333px 1.5px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| | `--mdui-elevation-level4` | `0 1.85px 6.25px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.5px 1.75px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| | `--mdui-elevation-level5` | `0 2.75px 9px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.25px 3px 0 rgba(var(--mdui-color-shadow), 3.9%)` |
| ## 動畫 {#motion} mdui 元件中的動畫緩動曲線和持續時間可以透過 CSS 自訂屬性進行配置。 下面是使用範例： ```css /* 修改 standard 的緩動曲線、及 short1 的持續時間 */ :root { --mdui-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1); --mdui-motion-duration-short1: 40ms; } /* 設定 foo 元素的過渡效果使用 standard 的緩動曲線、及 short1 的持續時間 */ .foo { transition: all var(--mdui-motion-duration-short1) var(--mdui-motion-easing-standard); } ```
類型 CSS 自訂屬性 預設值
緩動曲線 --mdui-motion-easing-linear cubic-bezier(0, 0, 1, 1)
--mdui-motion-easing-standard cubic-bezier(0.2, 0, 0, 1)
--mdui-motion-easing-standard-accelerate cubic-bezier(0.3, 0, 1, 1)
--mdui-motion-easing-standard-decelerate cubic-bezier(0, 0, 0, 1)
--mdui-motion-easing-emphasized var(--mdui-motion-easing-standard)
--mdui-motion-easing-emphasized-accelerate cubic-bezier(0.3, 0, 0.8, 0.15)
--mdui-motion-easing-emphasized-decelerate cubic-bezier(0.05, 0.7, 0.1, 1)
持續時間 --mdui-motion-duration-short1 50ms
--mdui-motion-duration-short2 100ms
--mdui-motion-duration-short3 150ms
--mdui-motion-duration-short4 200ms
--mdui-motion-duration-medium1 250ms
--mdui-motion-duration-medium2 300ms
--mdui-motion-duration-medium3 350ms
--mdui-motion-duration-medium4 400ms
--mdui-motion-duration-long1 450ms
--mdui-motion-duration-long2 500ms
--mdui-motion-duration-long3 550ms
--mdui-motion-duration-long4 600ms
--mdui-motion-duration-extra-long1 700ms
--mdui-motion-duration-extra-long2 800ms
--mdui-motion-duration-extra-long3 900ms
--mdui-motion-duration-extra-long4 1000ms
## 響應式斷點 {#breakpoint} mdui 提供了一系列的響應式斷點，這些斷點可以透過 CSS 自訂屬性進行配置。下面是使用範例： ```css /* 修改 sm 的斷點值 */ :root { --mdui-breakpoint-sm: 560px; } ``` 需要注意的是，這些 CSS 自訂屬性不能在 CSS 媒體查詢中使用。以下是一個錯誤的範例： ```css /* 錯誤用法。媒體查詢中無法使用 CSS 自訂屬性 */ @media (min-width: var(--mdui-breakpoint-sm)) { } ``` 如果你需要在 JavaScript 中進行斷點判斷，可以使用 [`breakpoint`](/zh-tw/docs/2/functions/breakpoint) 函式。 | CSS 自訂屬性 | 預設值 | | ----------------------- | -------- | | `--mdui-breakpoint-xs` | `0px` | | `--mdui-breakpoint-sm` | `600px` | | `--mdui-breakpoint-md` | `840px` | | `--mdui-breakpoint-lg` | `1080px` | | `--mdui-breakpoint-xl` | `1440px` | | `--mdui-breakpoint-xxl` | `1920px` | # 搭配 React 使用 在 React 中使用 mdui 時，只需要按照 [安裝](/zh-tw/docs/2/getting-started/installation#npm) 頁面的步驟完成安裝即可。 ## 注意事項 {#notes} 在 React 中使用 mdui 時，存在一些限制。這些限制是在 React 中使用 Web Components 的通用限制，而非 mdui 元件庫本身的限制。 ### 事件繫結 {#event-binding} 由於 React 不支援自訂事件，因此在使用 mdui 元件提供的事件時，需要先使用 `ref` 屬性取得元件的參照。 以下是在 React 中使用 mdui 元件事件的範例： ```js import { useEffect, useRef } from 'react'; import 'mdui/mdui.css'; import 'mdui/components/switch.js'; function App() { const switchRef = useRef(null); useEffect(() => { const handleToggle = () => { console.log('switch is toggled'); }; switchRef.current.addEventListener('change', handleToggle); return () => { switchRef.current.removeEventListener('change', handleToggle); }; }, []); return ; } export default App; ``` ### JSX TypeScript 型別宣告 {#jsx-typescript} 如果你在 TypeScript 檔案（.tsx）中使用 mdui，需要加入 TypeScript 型別宣告。你需要手動引入 mdui 的型別宣告檔案： ```ts /// ``` # 搭配 Vue 使用 在 Vue 中使用 mdui 時，首先需要按照 [安裝](/zh-tw/docs/2/getting-started/installation#npm) 頁面的指引完成安裝，然後進行一些必要的設定。 ## 設定 {#configuration} 你需要設定 Vue，不要把 mdui 元件解析為 Vue 元件。在 `vite.config` 檔案中，設定 `compilerOptions.isCustomElement` 選項即可： ```js // vite.config.js import vue from '@vitejs/plugin-vue'; export default { plugins: [ vue({ template: { compilerOptions: { // 所有以 mdui- 開頭的標籤名稱都是 mdui 元件 isCustomElement: (tag) => tag.startsWith('mdui-'), }, }, }), ], }; ``` 關於這個設定的詳細資訊，你可以參考 [Vue 官方文件](https://zh-hk.vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue)。 ## 注意事項 {#notes} ### 雙向資料繫結 {#data-binding} 在 mdui 元件上，你不能使用 `v-model` 進行雙向資料繫結。你需要自行處理資料的繫結與更新。例如： ```html ``` ### eslint 設定 {#eslint} 如果你使用了 [`eslint-plugin-vue`](https://www.npmjs.com/package/eslint-plugin-vue)，需要在 `.eslintrc.js` 中加入以下規則： ```js rules: { 'vue/no-deprecated-slot-attribute': 'off' } ``` # 搭配 Angular 使用 在 Angular 中使用 mdui 時，首先需要按照 [安裝](/zh-tw/docs/2/getting-started/installation#npm) 頁面的指引完成安裝，然後進行一些必要的設定。 ## 設定 {#configuration} 首先，我們先在 Angular 中啟用 Web Components 支援。範例如下： ```js import { BrowserModule } from '@angular/platform-browser'; import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; import { AppComponent } from './app.component'; @NgModule({ declarations: [AppComponent], imports: [BrowserModule], providers: [], bootstrap: [AppComponent], schemas: [CUSTOM_ELEMENTS_SCHEMA], }) export class AppModule {} ``` 設定完成後，我們就可以在 Angular 元件的程式碼中引入並使用 mdui 元件了： ```js import { Dialog } from 'mdui/components/dialog.js'; @Component({ selector: 'app-dialog-example', template: `
Dialog Content
` }) export class DialogExampleComponent implements OnInit { // 使用 @ViewChild 取得 #dialog 元素的參照 @ViewChild('dialog') dialog?: ElementRef; ... constructor(...) { } ngOnInit() { } ... openDialog() { // 使用 nativeElement 存取 mdui 元件 this.dialog?.nativeElement.open = true; } } ``` # 搭配其他框架使用 mdui 使用瀏覽器原生支援的 Web Components 開發，因此能在所有 Web 框架中使用。以下列出在常用框架中使用 mdui 的方式。 ## Aurelia {#Aurelia} 在按照 [安裝](/zh-tw/docs/2/getting-started/installation#npm) 頁面的指引完成安裝後，還需要安裝和設定一個額外的套件（僅適用於 Aurelia 2）： ```bash npm install aurelia-mdui --save ``` 然後將其註冊到應用程式中： ```typescript import { MduiWebTask } from 'aurelia-mdui'; Aurelia.register(MduiWebTask).app(MyApp).start(); ``` **注意** 請將錯誤報告傳送到 [https://github.com/mreiche/aurelia-mdui](https://github.com/mreiche/aurelia-mdui) ## WebCell {#WebCell} 在 [WebCell](https://web-cell.dev/) 中使用 mdui 時，只需要按照 [安裝](/zh-tw/docs/2/getting-started/installation#npm) 頁面的步驟完成安裝即可，Web Components、TypeScript 和 JSX 支援是一級特性且開箱即用。 或者，你可以使用 [官方 GitHub 範本儲存庫](https://github.com/EasyWebApp/WebCell-mobile) 來 [一鍵建立新專案](https://github.com/new?template_name=WebCell-mobile&template_owner=EasyWebApp)。 # 頭像元件 Avatar 頭像用於表示使用者或事物，支援多種形式，包含圖片、圖示或字元等。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/avatar.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Avatar } from 'mdui/components/avatar.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 圖片頭像 {#example-src} 你可以使用 `src` 屬性指定一個圖片網址作為頭像，或在 default slot 中提供一個 `` 元素作為頭像。 ```html 圖片頭像範例 ``` 你可以使用 `fit` 屬性定義圖片如何適應容器，類似於原生的 [`object-fit`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/object-fit)。 ### 圖示頭像 {#example-icon} 你可以使用 `icon` 屬性指定一個 Material Icons 圖示作為頭像，或在 default slot 中提供一個圖示元素作為頭像。 ```html ``` ### 字元頭像 {#example-char} 你可以在 default slot 中使用任意文字作為頭像。 ```html A ``` ## mdui-avatar API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
src src true string

頭像圖片的 URL 位址
fit fit true 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'

圖片如何適應容器，與原生的 object-fit 屬性相同。可選值包括：

  • contain：保持圖片原有尺寸比例，內容會被等比例縮放
  • cover：保持圖片原有尺寸比例，但部分內容可能被剪裁
  • fill：預設值，不保持圖片原有尺寸比例，內容會被拉伸以填滿整個容器
  • none：保留圖片原有尺寸，內容不會被縮放或拉伸
  • scale-down：保持圖片原有尺寸比例，內容尺寸與 none 或 contain 中較小的一個相同
icon icon true string

頭像的 Material Icons 圖示名
label label true string

頭像的替代文字描述
### Slots
名稱 說明
預設

自訂頭像內容，可以為字母、漢字、<img> 元素、圖示等
### CSS Parts
名稱 說明
image

使用圖片作為頭像時，元件內部的 <img> 元素
icon

使用圖示作為頭像時，元件內部的 <mdui-icon> 元素
### CSS 自訂屬性
名稱 說明
--shape-corner

元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 徽章元件 Badge 徽章用於展示動態資訊，例如計數或狀態指示。它可包含文字或數字。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/badge.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Badge } from 'mdui/components/badge.js'; ``` 使用範例： ```html 12 ``` ## 範例 {#examples} ### 形狀 {#example-variant} 使用 `variant` 屬性來設定徽章的形狀。當 `variant` 為 `large` 時，會顯示大型徽章。你可以在 default slot 中指定要顯示的文字。 ```html 99+ ``` ## mdui-badge API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'small' | 'large' 'large'

徽章的形狀。可選值包括：

  • small：小型徽章，不顯示文字
  • large：大型徽章，會顯示文字
### Slots
名稱 說明
預設

徽章中顯示的文字
### CSS 自訂屬性
名稱 說明
--shape-corner

元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 底部應用程式列元件 BottomAppBar 底部應用程式列主要用來在行動端頁面底部顯示導覽項目和其他重要操作。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/bottom-app-bar.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { BottomAppBar } from 'mdui/components/bottom-app-bar.js'; ``` 使用範例：（注意：範例中的 `style="position: relative"` 僅供示意，實際使用時請移除該樣式。） ```html
``` **注意事項：** 該元件預設使用 `position: fixed` 定位，並會自動在 `body` 上加上 `padding-bottom` 樣式，以防止頁面內容被該元件遮擋。 但在以下兩種情況下，會預設使用 `position: absolute` 定位： 1. 指定了 `scroll-target` 屬性時。此時會在 `scroll-target` 的元素上加上 `padding-bottom` 樣式。 2. 位於 [``](/zh-tw/docs/2/components/layout) 元件中時。此時不會加上 `padding-bottom` 樣式。 ## 範例 {#examples} ### 位於指定容器內 {#example-scroll-target} 預設情況下，底部應用程式列會固定在頁面底部。 如果你希望將底部應用程式列放在指定的容器內，可以指定 `scroll-target` 屬性，其值為可捲動內容容器的 CSS 選擇器或 DOM 元素。此時，底部應用程式列會以父元素作為定位基準（你需要自行替父元素加上 `position: relative; overflow: hidden` 樣式）。 ```html
Content
``` ### 捲動時隱藏 {#example-scroll-behavior} 將 `scroll-behavior` 屬性設定為 `hide`，可以在頁面向下捲動時隱藏底部應用程式列，向上捲動時則顯示底部應用程式列。 你可以使用 `scroll-threshold` 屬性，設定捲動多少像素後開始隱藏底部應用程式列。 ```html
Content
``` ### 固定浮動動作按鈕 {#example-fab-detach} 如果底部應用程式列中包含[浮動動作按鈕](/zh-tw/docs/2/components/fab)，加上 `fab-detach` 屬性後，頁面捲動且底部應用程式列隱藏時，浮動動作按鈕仍會停留在頁面右下角。 ```html
``` ## mdui-bottom-app-bar API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
hide hide true boolean false

是否隱藏
fab-detach fabDetach true boolean false

是否讓底部應用程式列中的 <mdui-fab> 元件脫離應用程式列。如果為 true，則當應用程式列隱藏後，<mdui-fab> 仍會停留在頁面上
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

捲動行為。可選值為：

  • hide：捲動時隱藏
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

需要監聽捲動事件的目標元素。值可以是 CSS 選擇器、DOM 元素、或 JQ 物件。預設監聽 window 的捲動事件
scroll-threshold scrollThreshold true number

觸發捲動行為所需的捲動距離，單位為 px
order order true number

該元件在 <mdui-layout> 中的版面順序，按從小到大排序。預設為 0
### 事件
名稱 說明
show

開始顯示時觸發。可透過呼叫 event.preventDefault() 阻止顯示
shown

顯示動畫完成時，事件被觸發
hide

開始隱藏時觸發。可透過呼叫 event.preventDefault() 阻止隱藏
hidden

隱藏動畫完成時，事件被觸發
### Slots
名稱 說明
預設

底部應用程式列內部的元素
### CSS 自訂屬性
名稱 說明
--shape-corner

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

元件的 CSS z-index 值
# 按鈕元件 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

元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 圖示按鈕元件 ButtonIcon 圖示按鈕主要用來執行次要操作。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/button-icon.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { ButtonIcon } from 'mdui/components/button-icon.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 圖示 {#example-icon} 使用 `icon` 屬性指定 Material Icons 圖示名稱。你也可以透過 default slot 指定圖示元素。 ```html ``` ### 形狀 {#example-variant} 使用 `variant` 屬性設定圖示按鈕的形狀。 ```html ``` ### 可選取 {#example-selectable} 加上 `selectable` 屬性即可讓圖示按鈕變成可選取狀態。 ```html ``` 使用 `selected-icon` 屬性指定選取狀態的 Material Icons 圖示名稱。也可以透過 `selected-icon` slot 指定選取狀態的圖示元素。 ```html ``` 圖示按鈕被選取後，`selected` 屬性會變為 `true`。你也可以透過加上 `selected` 屬性，使圖示按鈕預設處於選取狀態。 ```html ``` ### 連結 {#example-link} 加上 `href` 屬性即可將圖示按鈕轉為連結，並可使用以下連結相關的屬性：`download`、`target`、`rel`。 ```html ``` ### 禁用及載入中狀態 {#example-disabled} 加上 `disabled` 屬性即可停用圖示按鈕；加上 `loading` 屬性即可為圖示按鈕加入載入中狀態。 ```html ``` ## mdui-button-icon API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'standard' | 'filled' | 'tonal' | 'outlined' 'standard'

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

  • standard：適用於最低優先級的操作
  • filled：視覺效果強烈，適用於高優先級的操作
  • tonal：視覺效果介於 filled 和 outlined 之間，適用於中高優先級的操作
  • outlined：適用於中等優先級的操作
icon icon true string

Material Icons 圖示名。也可以透過 default slot 設定
selected-icon selectedIcon true string

選取狀態的 Material Icons 圖示名。也可以透過 slot="selected-icon" 設定
selectable selectable true boolean false

是否可選取
selected selected true boolean false

是否已被選取
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

失去焦點時觸發
change

選取狀態變更時觸發
invalid

表單欄位驗證未通過時觸發
### Slots
名稱 說明
預設

圖示元件
selected-icon

選取狀態顯示的圖示元素
### CSS Parts
名稱 說明
button

內部的 <button> 或 <a> 元素
icon

未選取狀態的圖示
selected-icon

選取狀態的圖示
loading

載入中狀態的 <mdui-circular-progress> 元素
### CSS 自訂屬性
名稱 說明
--shape-corner

元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 卡片元件 Card 卡片是一個多功能元件，用來承載與單一主題相關的內容和操作。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/card.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Card } from 'mdui/components/card.js'; ``` 使用範例： ```html Card ``` ## 範例 {#examples} ### 形狀 {#example-variant} 使用 `variant` 屬性設定卡片的形狀。 ```html ``` ### 可點選 {#example-clickable} 加上 `clickable` 屬性即可讓卡片可點選，此時會加入滑鼠懸停效果和點擊漣漪效果。 ```html ``` ### 連結 {#example-link} 加上 `href` 屬性即可將卡片轉為連結，並可使用以下連結相關的屬性：`download`、`target`、`rel`。 ```html ``` ### 禁用狀態 {#example-disabled} 加上 `disabled` 屬性即可停用卡片。 ```html ``` ## mdui-card API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'elevated' | 'filled' | 'outlined' 'elevated'

卡片的形狀。可選值包括：

  • elevated：帶陰影的卡片，與背景的視覺分離度較高
  • filled：帶填滿色的卡片，與背景的視覺分離度較低
  • outlined：帶邊框的卡片，與背景的視覺分離度最高
clickable clickable true boolean false

是否可點擊。為 true 時，卡片將具有滑鼠懸停效果和點擊漣漪效果
disabled disabled true boolean false

是否停用
href href true string

連結的目標 URL。

若設定此屬性，元件內部將渲染為 <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 鍵切換焦點時的順序
### 方法
名稱 說明
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
### Slots
名稱 說明
預設

卡片的內容
### CSS 自訂屬性
名稱 說明
--shape-corner

元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 核取方塊元件 Checkbox 核取方塊讓使用者可以從一組選項中選取一個或多個項目，或切換單一選項的開/關狀態。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/checkbox.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Checkbox } from 'mdui/components/checkbox.js'; ``` 使用範例： ```html Checkbox ``` ## 範例 {#examples} ### 選取狀態 {#example-checked} 核取方塊被選取時，`checked` 屬性值為 `true`。加上 `checked` 屬性可讓核取方塊預設處於選取狀態。 ```html Checkbox ``` ### 禁用狀態 {#example-disabled} 加上 `disabled` 屬性可禁用核取方塊。 ```html Checkbox Checkbox ``` ### 不確定狀態 {#example-indeterminate} 加上 `indeterminate` 屬性表示核取方塊處於不確定狀態。 ```html Checkbox ``` ### 圖示 {#example-icon} 透過設定 `unchecked-icon`、`checked-icon`、`indeterminate-icon` 屬性，可分別設定未選取、選取、不確定狀態時的核取方塊的 Material Icons 圖示。也可透過 `unchecked-icon`、`checked-icon`、`indeterminate-icon` slot 進行設定。 ```html Checkbox Checkbox
Checkbox Checkbox ``` ## mdui-checkbox API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
disabled disabled true boolean false

是否為停用狀態
checked checked true boolean false

是否為選取狀態
undefined defaultChecked false boolean false

預設選取狀態。在重設表單時，將恢復為此狀態。此屬性只能透過 JavaScript 屬性設定
indeterminate indeterminate true boolean false

是否處於不確定狀態
required required true boolean false

送出表單時，是否必須選取此核取方塊
form form true string

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

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

核取方塊名稱，將與表單資料一起送出
value value true string 'on'

核取方塊的值，將與表單資料一起送出
unchecked-icon uncheckedIcon true string

未選取狀態的 Material Icons 圖示名。也可以透過 slot="unchecked-icon" 設定
checked-icon checkedIcon true string

選取狀態的 Material Icons 圖示名。也可以透過 slot="checked-icon" 設定
indeterminate-icon indeterminateIcon true string

不確定狀態的 Material Icons 圖示名。也可以透過 slot="indeterminate-icon" 設定
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false string

如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串
autofocus autofocus true boolean false

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

元素在使用 Tab 鍵切換焦點時的順序
### 方法
名稱 說明
checkValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true
reportValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true。

如果驗證未通過，還會在元件上顯示驗證失敗的提示。
setCustomValidity(message: string): void

設定自訂的錯誤提示文字。只要這個文字不為空，就表示欄位未通過驗證
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
change

選取狀態變更時觸發
input

選取狀態變更時觸發
invalid

表單欄位驗證未通過時觸發
### Slots
名稱 說明
預設

核取方塊文字
unchecked-icon

未選取狀態的圖示
checked-icon

選取狀態的圖示
indeterminate-icon

不確定狀態的圖示
### CSS Parts
名稱 說明
control

左側圖示容器
unchecked-icon

未選取狀態的圖示
checked-icon

選取狀態的圖示
indeterminate-icon

不確定狀態的圖示
label

核取方塊文字
# 標籤元件 Chip 標籤元件用來協助使用者輸入資訊、選擇、篩選內容或執行相關操作。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/chip.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Chip } from 'mdui/components/chip.js'; ``` 使用範例： ```html Chip ``` ## 範例 {#examples} ### 形狀 {#example-variant} 使用 `variant` 屬性設定標籤的形狀。標籤共有 4 種形狀，可根據用途選擇： - `assist`：用於顯示與目前上下文相關的輔助操作。例如，在點餐頁面提供分享、收藏等功能。 - `filter`：用於對內容進行篩選。例如，在搜尋結果頁面對搜尋結果進行過濾。 - `input`：用於表示使用者輸入的資訊片段。例如，Gmail 中「收件人」欄位裡的聯絡人。 - `suggestion`：用於提供動態產生的推薦資訊，以簡化使用者操作。例如，在聊天應用中預測使用者可能想傳送的訊息，供使用者選擇。 ```html Assist Filter Input Suggestion ``` ### 陰影 {#example-elevated} 加上 `elevated` 屬性可讓標籤具有陰影。 ```html Chip ``` ### 圖示 {#example-icon} 加上 `icon`、`end-icon` 屬性，可分別在標籤左側、右側加上 Material Icons 圖示。也可透過 `icon`、`end-icon` slot 在標籤左側、右側加入元素。 ```html Icon End Icon Slot ``` ### 連結 {#example-link} 加上 `href` 屬性即可將標籤轉為連結，並可使用以下連結相關的屬性：`download`、`target`、`rel`。 ```html Link ``` ### 禁用及載入中狀態 {#example-disabled} 加上 `disabled` 屬性可禁用標籤；加上 `loading` 屬性可為標籤加上載入中狀態。 ```html Disabled Loading Loading & Disabled ``` ### 可選取 {#example-selectable} 加上 `selectable` 屬性可讓標籤變成可選取狀態。 ```html Chip ``` 使用 `selected-icon` 屬性即可指定選取狀態的 Material Icons 圖示名稱。也可以透過 `selected-icon` slot 指定選取狀態的圖示元素。 ```html Chip Chip ``` 標籤被選取後，`selected` 屬性會變為 `true`。也可以透過加上 `selected` 屬性，使標籤預設處於選取狀態。 ```html Chip ``` ### 可刪除 {#example-deletable} 加上 `deletable` 屬性後，標籤右側會出現一個刪除圖示。點擊該圖示會觸發 `delete` 事件。你可以透過 `delete-icon` 屬性指定刪除圖示的 Material Icons 圖示名稱，或者透過 `delete-icon` slot 指定刪除圖示的元素。 ```html Chip Chip Chip ``` ## mdui-chip API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'assist' | 'filter' | 'input' | 'suggestion' 'assist'

標籤的形狀。可選值包括：

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

是否顯示陰影
selectable selectable true boolean false

是否可選取
selected selected true boolean false

是否已選取
deletable deletable true boolean false

是否可刪除。為 true 時，標籤右側會顯示刪除圖示
icon icon true string

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

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

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

可刪除時，右側刪除圖示的 Material Icons 圖示名。也可以透過 slot="delete-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

表單欄位驗證未通過時觸發
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

元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 環形進度條元件 CircularProgress 環形進度條是一個用於顯示任務進度的圓形元件，例如資料載入或表單提交等。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/circular-progress.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { CircularProgress } from 'mdui/components/circular-progress.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 固定進度 {#example-value} 環形進度條預設為不確定的進度，你可以透過 `value` 屬性設定目前進度，預設的進度最大值為 `1`。 ```html ``` 你可以透過 `max` 屬性設定進度的最大值。 ```html ``` ## mdui-circular-progress API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
max max true number 1

進度條的最大值。預設為 1
value value false number

進度條的目前值。如果未指定該值，則顯示為不確定狀態
# 收合區塊元件 Collapse 收合區塊元件用來將複雜的內容區域分組並隱藏，以保持頁面的整潔。 請注意，收合區塊元件本身不包含任何樣式，你需要自行設定樣式，或與其他元件一起使用。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/collapse.js'; import 'mdui/components/collapse-item.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Collapse } from 'mdui/components/collapse.js'; import type { CollapseItem } from 'mdui/components/collapse-item.js'; ``` 使用範例： ```html first content second content ``` ## 範例 {#examples} ### 面板標題與內容 {#example-header} 你可以透過 `` 元件的 `header` 屬性設定標題文字，也可以透過 `header` slot 來指定標題元素。元件的 default slot 則用於面板內容。 ```html Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### 手風琴模式 {#example-accordion} 在 `` 元件上加上 `accordion` 屬性可以啟用手風琴模式，這樣一次只會有一個面板處於開啟狀態。 ```html Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### 設定啟用的面板 {#example-value} 透過 `` 元件的 `value` 屬性，你可以取得目前開啟的面板，或設定需要開啟的面板。 在手風琴模式下，`value` 屬性的值為字串，你可以使用 HTML 屬性或 JavaScript 屬性來操作它；在非手風琴模式下，`value` 屬性的值為陣列，此時只能透過 JavaScript 屬性進行操作。 ```html 手風琴模式 Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
非手風琴模式 Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### 禁用狀態 {#example-disabled} 你可以透過在 `` 元件上加上 `disabled` 屬性，來禁用整個收合區塊組。同樣地，在 `` 元件上加上 `disabled` 屬性，則可以禁用特定的收合區塊。 ```html 全部禁用 Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
禁用第一個面板 Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### 觸發收合的元素 {#example-trigger} 預設情況下，點擊整個面板標題區域會觸發收合。你可以透過設定 `` 元件的 `trigger` 屬性來指定觸發收合的元素。`trigger` 屬性可以是 CSS 選擇器或 DOM 元素。 ```html Item 1
Item 1 - subitem
``` ## mdui-collapse-item API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
value value true string

此收合區塊項目的值
header header true string

此收合區塊項目的頭部文字
disabled disabled true boolean false

是否停用此收合區塊項目
trigger trigger false string | HTMLElement | JQ<HTMLElement>

點擊該元素時觸發收合，值可以是 CSS 選擇器、DOM 元素、或 JQ 物件。預設為點擊整個 header 區域觸發
### 事件
名稱 說明
open

開始開啟時，事件被觸發
opened

開啟動畫完成時，事件被觸發
close

開始關閉時，事件被觸發
closed

關閉動畫完成時，事件被觸發
### Slots
名稱 說明
預設

收合區塊項目的正文內容
header

收合區塊項目的頭部內容
### CSS Parts
名稱 說明
header

收合區塊的頭部內容
body

收合區塊的正文內容
## mdui-collapse API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
accordion accordion true boolean false

是否啟用手風琴模式
value value false string | string[]

目前開啟的 <mdui-collapse-item> 的值

Note：該屬性的 HTML 屬性始終為字串，只有在 accordion 為 true 時，才能設定初始值；該屬性的 JavaScript 屬性值在 accordion 為 true 時為字串，在 accordion 為 false 時為字串陣列。因此，當 accordion 為 false 時，只能透過修改 JavaScript 屬性值來改變此值。
disabled disabled true boolean false

是否停用此收合區塊
### 事件
名稱 說明
change

目前開啟的收合區塊項目變化時觸發
### Slots
名稱 說明
預設

<mdui-collapse-item> 元件
# 對話框元件 Dialog 對話框用來在使用者的操作流程中提供重要提示。 除了直接使用該元件外，mdui 還提供了四個函式：[`mdui.dialog`](/zh-tw/docs/2/functions/dialog)、[`mdui.alert`](/zh-tw/docs/2/functions/alert)、[`mdui.confirm`](/zh-tw/docs/2/functions/confirm)、[`mdui.prompt`](/zh-tw/docs/2/functions/prompt)。這些函式可以簡化 Dialog 元件的使用。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/dialog.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Dialog } from 'mdui/components/dialog.js'; ``` 使用範例： ```html Dialog 關閉 開啟對話框 ``` ## 範例 {#examples} ### 點擊遮罩關閉 {#example-close-on-overlay-click} 加上 `close-on-overlay-click` 屬性，點擊遮罩層時即會關閉對話框。 ```html Dialog 開啟對話框 ``` ### 按下 ESC 鍵關閉 {#example-close-on-esc} 加上 `close-on-esc` 屬性，按下 ESC 鍵時即會關閉對話框。 ```html Dialog 開啟對話框 ``` ### 全螢幕 {#example-fullscreen} 加上 `fullscreen` 屬性，對話框會以全螢幕顯示。 ```html Dialog 關閉 開啟對話框 ``` ### 圖示 {#example-icon} 設定 `icon` 屬性，對話框上方會加入 Material Icons 圖示。 ```html Dialog 開啟對話框 ``` 也可以透過 `icon` slot 在對話框上方加入圖示元素。 ```html Dialog 開啟對話框 ``` ### 標題與描述 {#example-headline} 你可以透過 `headline` 和 `description` 屬性設定對話框的標題和描述。 ```html 開啟對話框 ``` 也可以透過 `headline` 和 `description` slot 來設定對話框的標題元素和描述元素。 ```html Delete selected images? Images will be permanently removed from your account and all synced devices. 開啟對話框 ``` ### 底部操作按鈕 {#example-action} 你可以透過 `action` slot 加入底部操作按鈕。 ```html 取消 刪除 開啟對話框 ``` 加上 `stacked-actions` 屬性，可使底部操作按鈕垂直排列。 ```html Turn on speed boost No thanks 開啟對話框 ``` ### 頂部內容 {#example-header} 你可以透過 `header` slot 設定對話框頂部內容。 ```html Title Save
開啟對話框 ``` ## mdui-dialog API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
icon icon true string

頂部的 Material Icons 圖示名。也可以透過 slot="icon" 設定
headline headline true string

標題。也可以透過 slot="headline" 設定
description description true string

標題下方的文字。也可以透過 slot="description" 設定
open open true boolean false

是否開啟對話框
fullscreen fullscreen true boolean false

是否全螢幕顯示對話框
close-on-esc closeOnEsc true boolean false

是否允許按下 ESC 鍵關閉對話框
close-on-overlay-click closeOnOverlayClick true boolean false

是否允許點擊遮罩層關閉對話框
stacked-actions stackedActions true boolean false

是否垂直排列底部操作按鈕
### 事件
名稱 說明
open

對話框開始開啟時觸發。可以透過呼叫 event.preventDefault() 阻止對話框開啟
opened

對話框開啟動畫完成後觸發
close

對話框開始關閉時觸發。可以透過呼叫 event.preventDefault() 阻止對話框關閉
closed

對話框關閉動畫完成後觸發
overlay-click

點擊遮罩層時觸發
### Slots
名稱 說明
header

頂部元素，預設包含 icon slot 和 headline slot
icon

頂部圖示
headline

頂部標題
description

標題下方的文字
預設

對話框主體內容
action

底部操作欄中的元素
### CSS Parts
名稱 說明
overlay

遮罩層
panel

對話框容器
header

對話框 header 部分，包含 icon 和 headline
icon

頂部圖示，位於 header 中
headline

頂部標題，位於 header 中
body

對話框 body 部分
description

副文字部分，位於 body 中
action

底部操作按鈕
### CSS 自訂屬性
名稱 說明
--shape-corner

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

元件的 CSS z-index 值
# 分隔線元件 Divider 分隔線是一條細線，用來在清單和容器中分隔內容。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/divider.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Divider } from 'mdui/components/divider.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 垂直分隔線 {#example-vertical} 加上 `vertical` 屬性，可讓分隔線垂直顯示。 ```html
``` ### 左側縮排 {#example-inset} 加上 `inset` 屬性，可讓分隔線左側縮排。這通常用於清單中，以便讓分隔線和左側文字對齊。 ```html Item 1 Item 2 ``` ### 兩側縮排 {#example-middle} 加上 `middle` 屬性，可讓分隔線兩側縮排。 ```html Item 1 Item 2 ``` ## mdui-divider API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
vertical vertical true boolean false

是否為垂直分隔線
inset inset true boolean false

是否進行左側縮排
middle middle true boolean false

是否進行左右兩側縮排
# 下拉元件 Dropdown 下拉元件用來在彈出式選單中顯示特定內容，通常會和選單元件一起使用。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/dropdown.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Dropdown } from 'mdui/components/dropdown.js'; ``` 使用範例： ```html open dropdown Item 1 Item 2 ``` ## 範例 {#examples} ### 禁用狀態 {#example-disabled} 加上 `disabled` 屬性可以禁用下拉元件。 ```html open dropdown Item 1 Item 2 ``` ### 開啟位置 {#example-placement} 使用 `placement` 屬性可以設定下拉元件的開啟位置。 ```html open dropdown Item 1 Item 2 ``` ### 觸發方式 {#example-trigger} 使用 `trigger` 屬性可以設定下拉元件的觸發方式。 ```html open dropdown Item 1 Item 2 ``` ### 在游標處開啟 {#example-open-on-pointer} 加上 `open-on-pointer` 屬性後，就能在指標位置開啟下拉元件。通常會搭配 `trigger="contextmenu"` 使用，做出以滑鼠右鍵開啟選單的效果。 ```html 在此區域使用滑鼠右鍵開啟選單 Item 1 Item 2 ``` ### 保持選單開啟狀態 {#example-stay-open-on-click} 在下拉元件中使用選單時，預設點擊選單項目後，會自動關閉下拉元件。你可以透過加上 `stay-open-on-click` 屬性，讓點擊選單項目時保持下拉元件的開啟狀態。 ```html open dropdown Item 1 Item 2 ``` ### 開啟/關閉的延遲 {#example-delay} 在設定了 `trigger="hover"` 時，可以透過 `open-delay`、`close-delay` 屬性設定開啟和關閉的延遲。 ```html open dropdown Item 1 Item 2 ``` ## mdui-dropdown API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
open open true boolean false

是否開啟下拉元件
disabled disabled true boolean false

是否停用下拉元件
trigger trigger true 'click' | 'hover' | 'focus' | 'contextmenu' | 'manual' | string 'click'

下拉元件的觸發方式，支援多個值，用空格分隔。可選值包括：

  • click：點擊觸發
  • hover：滑鼠懸停觸發
  • focus：聚焦觸發
  • contextmenu：滑鼠右鍵點擊、或觸控長按觸發
  • manual：僅能透過程式方式開啟和關閉下拉元件，不能再指定其他觸發方式
placement placement true 'auto' | 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end' | 'right-start' | 'right' | 'right-end' 'auto'

下拉元件內容的位置。可選值包括：

  • auto：自動判斷位置
  • top-start：上方左對齊
  • top：上方置中
  • top-end：上方右對齊
  • bottom-start：下方左對齊
  • bottom：下方置中
  • bottom-end：下方右對齊
  • left-start：左側頂部對齊
  • left：左側置中
  • left-end：左側底部對齊
  • right-start：右側頂部對齊
  • right：右側置中
  • right-end：右側底部對齊
stay-open-on-click stayOpenOnClick true boolean false

點擊 <mdui-menu-item> 後，下拉元件是否保持開啟狀態
open-delay openDelay true number 150

滑鼠懸停觸發下拉元件開啟的延遲，單位為毫秒
close-delay closeDelay true number 150

滑鼠懸停觸發下拉元件關閉的延遲，單位為毫秒
open-on-pointer openOnPointer true boolean false

是否在觸發下拉元件的游標位置開啟下拉元件，常用於滑鼠右鍵選單
### 事件
名稱 說明
open

下拉元件開始開啟時觸發。可透過呼叫 event.preventDefault() 阻止下拉元件開啟
opened

下拉元件開啟動畫完成時觸發
close

下拉元件開始關閉時觸發。可透過呼叫 event.preventDefault() 阻止下拉元件關閉
closed

下拉元件關閉動畫完成時觸發
### Slots
名稱 說明
預設

下拉元件的內容
trigger

觸發下拉元件的元素，例如 <mdui-button> 元素
### CSS Parts
名稱 說明
trigger

觸發下拉元件的元素的容器，即 trigger slot 的容器
panel

下拉元件內容的容器
### CSS 自訂屬性
名稱 說明
--z-index

元件的 CSS z-index 值
# 浮動動作按鈕元件 Fab 浮動動作按鈕（FAB）用於突顯頁面上的主要操作，它將關鍵操作置於易於存取的位置。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/fab.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Fab } from 'mdui/components/fab.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 圖示 {#example-icon} 使用 `icon` 屬性指定 Material Icons 圖示名稱。也可以透過 `icon` slot 指定圖示元素。 ```html ``` ### 展開狀態 {#example-extended} 加入 `extended` 屬性可以將 FAB 設定為展開狀態，此時 default slot 中的文字將會顯示出來。 ```html Compose ``` ### 變體 {#example-variant} 使用 `variant` 屬性可以設定 FAB 的變體。 ```html ``` ### 大小 {#example-size} 使用 `size` 屬性可以設定 FAB 的大小。 ```html ``` ### 連結 {#example-link} 加入 `href` 屬性，即可讓 FAB 具有連結功能，此時還可使用下列與連結相關的屬性：`download`、`target`、`rel`。 ```html ``` ### 禁用及載入中狀態 {#example-disabled} 加入 `disabled` 屬性即可停用 FAB；加入 `loading` 屬性即可為 FAB 加入載入中狀態。 ```html ``` ## mdui-fab API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'primary' | 'surface' | 'secondary' | 'tertiary' 'primary'

FAB 的形狀，此元件的不同形狀之間只有顏色不一樣。可選值包括：

  • primary：使用 Primary container 背景色
  • surface：使用 Surface container high 背景色
  • secondary：使用 Secondary container 背景色
  • tertiary：使用 Tertiary container 背景色
size size true 'normal' | 'small' | 'large' 'normal'

FAB 的大小。可選值包括：

  • normal：普通大小 FAB
  • small：小型 FAB
  • large：大型 FAB
icon icon true string

Material Icons 圖示名。也可以透過 slot="icon" 設定
extended extended true boolean false

是否為展開狀態
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

圖示
### CSS Parts
名稱 說明
button

內部的 <button> 或 <a> 元素
label

右側的文字
icon

左側的圖示
loading

載入中狀態的 <mdui-circular-progress> 元素
### CSS 自訂屬性
名稱 說明
--shape-corner-small

size="small" 時，元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
--shape-corner-normal

size="normal" 時，元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
--shape-corner-large

size="large" 時，元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 圖示元件 Icon 圖示用於表示常見的操作。它支援 Material Icons 圖示，也支援使用 SVG 圖示。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/icon.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Icon } from 'mdui/components/icon.js'; ``` 使用範例： ```html ``` ### 使用 Material Icons 圖示 {#usage-material-icons} 如果要透過這個元件使用 Material Icons 圖示，你需要另外引入 Material Icons 的 CSS 檔案。Material Icons 共有 5 種變體，分別為：Filled、Outlined、Rounded、Sharp、Two Tone，請依照你要使用的圖示變體，引入對應的 CSS 檔案： ```html ``` 使用元件時，在 `name` 屬性中傳入圖示名稱，並以圖示變體名稱為後綴（Filled 變體無需加入後綴），以下是 `delete` 圖示的 5 種變體的使用方式： ```html ``` 你可以直接在頁面下方的 [Material Icons 圖示搜尋](/zh-tw/docs/2/components/icon#search) 工具中搜尋圖示，然後點選需要使用的圖示，就會自動將圖示程式碼複製到剪貼簿。 另外，mdui 還提供了一個獨立的套件 [`@mdui/icons`](/zh-tw/docs/2/libraries/icons)，這個套件裡的每一個圖示元件都是一個獨立的檔案，讓你可以按需引入需要的圖示元件，而不需引入整個圖示庫。 ### 使用 SVG 圖示 {#usage-svg} 該元件也支援使用 SVG 圖示作為圖示內容。你可以透過元件的 `src` 屬性傳入 SVG 圖示的連結。例如： ```html ``` 也可以在元件的 default slot 中傳入 SVG 的內容。例如： ```html ``` ## 範例 {#examples} ### 設定顏色 {#example-color} 設定 `` 元素或父元素的 `color` CSS 樣式即可修改圖示顏色。 ```html ``` ### 設定大小 {#example-size} 設定 `` 元素或父元素的 `font-size` CSS 樣式即可修改圖示大小。 ```html ``` ## mdui-icon API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
name name true string

Material Icons 圖示名
src src true string

svg 圖示的路徑
### Slots
名稱 說明
預設

svg 圖示的內容
# 版面配置元件 Layout 版面配置元件提供了一個靈活的版面配置系統，用於建立複雜的頁面版面配置。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/layout.js'; import 'mdui/components/layout-item.js'; import 'mdui/components/layout-main.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Layout } from 'mdui/components/layout.js'; import type { LayoutItem } from 'mdui/components/layout-item.js'; import type { LayoutMain } from 'mdui/components/layout-main.js'; ``` **介紹：** 版面配置系統採用由外而內的方式組成。每個版面配置元件（`` 元件）都會在四個方向之一（上、下、左、右）佔據空間，後續的版面配置元件則會在剩餘空間中繼續佔位。 以下元件直接繼承自 `` 元件，因此也可以作為版面配置元件使用： - [``](/zh-tw/docs/2/components/navigation-bar) - [``](/zh-tw/docs/2/components/navigation-drawer) - [``](/zh-tw/docs/2/components/navigation-rail) - [``](/zh-tw/docs/2/components/bottom-app-bar) - [``](/zh-tw/docs/2/components/top-app-bar) 版面配置系統的最後一部分是 `` 元件，它會佔據剩餘空間，你可以在該元件內放置頁面內容。 ## 範例 {#examples} ### 版面配置元件順序 {#layout-default-order} 預設情況下，版面配置元件會按照在程式碼中出現的順序來佔據空間。你可以從下面兩個範例來理解這個概念，這兩個範例中，[``](/zh-tw/docs/2/components/top-app-bar) 和 [``](/zh-tw/docs/2/components/navigation-drawer) 在程式碼中出現的順序不同。

請在大螢幕顯示器上查看該範例。

```html Top App Bar Navigation drawer Main ``` ```html Navigation drawer Top App Bar Main ``` 可以發現，將 [``](/zh-tw/docs/2/components/top-app-bar) 放在 [``](/zh-tw/docs/2/components/navigation-drawer) 之前時，[``](/zh-tw/docs/2/components/top-app-bar) 會率先佔滿螢幕的寬度，而 [``](/zh-tw/docs/2/components/navigation-drawer) 只能在剩餘的空間內佔滿高度。調換二者順序後，[``](/zh-tw/docs/2/components/navigation-drawer) 則會率先佔滿螢幕的高度，而 [``](/zh-tw/docs/2/components/top-app-bar) 只能在剩餘的空間內佔滿寬度。 ### 版面配置元件位置 {#example-placement} 對於 `` 元件，你可以使用 `placement` 屬性來指定其在版面配置中的上、下、左、右位置。對於 [``](/zh-tw/docs/2/components/navigation-drawer) 和 [``](/zh-tw/docs/2/components/navigation-rail) 元件，你也可以使用 `placement` 屬性來指定其在版面配置中的左、右位置。 下面的範例中，我們將兩個 `` 元件放在了應用的兩側。 ```html Top App Bar Layout Item Layout Item Main ``` ### 自訂版面配置元件順序 {#example-order} 在大多數情況下，只要按順序放置版面配置元件，就能做出你想要的版面配置。 你也可以使用 `order` 屬性來指定版面配置順序，系統將按 `order` 的值從小到大排列元件，`order` 相同時則按程式碼順序排列。所有版面配置元件的預設 `order` 皆為 `0`。 ```html Layout Item Top App Bar
order="-1" Main ``` ## mdui-layout-item API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
placement placement true 'top' | 'bottom' | 'left' | 'right' 'top'

元件的位置。可選值包括：

  • top：上方
  • bottom：下方
  • left：左側
  • right：右側
order order true number

該元件在 <mdui-layout> 中的版面順序，按從小到大排序。預設為 0
### Slots
名稱 說明
預設

可以包含任意內容
## mdui-layout-main API ### Slots
名稱 說明
預設

可以包含任意內容
## mdui-layout API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
full-height fullHeight true boolean false

設定目前版面的高度為 100%
### Slots
名稱 說明
預設

可以包含 <mdui-top-app-bar>、<mdui-bottom-app-bar>、<mdui-navigation-bar>、<mdui-navigation-drawer>、<mdui-navigation-rail>、<mdui-layout-item>、<mdui-layout-main> 元素
# 線性進度條元件 LinearProgress 線性進度條是一種橫向的指示器，用來向使用者展示任務的執行進度，如資料載入或表單提交等。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/linear-progress.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { LinearProgress } from 'mdui/components/linear-progress.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 設定進度 {#example-value} 線性進度條預設為不確定的進度，你可以透過 `value` 屬性來設定目前的進度，預設的進度最大值為 `1`。 ```html ``` 你也可以透過 `max` 屬性來設定進度的最大值。 ```html ``` ## mdui-linear-progress API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
max max true number 1

進度條的最大值。預設為 1
value value false number

進度條的目前值。如果未指定該值，則處於不確定狀態
### CSS Parts
名稱 說明
indicator

指示器部分
### CSS 自訂屬性
名稱 說明
--shape-corner

元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 清單元件 List 清單是一種垂直排列的項目集合，用來呈現文字或圖片，方便使用者快速瀏覽並存取相關資訊。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/list.js'; import 'mdui/components/list-item.js'; import 'mdui/components/list-subheader.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { List } from 'mdui/components/list.js'; import type { ListItem } from 'mdui/components/list-item.js'; import type { ListSubheader } from 'mdui/components/list-subheader.js'; ``` 使用範例： ```html Subheader Item 1 Item 2 ``` ## 範例 {#examples} ### 文字內容 {#example-text} 在 `` 元件上設定 `headline` 屬性，可以設定清單項目的主文字；設定 `description` 屬性，則可以設定副文字。 ```html ``` 也可以透過 default slot 設定主文字，並透過 `description` slot 設定副文字。 ```html Headline Headline Supporting text ``` 預設情況下，主文字和副文字無論長度如何，都會完全顯示。你可以透過設定 `headline-line` 和 `description-line` 屬性來為主文字和副文字加入行數限制，最多可以限制為 3 行。 ```html Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text ``` ### 兩側內容 {#example-side} 在 `` 元件上設定 `icon` 和 `end-icon` 屬性，可以在清單項目的左側和右側加入 Material Icons 圖示。 ```html Headline ``` 也可以透過 `icon` 和 `end-icon` slot 在清單項目的左側和右側加入元素。 ```html Headline ``` ### 連結 {#example-link} 透過設定 `href` 屬性，即可將清單項目轉換為連結。此時，你還可使用下列與連結相關的屬性：`download`、`target` 和 `rel`。 ```html Headline ``` ### 停用狀態 {#example-disabled} 在 `` 元件上加上 `disabled` 屬性，可停用該清單項目。此時，清單項目中的核取方塊、單選按鈕、開關等元件也會被一併停用。 ```html Headline Headline ``` ### 啟用狀態 {#example-active} 在 `` 元件上加上 `active` 屬性，可以啟用該清單項目。 ```html Headline Headline ``` ### 不可點選狀態 {#example-nonclickable} 在 `` 元件上加上 `nonclickable` 屬性，可以移除清單項目上的滑鼠懸停和點選漣漪效果。 ```html Headline Headline ``` ### 圓角形狀 {#example-rounded} 在 `` 元件上加上 `rounded` 屬性，可以使該清單項目呈現圓角形狀。 ```html Headline Headline ``` ### 垂直對齊方式 {#example-alignment} 在 `` 元件上設定 `alignment` 屬性，可以調整清單項目左右兩側元素與清單項目的對齊方式。其值可以為： - `start`：頂部對齊 - `center`：居中對齊 - `end`：底部對齊 ```html Headline Headline Headline ``` ### 自訂內容 {#example-custom} 在 `` 元件中使用 `custom` slot，可以完全自訂清單項目的內容。 ```html
test
 ``` ## mdui-list-item API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
headline headline true string

主文字。也可以透過 default slot 設定
headline-line headlineLine true 1 | 2 | 3

主文字行數，超過限制後將截斷顯示。預設無行數限制。可選值包括：

  • 1：顯示單行，超出後截斷
  • 2：顯示兩行，超出後截斷
  • 3：顯示三行，超出後截斷
description description true string

副文字。也可以透過 slot="description" 設定
description-line descriptionLine true 1 | 2 | 3

副文字行數，超過限制後將截斷顯示。預設無行數限制。可選值包括：

  • 1：顯示單行，超出後截斷
  • 2：顯示兩行，超出後截斷
  • 3：顯示三行，超出後截斷
icon icon true string

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

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

是否停用該清單項目，停用後，清單項目將變為灰色，且其中的 <mdui-checkbox>、<mdui-radio>、<mdui-switch> 等也將停用
active active true boolean false

是否啟用該清單項目
nonclickable nonclickable true boolean false

是否使清單項目不可點擊。設定後，清單項目中的 <mdui-checkbox>、<mdui-radio>、<mdui-switch> 等仍可互動
rounded rounded true boolean false

是否使用圓角形狀的清單項目
alignment alignment true 'start' | 'center' | 'end' 'center'

清單項目的垂直對齊方式。可選值包括：

  • start：頂部對齊
  • center：置中對齊
  • end：底部對齊
href href true string

連結的目標 URL。

若設定此屬性，元件內部將渲染為 <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 鍵切換焦點時的順序
### 方法
名稱 說明
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
### Slots
名稱 說明
預設

主文字
description

副文字
icon

清單項目左側的元素
end-icon

清單項目右側的元素
custom

任意自訂內容
### CSS Parts
名稱 說明
container

清單項目容器
icon

左側圖示
end-icon

右側圖示
body

中間部分
headline

主標題
description

副標題
### CSS 自訂屬性
名稱 說明
--shape-corner

清單項目的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
--shape-corner-rounded

指定了 rounded 屬性時，清單項目的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
## mdui-list-subheader API ### Slots
名稱 說明
預設

清單副標題文字
## mdui-list API ### Slots
名稱 說明
預設

<mdui-list-item> 元素
# 選單元件 Menu 選單元件提供一組垂直排列的項目。當使用者與按鈕或其他控制項互動時，會顯示選單。 如果你需要建立下拉選單，可以搭配 [``](/zh-tw/docs/2/components/dropdown) 元件。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/menu.js'; import 'mdui/components/menu-item.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Menu } from 'mdui/components/menu.js'; import type { MenuItem } from 'mdui/components/menu-item.js'; ``` 使用範例： ```html Item 1 Item 2 ``` ## 範例 {#examples} ### 下拉選單 {#example-dropdown} 搭配 [``](/zh-tw/docs/2/components/dropdown) 元件來建立下拉選單。 ```html open dropdown Item 1 Item 2 ``` ### 緊湊佈局 {#example-dense} 在 `` 元件上加上 `dense` 屬性，可以做成緊湊佈局。 ```html Item 1 Item 2 Item 3 ``` ### 停用選單項目 {#example-disabled} 在 `` 元件上加上 `disabled` 屬性，可以停用該選單項目。 ```html Item 1 Item 2 Item 3 ``` ### 支援單選 {#example-selects-single} 在 `` 元件上指定 `selects` 屬性為 `single`，可以做成單選功能。此時 `` 的 `value` 值即為目前選取的 `` 的 `value` 值。 ```html Item 1 Item 2 ``` ### 支援多選 {#example-selects-multiple} 在 `` 元件上指定 `selects` 屬性為 `multiple`，可以做成多選功能。此時 `` 的 `value` 值即為目前選取的 `` 的 `value` 值所組成的陣列。 注意：在多選模式下，`` 的 `value` 值為陣列，只能透過 JavaScript 屬性來讀取和設定該值。 ```html Item 1 Item 2 Item 3 ``` ### 圖示 {#example-icon} 在 `` 元件上，透過設定 `icon` 和 `end-icon` 屬性，可以分別在選單項目的左側和右側加入 Material Icons 圖示。透過設定 `end-text` 屬性，則可以在右側加入文字。此外，也可以透過 `icon`、`end-icon` 和 `end-text` slot 在選單項目的左側和右側加入圖示和文字。 如果需要在選單項目左側空出一個圖示的位置以保持與其他選單項目的對齊，可以將 `icon` 屬性設定為空字串。 ```html Item 1 Item 2 Ctrl+X Item 3 ``` 在單選或多選模式下，可以透過 `selected-icon` 屬性或 `selected-icon` slot 設定選取狀態的圖示。 ```html Item 1 Item 2 ``` ### 連結 {#example-link} 在 `` 元件上設定 `href` 屬性，即可將選單項目轉為連結，並可使用以下連結相關的屬性：`download`、`target` 和 `rel`。 ```html Item 1 Item 2 ``` ### 子選單 {#example-submenu} 在 `` 元件中，可以使用 `submenu` slot 來指定子選單項目的元素。 ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` 在 `` 元件上，可以透過 `submenu-trigger` 屬性設定子選單的觸發方式。 ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` 當 `submenu-trigger` 屬性設定為 `hover` 時，可以在 `` 元件上透過 `submenu-open-delay` 和 `submenu-close-delay` 屬性設定子選單的開啟延遲和關閉延遲。 ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` ### 自訂內容 {#example-custom} 在 `` 元件中，你可以使用 `custom` slot 來完全自訂選單項目的內容。 ```html
ABS
取數值的絕對值
ACOS
數值的反餘弦值，以弧度表示
ACOSH
數值的反雙曲餘弦值
 ``` ## mdui-menu-item API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
value value true string

選單項目的值
disabled disabled true boolean false

是否停用選單項目
icon icon true string

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

如果左側不需要顯示圖示，但需要預留一個圖示的位置，可傳入空字串進行佔位
end-icon endIcon true string

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

右側的文字。也可以透過 slot="end-text" 設定
selected-icon selectedIcon true string

選取狀態的 Material Icons 圖示名。也可以透過 slot="selected-icon" 設定
submenu-open submenuOpen true boolean false

是否開啟子選單
href href true string

連結的目標 URL。

若設定此屬性，元件內部將渲染為 <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 鍵切換焦點時的順序
### 方法
名稱 說明
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
submenu-open

子選單開始開啟時，事件被觸發。可以透過呼叫 event.preventDefault() 阻止子選單開啟
submenu-opened

子選單開啟動畫完成時，事件被觸發
submenu-close

子選單開始關閉時，事件被觸發。可以透過呼叫 event.preventDefault() 阻止子選單關閉
submenu-closed

子選單關閉動畫完成時，事件被觸發
### Slots
名稱 說明
預設

選單項目的文字
icon

選單項目左側圖示
end-icon

選單項目右側圖示
end-text

選單右側的文字
selected-icon

選取狀態的圖示
submenu

子選單
custom

任意自訂內容
### CSS Parts
名稱 說明
container

選單項目的容器
icon

左側的圖示
label

文字內容
end-icon

右側的圖示
end-text

右側的文字
selected-icon

選取狀態的圖示
submenu

子選單元素
## mdui-menu API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
selects selects true 'single' | 'multiple'

選單項的可選狀態。預設不可選。可選值包括：

  • single：單選
  • multiple：多選
value value false string | string[]

目前選取的 <mdui-menu-item> 的值。

Note：該屬性的 HTML 屬性始終為字串，僅在 selects="single" 時可透過 HTML 屬性設定初始值；該屬性的 JavaScript 屬性值在 selects="single" 時為字串，在 selects="multiple" 時為字串陣列。因此，在 selects="multiple" 時，若要修改該值，只能透過修改 JavaScript 屬性值來實作。
dense dense true boolean false

選單項是否使用緊湊版面
submenu-trigger submenuTrigger true 'click' | 'hover' | 'focus' | 'manual' | string 'click hover'

子選單的觸發方式，支援多個值，用空格分隔。可選值包括：

  • click：點擊選單項時開啟子選單
  • hover：滑鼠懸停到選單項上時開啟子選單
  • focus：聚焦到選單項上時開啟子選單
  • manual：僅能透過程式方式開啟和關閉子選單，不能再指定其他觸發方式
submenu-open-delay submenuOpenDelay true number 200

滑鼠懸停觸發子選單開啟的延遲，單位毫秒
submenu-close-delay submenuCloseDelay true number 200

滑鼠懸停觸發子選單關閉的延遲，單位毫秒
### 方法
名稱 說明
focus(options?: FocusOptions): void

將焦點設定在目前元素上
blur(): void

從目前元素中移除焦點
### 事件
名稱 說明
change

選單項選取狀態變化時觸發
### Slots
名稱 說明
預設

子選單項（<mdui-menu-item>）、分隔線（<mdui-divider>）等元素
### CSS 自訂屬性
名稱 說明
--shape-corner

元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 底部導覽列元件 NavigationBar 導覽列用來讓使用者在行動端頁面中快速切換幾個主要頁面。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/navigation-bar.js'; import 'mdui/components/navigation-bar-item.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { NavigationBar } from 'mdui/components/navigation-bar.js'; import type { NavigationBarItem } from 'mdui/components/navigation-bar-item.js'; ``` 使用範例：（範例中的 `style="position: relative"` 僅供示意，實際使用時請移除該樣式。） ```html Item 1 Item 2 Item 3 ``` **注意事項：** 該元件預設使用 `position: fixed` 定位，並會自動在 `body` 上加入 `padding-bottom` 樣式，以防止頁面內容被元件遮擋。但在以下兩種情況下，會預設使用 `position: absolute` 定位： 1. 當指定了 `scroll-target` 屬性時。此時會在 `scroll-target` 的元素上加入 `padding-bottom` 樣式。 2. 當元件位於 [``](/zh-tw/docs/2/components/layout) 中時。此時不會加入 `padding-bottom` 樣式。 ## 範例 {#examples} ### 文字標籤顯示狀態 {#example-label-visibility} 導覽列中的文字標籤預設會在導覽項目數小於等於 3 個時始終顯示；當導覽項目數大於 3 個時，則只顯示選取狀態的文字。 ```html Item 1 Item 2 Item 3
Item 1 Item 2 Item 3 Item 4 ``` 你可以透過在 `` 元件上設定 `label-visibility` 屬性來調整文字標籤的顯示狀態。可選值有： - `selected`：僅顯示選取狀態的文字 - `labeled`：始終顯示文字 - `unlabeled`：始終不顯示文字 ```html Item 1 Item 2 Item 3 selected labeled unlabeled ``` ### 位於指定容器內 {#example-scroll-target} 預設情況下，導覽列會固定在頁面底部。 如果你希望將導覽列放在指定的容器內，可以在 `` 元件上指定 `scroll-target` 屬性。該屬性的值應為可捲動內容容器的 CSS 選擇器或 DOM 元素。此時，導覽列會以父元素作為定位基準（你需要自行替父元素加上 `position: relative; overflow: hidden` 樣式）。 ```html
Item 1 Item 2 Item 3
頁面內容
``` ### 捲動時隱藏 {#example-scroll-behavior} 透過在 `` 元件上將 `scroll-behavior` 設為 `hide`，即可在頁面向下捲動時隱藏導覽列，向上捲動時顯示導覽列。 你可以使用 `scroll-threshold` 屬性，設定捲動多少像素後開始隱藏導覽列。 ```html
Item 1 Item 2 Item 3
頁面內容
``` ### 圖示 {#example-icon} 在 `` 元件上，`icon` 屬性用來設定未啟用狀態的導覽項圖示，`active-icon` 屬性則用來設定啟用狀態的導覽項圖示。也可以透過 `icon` 和 `active-icon` slot 來設定未啟用和啟用狀態的圖示元素。 ```html Item 1 Item 2 ``` ### 連結 {#example-link} 在 `` 元件上設定 `href` 屬性，可以將導覽項變為連結。此時，還可以使用與連結相關的屬性：`download`、`target`、`rel`。 ```html Item 1 Item 2 ``` ### 徽章 {#example-badge} 在 `` 元件中，可以透過 `badge` slot 加入徽章。 ```html Item 1 99+ Item 2 ``` ## mdui-navigation-bar-item API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
icon icon true string

未啟用狀態的 Material Icons 圖示名。也可以透過 slot="icon" 設定
active-icon activeIcon true string

啟用狀態的 Material Icons 圖示名。也可以透過 slot="active-icon" 設定
value value true string

導覽項的值
href href true string

連結的目標 URL。

若設定此屬性，元件內部將渲染為 <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 鍵切換焦點時的順序
### 方法
名稱 說明
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
### Slots
名稱 說明
預設

導覽項文字
icon

圖示
active-icon

啟用狀態的圖示元素
badge

徽章
### CSS Parts
名稱 說明
container

導覽項容器
indicator

指示器
badge

徽章
icon

圖示
active-icon

啟用狀態的圖示
label

導覽項文字
### CSS 自訂屬性
名稱 說明
--shape-corner-indicator

指示器的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
## mdui-navigation-bar API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
hide hide true boolean false

是否隱藏
label-visibility labelVisibility true 'auto' | 'selected' | 'labeled' | 'unlabeled' 'auto'

文字的可視狀態。可選值包括：

  • auto：當選項小於等於3個時，始終顯示文字；當選項大於3個時，僅顯示選取狀態的文字
  • selected：僅在選取狀態顯示文字
  • labeled：始終顯示文字
  • unlabeled：始終不顯示文字
value value true string

目前選取的 <mdui-navigation-bar-item> 的值
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

捲動行為。可選值包括：

  • hide：捲動時隱藏
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

需要監聽捲動事件的目標元素。值可以是 CSS 選擇器、DOM 元素、或 JQ 物件。預設監聽 window 的捲動事件
scroll-threshold scrollThreshold true number

觸發捲動行為所需的捲動距離，單位為 px
order order true number

該元件在 <mdui-layout> 中的版面順序，按從小到大排序。預設為 0
### 事件
名稱 說明
change

值變化時觸發
show

開始顯示時觸發。可透過呼叫 event.preventDefault() 阻止顯示
shown

顯示動畫完成時，事件被觸發
hide

開始隱藏時觸發。可透過呼叫 event.preventDefault() 阻止隱藏
hidden

隱藏動畫完成時，事件被觸發
### Slots
名稱 說明
預設

<mdui-navigation-bar-item> 元件
### CSS 自訂屬性
名稱 說明
--shape-corner

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

元件的 CSS z-index 值
# 導覽抽屜元件 NavigationDrawer 導覽抽屜用來在頁面側邊提供導覽功能，讓使用者能夠快速存取不同的頁面或內容。 通常，你可以在導覽抽屜中使用 [``](/zh-tw/docs/2/components/list) 元件來加入導覽項。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/navigation-drawer.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { NavigationDrawer } from 'mdui/components/navigation-drawer.js'; ``` 使用範例： ```html 關閉導覽抽屜 開啟導覽抽屜 ``` **注意事項：** 該元件預設使用 `position: fixed` 定位。 當 `modal` 屬性為 `false`，且斷點大於等於 [`--mdui-breakpoint-md`](/zh-tw/docs/2/styles/design-tokens#breakpoint) 時，會自動在 `body` 上加入 `padding-left` 或 `padding-right` 樣式，以避免頁面內容被該元件遮擋。 但在以下兩種情況下，會預設使用 `position: absolute` 定位： 1. `contained` 屬性為 `true` 時。 2. 當元件位於 [``](/zh-tw/docs/2/components/layout) 中時。此時不會加入 `padding-left` 或 `padding-right` 樣式。 ## 範例 {#examples} ### 位於指定容器內 {#example-contained} 預設情況下，導覽抽屜會固定在頁面左側或右側。如果你希望把導覽抽屜放在指定容器內，可以加上 `contained` 屬性，此時導覽抽屜會以父元素作為定位基準（你需要自行替父元素加上樣式 `position: relative; overflow: hidden;`）。 ```html
關閉導覽抽屜
開啟導覽抽屜
``` ### 模態化 {#example-modal} 加上 `modal` 屬性可以在開啟導覽抽屜時顯示遮罩層。請注意，在視窗或父元素寬度小於 [`--mdui-breakpoint-md`](/zh-tw/docs/2/styles/design-tokens#breakpoint) 時，會忽略此參數，始終顯示遮罩層。 加上 `close-on-esc` 屬性，可以在按下 ESC 鍵時關閉導覽抽屜。 加上 `close-on-overlay-click` 屬性，可以在點擊遮罩層時關閉導覽抽屜。 ```html
關閉導覽抽屜
開啟導覽抽屜
``` ### 位於右側 {#example-placement} 透過將 `placement` 屬性設定為 `right`，可以將導覽抽屜顯示在頁面右側。 ```html
關閉導覽抽屜
開啟導覽抽屜
``` ## mdui-navigation-drawer API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
open open true boolean false

是否開啟抽屜導覽列
modal modal true boolean false

抽屜導覽列開啟時，是否顯示遮罩層

在窄螢幕裝置上（螢幕寬度小於 --mdui-breakpoint-md），會始終顯示遮罩層，無視該參數
close-on-esc closeOnEsc true boolean false

在有遮罩層的情況下，按下 ESC 鍵是否關閉抽屜導覽列
close-on-overlay-click closeOnOverlayClick true boolean false

點擊遮罩層時，是否關閉抽屜導覽列
placement placement true 'left' | 'right' 'left'

抽屜導覽列的位置。可選值包括：

  • left：左側
  • right：右側
contained contained true boolean false

預設情況下，抽屜導覽列相對於 body 元素顯示。當該屬性設定為 true 時，抽屜導覽列將相對於其父元素顯示。

Note：設定該屬性時，必須在父元素上手動設定樣式 position: relative; overflow: hidden;。
order order true number

該元件在 <mdui-layout> 中的版面順序，按從小到大排序。預設為 0
### 事件
名稱 說明
open

抽屜導覽列開啟前觸發。可透過呼叫 event.preventDefault() 阻止抽屜導覽列開啟
opened

抽屜導覽列開啟動畫完成之後觸發
close

抽屜導覽列關閉前觸發。可透過呼叫 event.preventDefault() 阻止抽屜導覽列關閉
closed

抽屜導覽列關閉動畫完成之後觸發
overlay-click

點擊遮罩層時觸發
### Slots
名稱 說明
預設

抽屜導覽列中的內容
### CSS Parts
名稱 說明
overlay

遮罩層
panel

抽屜導覽列容器
### CSS 自訂屬性
名稱 說明
--shape-corner

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

元件的 CSS z-index 值
# 側邊導覽列元件 NavigationRail 側邊導覽列為平板電腦和桌上型電腦提供了存取不同主頁面的方式。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/navigation-rail.js'; import 'mdui/components/navigation-rail-item.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { NavigationRail } from 'mdui/components/navigation-rail.js'; import type { NavigationRailItem } from 'mdui/components/navigation-rail-item.js'; ``` 使用範例：（範例中的 `style="position: relative"` 僅供示意，實際使用時請移除該樣式。） ```html Recent Images Library ``` **注意事項：** 該元件預設使用 `position: fixed` 定位，並會自動在 `body` 上加入 `padding-left` 或 `padding-right` 樣式，以防止頁面內容被該元件遮擋。 但在以下兩種情況下，會預設使用 `position: absolute` 定位： 1. `` 元件的 `contained` 屬性為 `true` 時。此時會在父元素上加入 `padding-left` 或 `padding-right` 樣式。 2. 當位於 [``](/zh-tw/docs/2/components/layout) 元件中時。此時不會加入 `padding-left` 或 `padding-right` 樣式。 ## 範例 {#examples} ### 位於指定容器內 {#example-contained} 預設情況下，側邊導覽列會固定在頁面左側或右側。如果你希望將側邊導覽列放在指定的容器內，可以在 `` 元件上加上 `contained` 屬性，此時側邊導覽列會以其父元素作為定位基準（你需要自行替父元素加上 `position: relative` 樣式）。 ```html
Recent Images Library
頁面內容
``` ### 位於右側 {#example-placement} 在 `` 元件上設定 `placement` 屬性為 `right`，可以將側邊導覽列顯示在右側。 ```html
Recent Images Library
頁面內容
``` ### 顯示分割線 {#example-divider} 在 `` 元件上加上 `divider` 屬性，可以在側邊導覽列上加入一條分割線，以便和頁面內容區分開。 ```html
Recent Images Library
頁面內容
``` ### 在頂部/底部加入元素 {#example-top-bottom} 你可以在 `` 元件內透過 `top`、`bottom` slot 在頂部和底部加入元素。 ```html
Recent Images Library
頁面內容
``` ### 導覽項垂直對齊方式 {#example-alignment} 透過設定 `` 元件的 `alignment` 屬性，可以修改導覽項的垂直對齊方式。 ```html
Recent Images Library
start center end
``` ### 圖示 {#example-icon} 在 `` 元件上，可以使用 `icon` 屬性設定未啟用狀態的導覽項圖示，使用 `active-icon` 屬性設定啟用狀態的導覽項圖示。也可以透過 `icon` 和 `active-icon` slot 設定未啟用和啟用狀態的圖示元素。 ```html
Recent Images Library
頁面內容
``` ### 僅使用圖示 {#example-no-label} `` 元件可以僅使用圖示，不加入文字。 ```html
頁面內容
``` ### 連結 {#example-link} 在 `` 元件上設定 `href` 屬性，可將導覽項設為連結。此時，還可以使用這些連結相關的屬性：`download`、`target`、`rel`。 ```html
Recent Images Library
頁面內容
``` ### 徽章 {#example-badge} 在 `` 元件中，可以透過 `badge` slot 加入徽章。 ```html
Recent 99+ Images Library
頁面內容
``` ## mdui-navigation-rail-item API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
icon icon true string

未啟用狀態下的 Material Icons 圖示名。也可以透過 slot="icon" 設定
active-icon activeIcon true string

啟用狀態下的 Material Icons 圖示名。也可以透過 slot="active-icon" 設定
value value true string

導覽項的值
href href true string

連結的目標 URL。

若設定此屬性，元件內部將渲染為 <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 鍵切換焦點時的順序
### 方法
名稱 說明
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
### Slots
名稱 說明
預設

文字內容
icon

圖示
active-icon

啟用狀態的圖示
badge

徽章
### CSS Parts
名稱 說明
container

導覽項目容器
indicator

指示器
badge

徽章
icon

圖示
active-icon

啟用狀態的圖示
label

文字內容
### CSS 自訂屬性
名稱 說明
--shape-corner-indicator

指示器的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
## mdui-navigation-rail API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
value value true string

目前選取的 <mdui-navigation-rail-item> 的值
placement placement true 'left' | 'right' 'left'

導覽列的位置。可選值包括：

  • left：左側
  • right：右側
alignment alignment true 'start' | 'center' | 'end' 'start'

<mdui-navigation-rail-item> 元素的對齊方式。可選值包括：

  • start：頂部對齊
  • center：置中對齊
  • end：底部對齊
contained contained true boolean false

預設情況下，導覽列相對於 body 元素顯示。當該屬性設定為 true 時，導覽列將相對於其父元素顯示。

Note：設定該屬性時，必須在父元素上手動設定樣式 position: relative;。
divider divider true boolean false

是否在導覽列和頁面內容之間新增分隔線
order order true number

該元件在 <mdui-layout> 中的版面順序，按從小到大排序。預設為 0
### 事件
名稱 說明
change

值變化時觸發
### Slots
名稱 說明
預設

<mdui-navigation-rail-item> 元件
top

頂部的元素
bottom

底部的元素
### CSS Parts
名稱 說明
top

頂部元素的容器
bottom

底部元素的容器
items

<mdui-navigation-rail-item> 元件的容器
### CSS 自訂屬性
名稱 說明
--shape-corner

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

元件的 CSS z-index 值
# 單選按鈕元件 Radio 單選按鈕用來讓使用者在一組選項中選擇其中一個，確保每次只能選中一個選項。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/radio-group.js'; import 'mdui/components/radio.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { RadioGroup } from 'mdui/components/radio-group.js'; import type { Radio } from 'mdui/components/radio.js'; ``` 使用範例： ```html Chinese English ``` ## 範例 {#examples} ### 選取狀態 {#example-checked} `` 元件的 `value` 屬性值即為目前選取的 `` 元件的 `value` 屬性值。你也可以透過更新 `` 元件的 `value` 屬性值，來切換目前選取的單選按鈕。 ```html Chinese English ``` 你可以單獨使用 `` 元件，此時可以透過 `checked` 屬性來讀取和修改選取狀態。 ```html Radio ``` ### 停用狀態 {#example-disabled} 你可以透過在 `` 元件上加上 `disabled` 屬性，來停用整個單選按鈕組。 ```html Chinese English ``` 如果需要停用特定的單選按鈕，可以在 `` 元件上加上 `disabled` 屬性。 ```html Chinese English ``` ### 圖示 {#example-icon} 你可以透過設定 `unchecked-icon` 和 `checked-icon` 屬性，分別定義未選取和選取狀態下的單選按鈕的 Material Icons 圖示。也可以透過 `unchecked-icon` 和 `checked-icon` slot 來設定。 ```html Chinese English ``` ## mdui-radio-group API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
disabled disabled true boolean false

是否停用此元件
form form true string

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

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

單選按鈕群組的名稱，將與表單資料一起送出
value value true string ''

單選按鈕群組目前選取的值，將與表單資料一起送出
undefined defaultValue false string ''

預設選取的值。在重設表單時，將重設為該預設值。該屬性只能透過 JavaScript 屬性設定
required required true boolean false

送出表單時，是否必須選取其中一個單選按鈕
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false string

如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串
### 方法
名稱 說明
checkValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true
reportValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true。

如果驗證未通過，還會在元件上顯示驗證失敗的提示。
setCustomValidity(message: string): void

設定自訂的錯誤提示文字。只要這個文字不為空，就表示欄位未通過驗證
### 事件
名稱 說明
change

選取值變化時觸發
input

選取值變化時觸發
invalid

表單欄位驗證未通過時觸發
### Slots
名稱 說明
預設

<mdui-radio> 元素
## mdui-radio API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
value value true string ''

目前單選項的值
disabled disabled true boolean false

是否停用目前單選項
checked checked true boolean false

目前單選項是否已選取
unchecked-icon uncheckedIcon true string

未選取狀態的 Material Icons 圖示名。也可以透過 slot="unchecked-icon" 設定
checked-icon checkedIcon true string

選取狀態的 Material Icons 圖示名。也可以透過 slot="checked-icon" 設定
autofocus autofocus true boolean false

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

元素在使用 Tab 鍵切換焦點時的順序
### 方法
名稱 說明
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
change

選取該單選項時觸發
### Slots
名稱 說明
預設

文字內容
unchecked-icon

未選取狀態的圖示
checked-icon

選取狀態的圖示
### CSS Parts
名稱 說明
control

左側圖示容器
unchecked-icon

未選取狀態的圖示
checked-icon

選取狀態的圖示
label

文字內容
# 範圍滑桿元件 RangeSlider 範圍滑桿元件用來讓使用者在一系列值中選擇一個範圍。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/range-slider.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { RangeSlider } from 'mdui/components/range-slider.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 預設值 {#example-value} 透過 `value` 屬性，你可以讀取或設定範圍滑桿的目前值。該屬性值是一個陣列，只能透過 JavaScript 屬性進行讀取和設定。 ```html ``` ### 停用狀態 {#example-disabled} 加上 `disabled` 屬性可以停用範圍滑桿。 ```html ``` ### 範圍 {#example-min-max} 使用 `min` 和 `max` 屬性設定範圍滑桿的最小值和最大值。 ```html ``` ### 步進間隔 {#example-step} 使用 `step` 屬性設定範圍滑桿的步進間隔。 ```html ``` ### 刻度標記 {#example-tickmarks} 加上 `tickmarks` 屬性可以在範圍滑桿上加入刻度標記。 ```html ``` ### 隱藏文字提示 {#example-nolabel} 加上 `nolabel` 屬性可以隱藏範圍滑桿上的文字提示。 ```html ``` ### 修改文字提示 {#example-labelFormatter} 你可以透過 `labelFormatter` JavaScript 屬性，修改文字提示的顯示格式。該屬性值是一個函式，函式參數為目前範圍滑桿的值，回傳值為你期望顯示的文字。 ```html ``` ## mdui-range-slider API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
undefined defaultValue false number[] []

預設值。在重設表單時，將重設為該預設值。此屬性只能透過 JavaScript 屬性設定
undefined value false number[]

滑桿的值，為陣列格式，將與表單資料一起送出。

NOTE：該屬性無法透過 HTML 屬性設定初始值，如果要修改該值，只能透過修改 JavaScript 屬性值來實作。
autofocus autofocus true boolean false

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

元素在使用 Tab 鍵切換焦點時的順序
min min true number 0

滑桿的最小值，預設為 0
max max true number 100

滑桿的最大值，預設為 100
step step true number 1

步進間隔，預設為 1
tickmarks tickmarks true boolean false

是否新增刻度標記
nolabel nolabel true boolean false

是否隱藏文字提示
disabled disabled true boolean false

是否被停用
form form true string

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

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

滑桿的名稱，該名稱將與表單資料一起送出
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false string

如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串
undefined labelFormatter false (value: number) => 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

值發生變更，且失去焦點時，將觸發該事件
input

值變更時觸發
invalid

表單欄位驗證未通過時觸發
### CSS Parts
名稱 說明
track-inactive

未啟用狀態的軌道
track-active

已啟用狀態的軌道
handle

操作桿
label

提示文字
tickmark

刻度標記
# 選擇框元件 Select 下拉選擇框元件可在下拉選單中提供多種選項，方便使用者快速選取所需內容。 本頁面主要介紹 `` 元件的使用方法，關於下拉選單項目的用法，請參見 [``](/zh-tw/docs/2/components/menu#menu-item-api)。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/select.js'; import 'mdui/components/menu-item.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Select } from 'mdui/components/select.js'; import type { MenuItem } from 'mdui/components/menu-item.js'; ``` 使用範例： ```html Item 1 Item 2 ``` ## 範例 {#examples} ### 樣式 {#example-variant} 透過 `variant` 屬性設定下拉選擇框的樣式。 ```html Item 1 Item 2 Item 1 Item 2 ``` ### 支援多選 {#example-multiple} 下拉選擇框預設為單選，`` 元件的 `value` 值即為目前選取的 [``](/zh-tw/docs/2/components/menu#menu-item-api) 的 `value` 值。 加上 `multiple` 屬性可讓下拉選擇框支援多選。此時 `` 的 `value` 值為目前選取的 [``](/zh-tw/docs/2/components/menu#menu-item-api) 的 `value` 值所組成的陣列。 注意：在支援多選時，`` 的 `value` 值為陣列，只能透過 JavaScript 屬性來讀取和設定該值。 ```html Item 1 Item 2 Item 3 ``` ### 輔助文字 {#example-helper-text} 使用 `label` 屬性設定下拉選擇框上方的標籤文字。 ```html Item 1 Item 2 ``` 使用 `placeholder` 屬性設定未選取值時的佔位文字。 ```html Item 1 Item 2 ``` 使用 `helper` 屬性設定下拉選擇框底部的輔助文字。也可以使用 `helper` slot 來設定輔助文字。 ```html Item 1 Item 2 Item 1 Item 2 Supporting text ``` ### 唯讀模式 {#example-readonly} 加上 `readonly` 屬性，可以將下拉選擇框設定為唯讀模式。 ```html Item 1 Item 2 ``` ### 停用狀態 {#example-disabled} 加上 `disabled` 屬性，即可停用下拉選擇框。 ```html Item 1 Item 2 ``` ### 可清除 {#example-clearable} 加上 `clearable` 屬性後，當下拉選擇框有值時，右側會出現一個清除按鈕。 ```html Item 1 Item 2 ``` 也可以透過 `clear` slot 自訂清除按鈕。 ```html Item 1 Item 2 ``` ### 下拉選單位置 {#example-placement} 透過 `placement` 屬性，你可以設定下拉選單的位置。 ```html Item 1 Item 2 ``` ### 文字靠右對齊 {#example-end-aligned} 加上 `end-aligned` 屬性，即可讓文字靠右對齊。 ```html Item 1 Item 2 ``` ### 前後文字及圖示 {#example-prefix-suffix} 透過設定 `icon` 和 `end-icon` 屬性，可以在下拉選擇框的左側和右側加入 Material Icons 圖示。你也可以透過 `icon` 和 `end-icon` slot 在下拉選擇框的左側和右側加入元素。 ```html Item 1 Item 2

Item 1 Item 2 ``` 透過設定 `prefix` 和 `suffix` 屬性，可以在下拉選擇框的左側和右側加入文字。也可以透過 `prefix` 和 `suffix` slot 在下拉選擇框的左側和右側加入文字元素。這些文字只有在下拉選擇框取得焦點或有值時才會顯示。 ```html Item 1 Item 2

Item 1 Item 2 $ /100 ``` ## mdui-select API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'filled' | 'outlined' 'filled'

選擇框的樣式。可選值包括：

  • filled：帶背景色的選擇框，視覺效果較強
  • outlined：帶邊框的選擇框，視覺效果較弱
multiple multiple true boolean false

是否支援多選
name name true string ''

選擇框的名稱，將與表單資料一起送出
value value false string | string[] ''

選擇框的值，將與表單資料一起送出。

如果未指定 multiple 屬性，該值為字串；如果指定了 multiple 屬性，該值為字串陣列。HTML 屬性只能設定字串值；如果需要設定陣列值，請透過 JavaScript 屬性設定。
undefined defaultValue false string | string[] ''

預設選取的值。在重設表單時，將重設為該預設值。該屬性只能透過 JavaScript 屬性設定
label label true string

標籤文字
placeholder placeholder true string

佔位符文字
helper helper true string

選擇框底部的說明文字。也可以透過 slot="helper" 設定
clearable clearable true boolean false

是否可以清空選擇框
clear-icon clearIcon true string

當選擇框可清空時，顯示在選擇框右側的清空按鈕的 Material Icons 圖示名。也可以透過 slot="clear-icon" 設定
placement placement true 'auto' | 'bottom' | 'top' 'auto'

選擇框的位置。可選值包括：

  • auto：自動判斷位置
  • bottom：位於下方
  • top：位於上方
end-aligned endAligned true boolean false

文字是否右對齊
prefix prefix true string

選擇框的前綴文字。僅在聚焦狀態，或選擇框有值時才會顯示。也可以透過 slot="prefix" 設定
suffix suffix true string

選擇框的後綴文字。僅在聚焦狀態，或選擇框有值時才會顯示。也可以透過 slot="suffix" 設定
icon icon true string

選擇框的前綴圖示的 Material Icons 圖示名。也可以透過 slot="icon" 設定
end-icon endIcon true string

選擇框的後綴圖示的 Material Icons 圖示名。也可以透過 slot="end-icon" 設定
error-icon errorIcon true string

表單欄位驗證失敗時，顯示在選擇框右側的 Material Icons 圖示名。也可以透過 slot="error-icon" 設定
form form true string

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

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

是否為唯讀狀態
disabled disabled true boolean false

是否為停用狀態
required required true boolean false

送出表單時，是否必須填寫該欄位
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false string

如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串
autofocus autofocus true boolean false

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

元素在使用 Tab 鍵切換焦點時的順序
### 方法
名稱 說明
checkValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true
reportValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true。

如果驗證未通過，還會在元件上顯示驗證失敗的提示。
setCustomValidity(message: string): void

設定自訂的錯誤提示文字。只要這個文字不為空，就表示欄位未通過驗證
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
change

選取的值變更時觸發
invalid

表單欄位驗證未通過時觸發
clear

在點擊由 clearable 屬性產生的清空按鈕時觸發。可以透過呼叫 event.preventDefault() 阻止清空選擇框
### Slots
名稱 說明
預設

<mdui-menu-item> 元素
icon

左側圖示
end-icon

右側圖示
error-icon

驗證失敗狀態的右側圖示
prefix

左側文字
suffix

右側文字
clear-button

清空按鈕
clear-icon

清空按鈕中的圖示
helper

底部的說明文字
### CSS Parts
名稱 說明
chips

多選時，放置選取值對應的 chip 的容器
chip

多選時，每一個選取的值對應的 chip
chip__button

chip 內部的 <button> 元素
chip__label

chip 內部的文字
chip__delete-icon

chip 內部的刪除圖示
text-field

文字欄位，即 <mdui-text-field> 元素
text-field__container

text-field 內部的文字欄位容器
text-field__icon

text-field 內部的左側圖示
text-field__end-icon

text-field 內部的右側圖示
text-field__error-icon

text-field 內部的驗證失敗狀態的右側圖示
text-field__prefix

text-field 內部的左側文字
text-field__suffix

text-field 內部的右側文字
text-field__label

text-field 內部的標籤文字
text-field__input

text-field 內部的 <input> 元素
text-field__clear-button

text-field 內部的清空按鈕
text-field__clear-icon

text-field 內部的清空按鈕中的圖示
text-field__supporting

text-field 內部的底部輔助資訊容器，包括 helper 和 error
text-field__helper

text-field 內部的底部說明文字
text-field__error

text-field 內部的底部錯誤描述文字
menu

下拉選單，即 <mdui-menu> 元素
# 分段按鈕元件 SegmentedButton 分段按鈕元件封裝了一組按鈕，用於提供選項、切換視圖或對元素進行排序等。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/segmented-button-group.js'; import 'mdui/components/segmented-button.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { SegmentedButtonGroup } from 'mdui/components/segmented-button-group.js'; import type { SegmentedButton } from 'mdui/components/segmented-button.js'; ``` 使用範例： ```html Day Week Month ``` ## 範例 {#examples} ### 全寬顯示 {#example-full-width} 在 `` 元素上加上 `full-width` 屬性，可使元件佔滿整個寬度。 ```html Day Week Month ``` ### 單選模式 {#example-selects-single} 在 `` 元素上指定 `selects` 屬性為 `single`，即可做成單選模式。此時 `` 的 `value` 屬性值即為目前選取的 `` 的 `value` 屬性的值。 ```html Day Week Month Day Week Month ``` ### 多選模式 {#example-selects-multiple} 在 `` 元素上指定 `selects` 屬性為 `multiple`，即可做成多選模式。此時 `` 的 `value` 屬性值為目前選取的 `` 的 `value` 屬性的值所組成的陣列。 注意：在多選模式下，`` 的 `value` 屬性值為陣列，只能透過 JavaScript 屬性來讀取和設定該值。 ```html Day Week Month Day Week Month ``` ### 圖示 {#example-icon} 在 `` 元素上，透過設定 `icon` 和 `end-icon` 屬性，可以在按鈕的左側和右側加入 Material Icons 圖示。另外，也可以透過 `icon` 和 `end-icon` slot 在按鈕的左側和右側加入元素。 ```html Day Week Month ``` 在 `` 元素上，透過加上 `selected-icon` 屬性，可以設定選取狀態的 Material Icons 圖示。也可以透過 `selected-icon` slot 進行設定。 ```html Day Week ``` ### 連結 {#example-link} 在 `` 元素上，透過設定 `href` 屬性，即可將按鈕轉換為連結。此時，還可使用下列與連結相關的屬性：`download`、`target`、`rel`。 ```html Link Week Month ``` ### 停用及載入中狀態 {#example-disabled} 在 `` 元素上，透過加上 `disabled` 屬性，即可停用整個分段按鈕組。 ```html Day Week Month ``` 在 `` 元素上，透過加上 `disabled` 屬性，即可停用特定按鈕；透過加上 `loading` 屬性，則可為特定按鈕加入載入中狀態。 ```html Day Week Month Year ``` ## mdui-segmented-button-group API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
full-width fullWidth true boolean false

是否填滿父元素寬度
selects selects true 'single' | 'multiple'

分段按鈕的可選取狀態，預設為不可選取。可選值包括：

  • single：單選
  • multiple：多選
disabled disabled true boolean false

是否為停用狀態
required required true boolean false

送出表單時，是否必須選取
form form true string

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

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

送出表單時的名稱，將與表單資料一起送出
value value false string | string[] ''

目前選取的 <mdui-segmented-button> 的值。

Note：該屬性的 HTML 屬性始終為字串，且僅在 selects="single" 時可以透過 HTML 屬性設定初始值。該屬性的 JavaScript 屬性值在 selects="single" 時為字串，在 selects="multiple" 時為字串陣列。所以，在 selects="multiple" 時，如果要修改該值，只能透過修改 JavaScript 屬性值來實作。
undefined defaultValue false string | string[] ''

預設選取的值。在重設表單時，將重設為該預設值。該屬性只能透過 JavaScript 屬性設定
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false 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 屬性 Reflect 型別 預設值 說明
icon icon true string

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

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

選取狀態的 Material Icons 圖示名。也可以透過 slot="selected-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

分段按鈕項目的左側圖示
selected-icon

選取狀態的左側圖示
end-icon

分段按鈕項目的右側圖示
### CSS Parts
名稱 說明
button

內部的 <button> 或 <a> 元素
icon

左側的圖示
selected-icon

選取狀態的左側圖示
end-icon

右側的圖示
label

文字內容
loading

載入中狀態的 <mdui-circular-progress> 元素
# 滑桿元件 Slider 滑桿元件讓使用者可以透過拖曳滑桿，在一系列數值中做出選擇。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/slider.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Slider } from 'mdui/components/slider.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 預設值 {#example-value} 透過 `value` 屬性，可以讀取或設定滑桿的目前值。 ```html ``` ### 停用狀態 {#example-disabled} 加上 `disabled` 屬性可以停用滑桿。 ```html ``` ### 範圍 {#example-min-max} 使用 `min` 和 `max` 屬性來設定滑桿的最小值和最大值。 ```html ``` ### 步進值 {#example-step} 透過 `step` 屬性，你可以設定滑桿的步進值。 ```html ``` ### 刻度標記 {#example-tickmarks} 加上 `tickmarks` 屬性，可以在滑桿上顯示刻度標記。 ```html ``` ### 隱藏文字提示 {#example-nolabel} 如果你想隱藏滑桿上的文字提示，可以加上 `nolabel` 屬性。 ```html ``` ### 修改文字提示 {#example-labelFormatter} 你可以透過 `labelFormatter` JavaScript 屬性來修改文字提示的顯示格式。這個屬性的值應該是一個函式，該函式接收目前滑桿的值作為參數，回傳你希望顯示的文字。 ```html ``` ## mdui-slider API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
value value false number 0

滑桿的值，將與表單資料一起送出
undefined defaultValue false number 0

預設值。在重設表單時，將重設為該預設值。該屬性只能透過 JavaScript 屬性設定
autofocus autofocus true boolean false

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

元素在使用 Tab 鍵切換焦點時的順序
min min true number 0

滑桿的最小值，預設為 0
max max true number 100

滑桿的最大值，預設為 100
step step true number 1

步進間隔，預設為 1
tickmarks tickmarks true boolean false

是否新增刻度標記
nolabel nolabel true boolean false

是否隱藏文字提示
disabled disabled true boolean false

是否被停用
form form true string

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

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

滑桿的名稱，該名稱將與表單資料一起送出
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false string

如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串
undefined labelFormatter false (value: number) => 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

在值發生變更，且失去焦點時，將觸發該事件
input

值變更時觸發
invalid

表單欄位驗證未通過時觸發
### CSS Parts
名稱 說明
track-inactive

未啟用狀態的軌道
track-active

已啟用狀態的軌道
handle

操作桿
label

提示文字
tickmark

刻度標記
# 消息條元件 Snackbar 消息條元件用來在頁面中顯示簡短的應用程式狀態訊息。 除了直接使用該元件外，mdui 還提供了一個 [`mdui.snackbar`](/zh-tw/docs/2/functions/snackbar) 函式，以簡化 Snackbar 元件的使用。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/snackbar.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Snackbar } from 'mdui/components/snackbar.js'; ``` 使用範例： ```html Photo archived 開啟 Snackbar ``` ## 範例 {#examples} ### 位置 {#example-placement} 透過 `placement` 屬性，你可以設定 Snackbar 的顯示位置。 ```html
Photo archived top-start Photo archived top Photo archived top-end
Photo archived bottom-start Photo archived bottom Photo archived bottom-end
``` ### 操作按鈕 {#example-action} 你可以使用 `action` 屬性在 Snackbar 的右側加上一個操作按鈕，並透過該屬性指定按鈕的文字。點擊操作按鈕會觸發 `action-click` 事件。如果你希望操作按鈕顯示為載入中狀態，可以加上 `action-loading` 屬性。 ```html Photo archived 開啟 Snackbar ``` 你也可以透過 `action` slot 在 Snackbar 的右側加入自訂元素。 ```html Photo archived Undo 開啟 Snackbar ``` ### 可關閉 {#example-closeable} 加上 `closeable` 屬性後，Snackbar 的右側會出現一個關閉按鈕。點擊該按鈕會關閉 Snackbar，並觸發 `close` 事件。 ```html Photo archived 開啟 Snackbar ``` 可以透過 `close-button` slot 來自訂關閉按鈕的元素。 ```html Photo archived 開啟 Snackbar ``` 透過設定 `close-icon` 屬性，你可以修改預設關閉按鈕中的 Material Icons 圖示。也可以透過 `close-icon` slot 來自訂關閉按鈕中的圖示元素。 ```html Photo archived 開啟 Snackbar ``` ### 文字行數 {#example-message-line} 預設情況下，訊息文字沒有行數限制。你可以透過 `message-line` 屬性來限制文字行數，最多可以設定為 2 行。 ```html The item already has the label "travel". You can add a new label. You can add a new label. 開啟 Snackbar ``` ### 自動關閉延遲 {#example-auto-close-delay} 可以使用 `auto-close-delay` 屬性來設定自動關閉的延遲，單位為毫秒。預設值為 5000 毫秒。 ```html Photo archived 開啟 Snackbar ``` ### 點擊外部區域關閉 {#example-close-on-outside-click} 加上 `close-on-outside-click` 屬性，你可以設定在點擊 Snackbar 外部區域時關閉 Snackbar。 ```html Photo archived 開啟 Snackbar ``` ## mdui-snackbar API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
open open true boolean false

是否顯示 Snackbar
placement placement true 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' 'bottom'

Snackbar 的顯示位置。預設為 bottom。可選值包括：

  • top：頂部置中
  • top-start：頂部左對齊
  • top-end：頂部右對齊
  • bottom：底部置中
  • bottom-start：底部左對齊
  • bottom-end：底部右對齊
action action true string

操作按鈕的文字。也可以透過 slot="action" 設定操作按鈕
action-loading actionLoading true boolean false

操作按鈕是否處於載入中狀態
closeable closeable true boolean false

是否在右側顯示關閉按鈕
close-icon closeIcon true string

關閉按鈕的 Material Icons 圖示名。也可以透過 slot="close-icon" 設定
message-line messageLine true 1 | 2

訊息文字的最大顯示行數。預設不限制。可選值包括：

  • 1：最多顯示一行
  • 2：最多顯示兩行
auto-close-delay autoCloseDelay true number 5000

自動關閉的延遲時間（單位：毫秒）。設定為 0 則不自動關閉。預設為 5000 毫秒
close-on-outside-click closeOnOutsideClick true boolean false

點擊或觸碰 Snackbar 以外的區域時，是否關閉 Snackbar
### 事件
名稱 說明
open

Snackbar 開始顯示時觸發。可透過呼叫 event.preventDefault() 阻止 Snackbar 顯示
opened

Snackbar 顯示動畫完成時，事件被觸發
close

Snackbar 開始隱藏時觸發。可透過呼叫 event.preventDefault() 阻止 Snackbar 關閉
closed

Snackbar 隱藏動畫完成時，事件被觸發
action-click

點擊操作按鈕時觸發
### Slots
名稱 說明
預設

Snackbar 的訊息文字內容
action

右側的操作按鈕
close-button

右側的關閉按鈕。必須設定 closeable 屬性為 true 才會顯示
close-icon

關閉按鈕中的圖示
### CSS Parts
名稱 說明
message

訊息文字
action

操作按鈕
close-button

關閉按鈕
close-icon

關閉按鈕中的圖示
### CSS 自訂屬性
名稱 說明
--shape-corner

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

元件的 CSS z-index 值
# 切換開關元件 Switch 開關元件用來切換單一選項的開啟或關閉狀態，透過直覺的互動設計，讓使用者能輕鬆調整設定。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/switch.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Switch } from 'mdui/components/switch.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 選取狀態 {#example-checked} 當開關被選取時，`checked` 屬性的值為 `true`。你也可以透過加上 `checked` 屬性，使開關預設處於選取狀態。 ```html ``` ### 停用狀態 {#example-disabled} 透過加上 `disabled` 屬性，可以停用開關元件。 ```html ``` ### 圖示 {#example-icon} 你可以透過 `unchecked-icon` 屬性來設定未選取狀態的 Material Icons 圖示，透過 `checked-icon` 屬性來設定選取狀態的 Material Icons 圖示。也可以透過 `unchecked-icon` 和 `checked-icon` slot 來自訂未選取和選取狀態的圖示元素。 ```html ``` ## mdui-switch API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
disabled disabled true boolean false

是否為停用狀態
checked checked true boolean false

是否為選取狀態
undefined defaultChecked false boolean false

預設選取狀態。在重設表單時，將重設為此狀態。此屬性只能透過 JavaScript 屬性設定
unchecked-icon uncheckedIcon true string

未選取狀態的 Material Icons 圖示名。也可以透過 slot="unchecked-icon" 設定
checked-icon checkedIcon true string

選取狀態的 Material Icons 圖示名。也可以透過 slot="checked-icon" 設定

預設為 check 圖示，可傳入空字串移除預設圖示
required required true boolean false

送出表單時，是否必須選取此開關
form form true string

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

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

開關的名稱，將與表單資料一起送出
value value true string 'on'

開關的值，將與表單資料一起送出
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false string

如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串
autofocus autofocus true boolean false

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

元素在使用 Tab 鍵切換焦點時的順序
### 方法
名稱 說明
checkValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true
reportValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true。

如果驗證未通過，還會在元件上顯示驗證失敗的提示。
setCustomValidity(message: string): void

設定自訂的錯誤提示文字。只要這個文字不為空，就表示欄位未通過驗證
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
change

選取狀態變更時觸發
input

選取狀態變更時觸發
invalid

表單欄位驗證不通過時觸發
### Slots
名稱 說明
unchecked-icon

未選取狀態的元素
checked-icon

選取狀態的元素
### CSS Parts
名稱 說明
track

軌道
thumb

圖示容器
unchecked-icon

未選取狀態的圖示
checked-icon

選取狀態的圖示
### CSS 自訂屬性
名稱 說明
--shape-corner

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

元件圖示容器的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
# 分頁元件 Tabs 分頁元件用來將內容或資料集分組並展示，方便使用者在不同類別之間快速切換。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/tabs.js'; import 'mdui/components/tab.js'; import 'mdui/components/tab-panel.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Tabs } from 'mdui/components/tabs.js'; import type { Tab } from 'mdui/components/tab.js'; import type { TabPanel } from 'mdui/components/tab-panel.js'; ``` 使用範例： ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ## 範例 {#examples} ### 分頁樣式 {#example-variant} 透過在 `` 元件上使用 `variant` 屬性，可以設定分頁的樣式。 ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 分頁位置 {#example-placement} 在 `` 元件上使用 `placement` 屬性，可以設定分頁的位置。 ```html top-start top top-end bottom-start bottom bottom-end left-start left left-end right-start right right-end Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 滿版顯示 {#example-full-width} 在 `` 元件上加上 `full-width` 屬性，可讓分頁佔滿全部寬度，各個分頁將平均分配寬度。 ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 圖示 {#example-icon} 在 `` 元件上設定 `icon` 屬性，可以在分頁上加入 Material Icons 圖示。你也可以透過 `icon` slot 加入圖示元素。 加上 `inline` 屬性可以將圖示和文字水平排列。 ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 徽章 {#example-badge} 在 `` 元件中，可以透過 `badge` slot 加入徽章。 ```html Tab 1 99+ Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### 自訂內容 {#example-custom} 在 `` 元件中使用 `custom` slot，可以完全自訂分頁的內容。 ```html Tab 1 Icon Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ## mdui-tab-panel API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
value value true string

分頁面板的值
### Slots
名稱 說明
預設

分頁面板內容
## mdui-tab API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
value value true string

分頁的值
icon icon true string

Material Icons 圖示名。也可以透過 slot="icon" 設定
inline inline true boolean false

是否把圖示和文字水平排列
autofocus autofocus true boolean false

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

元素在使用 Tab 鍵切換焦點時的順序
### 方法
名稱 說明
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
### Slots
名稱 說明
預設

分頁的文字內容
icon

分頁中的圖示
badge

徽章
custom

自訂整個分頁中的內容
### CSS Parts
名稱 說明
container

分頁容器
icon

分頁中的圖示
label

分頁的文字
## mdui-tabs API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'primary' | 'secondary' 'primary'

分頁形狀。可選值包括：

  • primary：適用於位於 <mdui-top-app-bar> 下方，用於切換應用的主頁面的場景
  • secondary：適用於位於頁面中，用於切換一組相關內容的場景
value value true string

目前啟用的 <mdui-tab> 的值
placement placement true 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end' | 'right-start' | 'right' | 'right-end' 'top-start'

分頁位置。預設為 top-start。可選值包括：

  • top-start：位於上方，左對齊
  • top：位於上方，置中對齊
  • top-end：位於上方，右對齊
  • bottom-start：位於下方，左對齊
  • bottom：位於下方，置中對齊
  • bottom-end：位於下方，右對齊
  • left-start：位於左側，頂部對齊
  • left：位於左側，置中對齊
  • left-end：位於左側，底部對齊
  • right-start：位於右側，頂部對齊
  • right：位於右側，置中對齊
  • right-end：位於右側，底部對齊
full-width fullWidth true boolean false

是否填滿父元素寬度
### 事件
名稱 說明
change

選取的值變化時觸發
### Slots
名稱 說明
預設

<mdui-tab> 元素
panel

<mdui-tab-panel> 元素
### CSS Parts
名稱 說明
container

<mdui-tab> 元素的容器
indicator

啟用狀態指示器
# 文字欄位元件 TextField 文字欄位元件讓使用者能在頁面中輸入文字，通常用於表單和對話框。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/text-field.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { TextField } from 'mdui/components/text-field.js'; ``` 使用範例： ```html ``` ## 範例 {#examples} ### 樣式 {#example-variant} 透過 `variant` 屬性設定文字欄位的樣式。 ```html

``` ### 輔助文字 {#example-helper-text} 透過 `label` 屬性設定文字欄位上方的標籤文字。 ```html ``` 透過 `placeholder` 屬性設定無值時的佔位文字。 ```html ``` 透過 `helper` 屬性設定文字欄位底部的輔助文字。你也可以使用 `helper` slot 來設定輔助文字。加上 `helper-on-focus` 屬性則僅在輸入框聚焦時顯示輔助文字。 ```html Supporting text ``` ### 可清空 {#example-clearable} 加上 `clearable` 屬性後，當文字欄位有值時，會在右側加上清空按鈕。 ```html ``` ### 文字靠右對齊 {#example-end-aligned} 加上 `end-aligned` 屬性可以使文字靠右對齊。 ```html ``` ### 前後文字及圖示 {#example-prefix-suffix} 透過設定 `icon` 和 `end-icon` 屬性，即可在文字欄位的左側和右側加入 Material Icons 圖示。也可以透過 `icon` 和 `end-icon` slot 在文字欄位的左側和右側加入元素。 ```html

``` 透過設定 `prefix` 和 `suffix` 屬性，可以在文字欄位的左側和右側加入文字。也可以透過 `prefix` 和 `suffix` slot 在文字欄位的左側和右側加入文字元素。這些文字只有在文字欄位聚焦或有值時才會顯示。 ```html

$ /100 ``` ### 唯讀模式 {#example-readonly} 加上 `readonly` 屬性，可以將文字欄位設定為唯讀模式。 ```html ``` ### 停用狀態 {#example-disabled} 加上 `disabled` 屬性即可停用文字欄位。 ```html ``` ### 多行文字欄位 {#example-rows} 透過 `rows` 屬性，可以設定多行文字欄位的行數。 ```html ``` 也可以加上 `autosize` 屬性，使文字欄位能根據輸入內容的長度自動調整高度。透過 `min-rows` 和 `max-rows` 屬性，可以指定自動調整高度時的最小行數和最大行數。 ```html

``` ### 字數統計 {#example-counter} 當透過 `maxlength` 屬性設定了最大字數時，可以加上 `counter` 屬性在文字欄位下方顯示字數統計。 ```html ``` ### 密碼欄位 {#example-password} 當 `type="password"` 時，加上 `toggle-password` 屬性可以在文字欄位右側加入切換密碼可見性的按鈕。 ```html ``` ## mdui-text-field API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'filled' | 'outlined' 'filled'

文字欄位的形狀。預設為 filled。可選值包括：

  • filled：帶背景色的文字欄位，視覺效果較強
  • outlined：帶邊框的文字欄位，視覺效果較弱
type type true 'text' | 'number' | 'password' | 'url' | 'email' | 'search' | 'tel' | 'hidden' | 'date' | 'datetime-local' | 'month' | 'time' | 'week' 'text'

文字欄位輸入類型。預設為 text。可選值包括：

  • text：預設值。文字欄位
  • number：只能輸入數字。支援虛擬鍵盤的裝置上會顯示數字鍵盤
  • password：用於輸入密碼，其值會被遮蓋
  • url：用於輸入 URL，會驗證 URL 格式。在支援虛擬鍵盤的裝置上有相應的鍵盤
  • email：用於輸入郵件地址，會驗證郵件格式。在支援虛擬鍵盤的裝置上有相應的鍵盤
  • search：用於搜尋框。支援虛擬鍵盤的裝置上的 Enter 圖示會變成搜尋圖示
  • tel：用於輸入電話號碼。支援虛擬鍵盤的裝置上會顯示電話數字鍵盤
  • hidden：隱藏該控制項，但其值仍會送出到伺服器
  • date：輸入日期的控制項（年、月、日，不包括時間）。在支援的瀏覽器啟用時開啟日期選擇器或年月日的數字滾輪
  • datetime-local：輸入日期和時間的控制項，不包括時區。在支援的瀏覽器啟用時開啟日期選擇器或年月日的數字滾輪
  • month：輸入年和月的控制項，沒有時區
  • time：用於輸入時間的控制項，不包括時區
  • week：用於輸入以年和週數組成的日期，不帶時區
name name true string ''

文字欄位名稱，將與表單資料一起送出
value value false string ''

文字欄位的值，將與表單資料一起送出
undefined defaultValue false string ''

預設值。在重設表單時，將重設為該預設值。該屬性只能透過 JavaScript 屬性設定
label label true string

標籤文字
placeholder placeholder true string

佔位符文字
helper helper true string

文字欄位底部的說明文字。也可以透過 slot="helper" 設定
helper-on-focus helperOnFocus true boolean false

是否僅在取得焦點時，顯示底部的說明文字
clearable clearable true boolean false

是否可清空文字欄位內容
clear-icon clearIcon true string

可清空文字欄位時，顯示在文字欄位右側的清空按鈕的 Material Icons 圖示名。也可以透過 slot="clear-icon" 設定
end-aligned endAligned true boolean false

是否將文字右對齊
prefix prefix true string

文字欄位的前綴文字。只在文字欄位聚焦或有值時顯示。也可以透過 slot="prefix" 設定
suffix suffix true string

文字欄位的後綴文字。只在文字欄位聚焦或有值時顯示。也可以透過 slot="suffix" 設定
icon icon true string

文字欄位的前綴圖示的 Material Icons 圖示名。也可以透過 slot="icon" 設定
end-icon endIcon true string

文字欄位的後綴圖示的 Material Icons 圖示名。也可以透過 slot="end-icon" 設定
error-icon errorIcon true string

表單欄位驗證失敗時，顯示在文字欄位右側的 Material Icons 圖示名。也可以透過 slot="error-icon" 設定
form form true string

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

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

是否為唯讀模式
disabled disabled true boolean false

是否停用輸入框
required required true boolean false

送出表單時，是否必須填寫該欄位
rows rows true number

文字欄位的固定顯示行數
autosize autosize true boolean false

是否根據輸入內容自動調整文字欄位高度
min-rows minRows true number

autosize 為 true 時，文字欄位的最小行數
max-rows maxRows true number

autosize 為 true 時，文字欄位的最大行數
minlength minlength true number

允許輸入的最小字元數
maxlength maxlength true number

允許輸入的最大字元數
counter counter true boolean false

是否顯示字數統計，只在 maxlength 被指定時有效
min min true number

當 type 為 number 時，允許輸入的最小數值
max max true number

當 type 為 number 時，允許輸入的最大數值
step step true number

type 為 number 時，數值增減的步長
pattern pattern true string

用於表單驗證的正規表示式
toggle-password togglePassword true boolean false

type 為 password 時，設定此屬性會新增一個切換按鈕，用於在明文和密文之間切換
show-password-icon showPasswordIcon true string

密碼切換按鈕的 Material Icons 圖示，當密碼為明文時顯示。也可以透過 slot="show-password-icon" 設定
hide-password-icon hidePasswordIcon true string

密碼切換按鈕的 Material Icons 圖示，當密碼為密文時顯示。也可以透過 slot="hide-password-icon" 設定
autocapitalize autocapitalize true 'none' | 'sentences' | 'words' | 'characters'

iOS 的非標準屬性，用於控制文字首字母是否自動大寫。在 iOS5 及以後的版本上有效。可選值包括：

  • none：停用首字母大寫
  • sentences：句子首字母大寫
  • words：單字首字母大寫
  • characters：所有字母大寫
autocorrect autocorrect true string

input 元素的 autocorrect 屬性
autocomplete autocomplete true string

input 元素的 autocomplete 屬性
enterkeyhint enterkeyhint true 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'

input 元素的 enterkeyhint 屬性，用於客製化虛擬鍵盤上的 Enter 鍵的顯示文字或圖示。具體顯示效果取決於使用者使用的裝置和語言。可選值包括：

  • enter：插入新行
  • done：完成輸入，關閉虛擬鍵盤
  • go：前往輸入文字的目標
  • next：移動到下一個輸入項
  • previous：移動到上一個輸入項
  • search：前往搜尋結果
  • send：傳送文字資訊
spellcheck spellcheck true boolean false

是否啟用拼字檢查
inputmode inputmode true 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'

input 元素的 inputmode 屬性，用於客製化虛擬鍵盤的類型。可選值包括：

  • none：無虛擬鍵盤。在需要實作自己的鍵盤輸入控制項時很有用
  • text：標準文字輸入鍵盤
  • decimal：小數輸入鍵盤，除了數字之外可能會有小數點 . 或者千分符逗號 ,
  • numeric：顯示 0-9 的數字鍵盤
  • tel：手機數字鍵盤，包含 0-9 數字、星號 * 或者井號 # 鍵
  • search：為搜尋輸入最佳化的虛擬鍵盤，送出按鈕通常會顯示 search 或者「搜尋」
  • email：為郵件地址輸入最佳化的虛擬鍵盤，通常會有 @ . 等鍵
  • url：為 URL 輸入最佳化的虛擬鍵盤，通常會有 . / # 等鍵
undefined validity false ValidityState

表單驗證狀態物件，具體參見 ValidityState
undefined validationMessage false string

如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串
undefined valueAsNumber false number

取得目前值，並轉換為 number 類型；或設定一個 number 類型的值。 如果值無法被轉換為 number 類型，則會回傳 NaN。
autofocus autofocus true boolean false

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

元素在使用 Tab 鍵切換焦點時的順序
### 方法
名稱 說明
select(): void

選取文字欄位中的文字
setSelectionRange(start: number, end: number, direction: 'forward' | 'backward' | 'none'): void

選取文字欄位中特定範圍的內容
setRangeText(replacement: string, start: number, end: number, selectMode: 'select' | 'start' | 'end' | 'preserve'): void

將文字欄位中特定範圍的文字替換為新的文字
checkValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true
reportValidity(): boolean

檢查表單欄位是否通過驗證。如果未通過，回傳 false 並觸發 invalid 事件；如果通過，回傳 true。

如果驗證未通過，還會在元件上顯示驗證失敗的提示。
setCustomValidity(message: string): void

設定自訂的錯誤提示文字。只要這個文字不為空，就表示欄位未通過驗證
click(): void

模擬滑鼠點擊元素
focus(options?: FocusOptions): void

將焦點設定到目前元素。

可以傳入一個物件作為引數，該物件的屬性包括：

  • preventScroll：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 true。
blur(): void

移除目前元素的焦點
### 事件
名稱 說明
focus

取得焦點時觸發
blur

失去焦點時觸發
change

在文字欄位的值變更，且失去焦點時觸發
input

在文字欄位的值變更時觸發
invalid

表單欄位驗證不通過時觸發
clear

在點擊由 clearable 屬性產生的清空按鈕時觸發。可以透過呼叫 event.preventDefault() 阻止清空文字欄位
### Slots
名稱 說明
icon

左側圖示
end-icon

右側圖示
error-icon

驗證失敗狀態的右側圖示
prefix

左側文字
suffix

右側文字
clear-button

清空按鈕
clear-icon

清空按鈕中的圖示
toggle-password-button

密碼顯示狀態切換按鈕
show-password-icon

顯示密碼狀態下，密碼顯示狀態切換按鈕中的圖示
hide-password-icon

隱藏密碼狀態下，密碼顯示狀態切換按鈕中的圖示
helper

底部的說明文字
### CSS Parts
名稱 說明
container

文字欄位容器
icon

左側圖示
end-icon

右側圖示
error-icon

驗證失敗狀態的右側圖示
prefix

左側文字
suffix

右側文字
label

上方的標籤文字
input

內部的 <input> 或 <textarea> 元素
clear-button

清空按鈕
clear-icon

清空按鈕中的圖示
toggle-password-button

密碼顯示狀態切換按鈕
show-password-icon

顯示密碼狀態下，密碼顯示狀態切換按鈕中的圖示
hide-password-icon

隱藏密碼狀態下，密碼顯示狀態切換按鈕中的圖示
supporting

底部輔助資訊容器，包括 helper、error、counter
helper

底部的說明文字
error

底部的錯誤描述文字
counter

底部右側的字數統計
# 工具提示元件 Tooltip 工具提示用來為特定元素提供補充文字提示或上下文資訊，方便使用者更好地理解該元素的功能或用途。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/tooltip.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { Tooltip } from 'mdui/components/tooltip.js'; ``` 使用範例： ```html button ``` ## 範例 {#examples} ### 純文字工具提示 {#example-plain} 預設為純文字工具提示。可以透過 `content` 屬性設定工具提示的內容。 ```html button ``` 也可以透過 `content` slot 設定工具提示的內容。 ```html button
title
content
 ``` ### 進階工具提示 {#example-rich} 設定 `variant` 屬性為 `rich` 可以建立進階工具提示。可以透過 `headline` 屬性設定工具提示的標題，`content` 屬性設定工具提示的內容。 ```html button ``` 也可以透過 `headline`、`content` slot 設定工具提示的標題和內容。透過 `action` slot 設定工具提示的操作按鈕。 ```html button
進階工具提示
進階工具提示可凸顯需要使用者注意的特定元素，並支援多行說明文字。
Action ``` ### 位置 {#example-placement} 透過 `placement` 屬性可以設定工具提示的位置。 ```html
``` ### 觸發方式 {#example-trigger} 透過 `trigger` 屬性，可以設定工具提示的觸發方式。 ```html button ``` ### 開啟/關閉延遲 {#example-delay} 當觸發方式為 `hover` 時，可以透過 `open-delay` 和 `close-delay` 屬性分別設定開啟與關閉工具提示的延遲，單位為毫秒。 ```html button ``` ### 停用狀態 {#example-disabled} 加上 `disabled` 屬性即可停用工具提示。 ```html button ``` ## mdui-tooltip API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'plain' | 'rich' 'plain'

tooltip 的形狀。預設為 plain。可選值包括：

  • plain：純文字，適用於簡單的單行文字
  • rich：富文字，可以包含標題、正文和操作按鈕
placement placement true 'auto' | 'top-left' | 'top-start' | 'top' | 'top-end' | 'top-right' | 'bottom-left' | 'bottom-start' | 'bottom' | 'bottom-end' | 'bottom-right' | 'left-start' | 'left' | 'left-end' | 'right-start' | 'right' | 'right-end' 'auto'

tooltip 的位置。預設為 auto。可選值包括：

  • auto：自動判斷位置。variant="plain" 時，優先使用 top；variant="rich" 時，優先使用 bottom-right
  • top-left：位於左上方
  • top-start：位於上方，左對齊
  • top：位於上方，置中對齊
  • top-end：位於上方，右對齊
  • top-right：位於右上方
  • bottom-left：位於左下方
  • bottom-start：位於下方，左對齊
  • bottom：位於下方，置中對齊
  • bottom-end：位於下方，右對齊
  • bottom-right：位於右下方
  • left-start：位於左側，頂部對齊
  • left：位於左側，置中對齊
  • left-end：位於左側，底部對齊
  • right-start：位於右側，頂部對齊
  • right：位於右側，置中對齊
  • right-end：位於右側，底部對齊
open-delay openDelay true number 150

滑鼠懸停觸發顯示的延遲，單位為毫秒
close-delay closeDelay true number 150

滑鼠懸停觸發隱藏的延遲，單位為毫秒
headline headline true string

tooltip 的標題。僅 variant="rich" 時可使用。也可以透過 slot="headline" 設定
content content true string

tooltip 的內容。也可以透過 slot="content" 設定
trigger trigger true 'click' | 'hover' | 'focus' | 'manual' | string 'hover focus'

觸發方式，支援多個值，用空格分隔。可選值包括：

  • click：點擊時觸發
  • hover：滑鼠懸停時觸發
  • focus：聚焦時觸發
  • manual：只能透過程式方式開啟和關閉 tooltip，不能再指定其他觸發方式
disabled disabled true boolean false

是否停用 tooltip
open open true boolean false

是否顯示 tooltip
### 事件
名稱 說明
open

tooltip 開始顯示時觸發。可透過呼叫 event.preventDefault() 阻止 tooltip 開啟
opened

tooltip 顯示動畫完成時，事件被觸發
close

tooltip 開始隱藏時觸發。可透過呼叫 event.preventDefault() 阻止 tooltip 關閉
closed

tooltip 隱藏動畫完成時，事件被觸發
### Slots
名稱 說明
預設

tooltip 觸發的目標元素，只有 default slot 中的第一個元素會作為目標元素
headline

tooltip 的標題，只有當 variant="rich" 時，此 slot 才有效
content

tooltip 的內容，可以包含 HTML。若只包含純文字，可以使用 content 屬性代替
action

tooltip 底部的按鈕，只有當 variant="rich" 時，此 slot 才有效
### CSS Parts
名稱 說明
popup

tooltip 的容器
headline

標題
content

正文
action

操作按鈕
### CSS 自訂屬性
名稱 說明
--shape-corner-plain

當 variant="plain" 時，元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
--shape-corner-rich

當 variant="rich" 時，元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
--z-index

元件的 CSS z-index 值
# 頂部應用程式列元件 TopAppBar 頂部應用程式列用來在頁面頂部顯示關鍵資訊與相關操作，提供清楚的導覽和方便的功能存取。 ## 使用方法 {#usage} 按需引入元件： ```js import 'mdui/components/top-app-bar.js'; import 'mdui/components/top-app-bar-title.js'; ``` 按需引入元件的 TypeScript 型別： ```ts import type { TopAppBar } from 'mdui/components/top-app-bar.js'; import type { TopAppBarTitle } from 'mdui/components/top-app-bar-title.js'; ``` 使用範例：（範例中的 `style="position: relative"` 僅供示範使用，實際使用時請移除該樣式。） ```html Title
``` **注意事項：** 該元件預設使用 `position: fixed` 定位，並會自動在 `body` 上加入 `padding-top` 樣式，以防止頁面內容被該元件遮擋。 但在以下兩種情況下，會預設使用 `position: absolute` 定位： 1. 當指定了 `scroll-target` 屬性時。此時會在 `scroll-target` 的元素上加入 `padding-top` 樣式。 2. 當位於 [``](/zh-tw/docs/2/components/layout) 元件中時。此時不會加入 `padding-top` 樣式。 ## 範例 {#examples} ### 位於指定容器內 {#example-scroll-target} 預設情況下，頂部應用程式列會固定在頁面頂部。 如果你希望將頂部應用程式列放在指定的容器內，可以在 `` 元件上指定 `scroll-target` 屬性，其值為可捲動內容容器的 CSS 選擇器或 DOM 元素。此時，頂部應用程式列會以父元素作為定位基準（你需要自行替父元素加上樣式 `position: relative; overflow: hidden`）。 ```html
Title
``` ### 樣式 {#example-variant} 可以透過在 `` 元件上使用 `variant` 屬性來設定頂部應用程式列的樣式。 ```html
Title
center-aligned small medium large
``` ### 頁面捲動時的行為 {#example-scroll-behavior} 透過在 `` 元件上設定 `scroll-behavior` 屬性，可以定義頁面捲動時頂部應用程式列的行為。可以同時設定多個行為，用空格分隔即可。 捲動行為包括： - `hide`：頁面向下捲動時隱藏頂部應用程式列，向上捲動時顯示頂部應用程式列。 - `shrink`：僅在 `variant` 屬性為 `medium` 或 `large` 時有效。頁面向下捲動時展開頂部應用程式列，向上捲動時收合頂部應用程式列。 - `elevate`：頁面向下捲動時，在頂部應用程式列上加入陰影；頁面捲回頂部時，取消陰影。 使用 `scroll-threshold` 屬性，可以設定捲動多少像素後開始觸發頂部應用程式列的捲動行為。（注意，為了確保即時反應，在使用了 `elevate` 捲動行為時，請不要再設定 `scroll-threshold` 屬性。） **範例：捲動時隱藏** ```html
Title
``` **範例：捲動時加入陰影** ```html
Title
``` **範例：捲動時收合** ```html
Title
``` **範例：捲動時收合及加入陰影** ```html
Title
``` ### 展開狀態的文字 {#label-large} 對於 `variant` 屬性為 `medium` 或 `large`，且 `scroll-behavior` 屬性為 `shrink` 的頂部應用程式列，你可以在 `` 元件中加入 `label-large` slot，以設定展開狀態下顯示的文字。 ```html
這是收合狀態的標題 這是展開狀態的標題
``` ## mdui-top-app-bar-title API ### Slots
名稱 說明
預設

頂部應用程式列的標題文字
label-large

展開狀態下的標題文字
### CSS Parts
名稱 說明
label

標題文字
label-large

展開狀態下的標題文字
## mdui-top-app-bar API ### 屬性
HTML 屬性 JavaScript 屬性 Reflect 型別 預設值 說明
variant variant true 'center-aligned' | 'small' | 'medium' | 'large' 'small'

頂部應用程式列的形狀。預設為 small。可選值包括：

  • center-aligned：小型應用程式列，標題置中
  • small：小型應用程式列
  • medium：中型應用程式列
  • large：大型應用程式列
hide hide true boolean false

是否隱藏
shrink shrink true boolean false

是否縮小為 variant="small" 的樣式，僅在 variant="medium" 或 variant="large" 時生效
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

捲動行為。可同時使用多個值，用空格分隔。可選值包括：

  • hide：捲動時隱藏
  • shrink：在中型、大型應用程式列中可使用，捲動時縮小成小型應用程式列的樣式
  • elevate：捲動時新增陰影
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

需要監聽捲動事件的目標元素。值可以是 CSS 選擇器、DOM 元素、或 JQ 物件。預設監聽 window 的捲動事件
scroll-threshold scrollThreshold true number

觸發捲動行為所需的捲動距離，單位為 px
order order true number

該元件在 <mdui-layout> 中的版面順序，按從小到大排序。預設為 0
### 事件
名稱 說明
show

開始顯示時觸發。可透過呼叫 event.preventDefault() 阻止顯示
shown

顯示動畫完成時，事件被觸發
hide

開始隱藏時觸發。可透過呼叫 event.preventDefault() 阻止隱藏
hidden

隱藏動畫完成時，事件被觸發
### Slots
名稱 說明
預設

頂部應用程式列內部的元素
### CSS 自訂屬性
名稱 說明
--shape-corner

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

元件的 CSS z-index 值
# jq 工具庫 mdui 內建了一個輕量級的 JavaScript 工具庫，它提供了類似於 jQuery 的 API 和鏈式呼叫方式，但其體積只有 jQuery 的六分之一。 你可以按需引入該工具函式： ```js import { $ } from 'mdui/jq.js'; ``` ## 核心 {#api-core} ### `$()` {#dollar} 該函式有多種用法： 傳入 CSS 選擇器作為參數，回傳包含匹配元素的 JQ 物件。 ```js $('.box'); ``` 傳入 DOM 元素、任意陣列、NodeList 或 JQ 物件，回傳包含指定元素的 JQ 物件。 ```js $(document); ``` 傳入 HTML 字串，回傳包含根據 HTML 建立的 DOM 的 JQ 物件。 ```js $(`
`); ``` 傳入一個函式，當 DOM 載入完畢後會呼叫該函式。 ```js $(function () { console.log('DOM Loaded'); }); ``` ## 擴充 {#api-extend} ### `$.extend()` {#d-extend} 如果只傳入一個物件，該物件中的屬性將合併到 `$` 物件中，相當於在 `$` 的命名空間下新增功能。 ```js $.extend({ customFunc: function () {}, }); // 然後就可以這樣呼叫自訂方法了 $.customFunc(); ``` 如果傳入了兩個或更多個物件，所有物件的屬性都加入到第一個物件，並回傳合併後的物件。不過值為 `undefined` 的屬性不會合併。 ```js const object = $.extend({ key1: val1 }, { key2: val2 }, { key3: val3 }); // 此時第一個物件和回傳值都是 { key1: val1, key2: val2, key3: val3 } ``` ### `$.fn.extend()` {#fn-extend} 在 `$` 的原型鏈上擴充方法。 ```js $.fn.extend({ customFunc: function () {}, }); // 然後就可以這樣使用擴充的方法了 $(document).customFunc(); ``` ## URL {#api-url} ### `$.param()` {#d-param} 將陣列或物件序列化為 URL 查詢字串。 ```js $.param({ width: 1680, height: 1050 }); // width=1680&height=1050 $.param({ foo: { one: 1, two: 2 } }); // foo[one]=1&foo[two]=2 $.param({ ids: [1, 2, 3] }); // ids[]=1&ids[]=2&ids[]=3 ``` 如果傳入的參數是陣列，那麼該陣列的格式必須與 [`.serializeArray()`](#serializeArray) 回傳的格式一致。 ```js $.param([ { name: 'name', value: 'mdui' }, { name: 'password', value: '123456' }, ]); // name=mdui&password=123456 ``` ## 陣列和物件操作 {#api-array} ### `$.each()` {#d-each} 走訪陣列或物件。它回傳的是第一個參數，即被走訪的陣列或物件。 回呼函式的第一個參數是陣列的索引或物件的鍵，第二個參數是陣列或物件對應位置的值。 在回呼函式中，`this` 指向陣列或物件對應位置的值。如果回呼函式回傳 `false`，則停止走訪。 ```js // 走訪陣列 $.each(['a', 'b', 'c'], function (index, value) { console.log(index + ':' + value); }); // 結果： // 0:a // 1:b // 2:c ``` ```js // 走訪物件 $.each({ name: 'mdui', lang: 'zh' }, function (key, value) { console.log(key + ':' + value); }); // 結果 // name:mdui // lang:zh ``` ### `$.merge()` {#d-merge} 將第二個陣列的元素追加到第一個陣列中，並回傳合併後的陣列。 ```js const first = ['a', 'b', 'c']; const second = ['c', 'd', 'e']; const result = $.merge(first, second); console.log(first); // ['a', 'b', 'c', 'c', 'd', 'e'] console.log(result); // ['a', 'b', 'c', 'c', 'd', 'e'] ``` ### `$.unique()` {#d-unique} 移除陣列中的重複元素。 ```js const result = $.unique([1, 2, 12, 3, 2, 1, 2, 1, 1, 1, 1]); console.log(result); // [1, 2, 12, 3] ``` ### `$.map()` {#d-map} 走訪陣列或物件，回傳一個由回呼函式的回傳值組成的新陣列。 回呼函式的第一個參數是陣列或物件對應位置的值，第二個參數是陣列的索引或物件的鍵。 回呼函式可以回傳任何值。如果回傳的是陣列，那麼這個陣列會被展開。如果回傳的是 `null` 或 `undefined`，那麼這個值會被忽略。在回呼函式內部，`this` 指向 `window` 物件。 ```js // 走訪陣列 const result = $.map(['a', 'b', 'c'], function (value, index) { return index + value; }); console.log(result); // ['0a', '1b', '2c'] ``` ```js // 當回呼函式回傳陣列時，陣列會被展開 const result = $.map([1, 2, 3], function (value, index) { return [value, value + 1]; }); console.log(result); // [1, 2, 2, 3, 3, 4] ``` ```js // 走訪物件 const result = $.map( { name: 'mdui', password: '123456' }, function (value, key) { return key + ':' + value; }, ); console.log(result); // ['name:mdui', 'password:123456'] ``` ### `$.contains()` {#d-contains} 判斷一個節點是否包含另一個節點。如果父節點包含子節點，回傳 `true`；否則，回傳 `false`。 ```js $.contains(document, document.body); // true $.contains(document.body, document); // false ``` ## 資料型別判斷 {#api-type} ### `.is()` {#is} 判斷集合中是否至少有一個元素與參數匹配。如果匹配，回傳 `true`；否則，回傳 `false`。 參數可以是 CSS 選擇器、DOM 元素、DOM 元素陣列、JQ 物件，或者回呼函式。 如果參數是回呼函式，函式的第一個參數是索引，第二個參數是目前元素。在函式內部，`this` 指向目前元素。如果函式回傳 `true`，表示目前元素與參數匹配；如果回傳 `false`，表示目前元素與參數不匹配。 ```js $('.box').is('.box'); // true $('.box').is('.boxss'); // false $('.box').is($('.box')[0]); // true ``` ```js // 透過回呼函式的回傳值做判斷 $(document).is(function (index, element) { return element === document; }); // true ``` ## 物件存取 {#api-object} ### `.length` {#length} 回傳目前集合中元素的數量。 ```js $('body').length; // 1 ``` ### `.each()` {#each} 走訪目前集合，為集合中的每個元素執行一個函式。如果函式回傳 `false`，則停止走訪。 函式的第一個參數是元素的索引位置，第二個參數是目前元素。在函式內部，`this` 指向目前元素。 ```js $('img').each(function (index, element) { this.src = 'test' + index + '.jpg'; }); ``` ### `.map()` {#map} 走訪目前集合，為集合中的每個元素執行一個函式，回傳由函式回傳值組成的新集合。 函式可以回傳單一資料或資料陣列。如果回傳陣列，那麼會將陣列中的元素依序加入新集合中。如果函式回傳 `null` 或 `undefined`，那麼這個值不會被加入新集合中。 函式的第一個參數是元素的索引位置，第二個參數是目前元素。在函式內部，`this` 指向目前元素。 ```js const result = $('input.checked').map(function (i, element) { return element.value; }); // result 是一個由匹配元素的值組成的 JQ 物件 ``` ### `.eq()` {#eq} 回傳一個新集合，該集合只包含指定索引位置的元素。 ```js $('div').eq(0); // 回傳僅包含第一個元素的集合 $('div').eq(-1); // 回傳僅包含最後一個元素的集合 $('div').eq(-2); // 回傳僅包含倒數第二個元素的集合 ``` ### `.first()` {#first} 回傳一個新集合，該集合只包含目前集合中的第一個元素。 ```js $('div').first(); // 回傳僅包含第一個 div 的集合 ``` ### `.last()` {#last} 回傳一個新集合，該集合只包含目前集合中的最後一個元素。 ```js $('div').last(); // 回傳僅包含最後一個 div 的集合 ``` ### `.get()` {#get} 回傳指定索引位置的元素。未傳入參數時，會回傳由集合中所有元素組成的陣列。 ```js $('div').get(); // 回傳所有 div 元素組成的陣列 $('div').get(0); // 回傳第一個 div 元素 $('div').get(-1); // 回傳最後一個 div 元素 ``` ### `.index()` {#index} 未傳入參數時，會回傳目前集合中第一個元素相對於其同輩元素的索引值。 傳入一個 CSS 選擇器時，會回傳目前集合中第一個元素相對於 CSS 選擇器匹配元素的索引值。 傳入一個 DOM 元素時，會回傳該元素在目前集合中的索引值。 傳入一個 JQ 物件時，會回傳物件中第一個元素在目前集合中的索引值。 ```html
``` ```js $('#child3').index(); // 2 $('#child3').index('#child div'); // 2 $('#child div').index($('#child3').get(0)); // 2 ``` ### `.slice()` {#slice} 回傳目前集合的子集。 你可以透過傳入兩個參數來指定子集的起始和結束位置（不包含結束位置的元素）。如果沒有傳入第二個參數，它將回傳從起始位置到集合末尾的所有元素。 ```js // 回傳集合中第三個（包含第三個）之後的所有元素 $('div').slice(3); // 回傳集合中第三個到第五個（包含第三個，不包含第五個）之間的元素 $('div').slice(3, 5); ``` ### `.filter()` {#filter} 從目前集合中篩選出與指定表達式匹配的元素。參數可以是 CSS 選擇器、DOM 元素、DOM 元素陣列或回呼函式。 如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是目前元素。在函式內部，`this` 指向目前元素。如果函式回傳 `true`，目前元素會被保留；如果回傳 `false`，目前元素會被移除。 ```js // 篩選出所有含 .box 的 div 元素 $('div').filter('.box'); // 篩選出所有已選取的選項 $('#select option').filter(function (index, element) { return element.selected; }); ``` ### `.not()` {#not} 從目前集合中篩選出與指定表達式不匹配的元素。 參數可以是 CSS 選擇器、DOM 元素、DOM 元素陣列、JQ 物件，或回傳 `boolean` 值的回呼函式。 如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是目前元素。在函式內部，`this` 指向目前元素。如果函式回傳 `true`，目前元素會被移除；如果回傳 `false`，目前元素會被保留。 ```js // 篩選出所有不含 .box 類別的 div 元素 $('div').not('.box'); // 篩選出所有未選取的選項 $('#select option').not(function (index, element) { return element.selected; }); ``` ## CSS 類別 {#api-css} ### `.hasClass()` {#hasClass} 判斷集合中的第一個元素是否含有指定的 CSS 類別。 ```js // 判斷第一個 div 元素是否含有 .item $('div').hasClass('item'); ``` ### `.addClass()` {#addClass} 為集合中的每個元素新增 CSS 類別，多個類別名稱之間可以用空格分隔。 參數可以是字串，也可以是一個回傳 CSS 類別名稱的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的 CSS 類別名稱。在函式內部，`this` 指向目前元素。 ```js // 為所有 div 元素新增 .item $('div').addClass('item'); // 為所有 div 元素新增 .item1 和 .item2 $('div').addClass('item1 item2'); // 為所有 div 元素新增由回呼函式回傳的 CSS 類別 $('div').addClass(function (index, currentClassName) { return currentClassName + '-' + index; }); ``` ### `.removeClass()` {#removeClass} 移除集合中每個元素上的指定 CSS 類別，多個類別名稱之間可以用空格分隔。 參數可以是字串，也可以是一個回傳 CSS 類別名稱的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的 CSS 類別名稱。在函式內部，`this` 指向目前元素。 如果沒有傳入參數，該方法將直接移除元素上的 `class` 屬性。 ```js // 移除所有 div 元素上的 .item $('div').removeClass('item'); // 移除所有 div 元素上的 .item1 和 .item2 $('div').removeClass('item1 item2'); // 移除所有 div 元素上的由回呼函式回傳的 CSS 類別 $('div').removeClass(function (index, currentClassName) { return 'item'; }); ``` ### `.toggleClass()` {#toggleClass} 如果元素上有指定的 CSS 類別，則刪除它；如果沒有，則新增它。多個類別名稱之間可以用空格分隔。 參數可以是字串，也可以是一個回傳 CSS 類別名稱的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的 CSS 類別名稱。在函式內部，`this` 指向目前元素。 ```js // 切換所有 div 元素上的 .item 類別 $('div').toggleClass('item'); // 切換所有 div 元素上的 .item1 和 .item2 類別 $('div').toggleClass('item1 item2'); // 切換所有 div 元素上的由回呼函式回傳的 CSS 類別 $('div').toggleClass(function (index, currentClassName) { return 'item'; }); ``` ## 節點屬性 {#api-attr} ### `.prop()` {#prop} 取得集合中第一個元素的 JavaScript 屬性值。 ```js // 取得第一個元素 checked 屬性值 $('input').prop('checked'); ``` 傳入兩個參數時，會設定集合中所有元素的指定 JavaScript 屬性值。 屬性值可以是任意類型的值，也可以是一個回傳屬性值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的屬性值。在函式內部，`this` 指向目前元素。 如果屬性值或回呼函式的回傳值為 `undefined`，該方法將不會修改元素的原有屬性。 ```js // 設定所有選取元素的 checked 屬性值為 true $('input').prop('checked', true); // 透過回呼函式的回傳值設定屬性值 $('input').prop('checked', function (index, oldPropValue) { return true; }); ``` 也可以透過傳入一個物件來同時設定多個屬性。 ```js // 同時設定元素的多個屬性值 $('input').prop({ checked: false, disabled: function (index, oldPropValue) { return true; }, }); ``` ### `.removeProp()` {#removeProp} 刪除集合中所有元素上指定的 JavaScript 屬性值。 ```js $('input').removeProp('disabled'); ``` ### `.attr()` {#attr} 取得集合中第一個元素的 HTML 屬性值。 ```js // 取得第一個元素的屬性值 $('div').attr('username'); ``` 傳入兩個參數時，會設定集合中所有元素的指定 HTML 屬性值。 屬性值可以是字串或數值，也可以是一個回傳屬性值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的屬性值。在函式內部，`this` 指向目前元素。 如果屬性值或回呼函式的回傳值為 `null`，該方法將刪除指定屬性；如果為 `undefined`，則不會修改元素的原有屬性。 ```js // 設定所有選取元素的屬性值 $('div').attr('username', 'mdui'); // 透過回呼函式的回傳值設定屬性值 $('div').attr('username', function (index, oldAttrValue) { return 'mdui'; }); ``` 也可以透過傳入一個物件來同時設定多個屬性。 ```js // 同時設定元素的多個屬性值 $('div').attr({ username: 'mdui', lastname: function (index, oldAttrValue) { return 'test'; }, }); ``` ### `.removeAttr()` {#removeAttr} 刪除集合中所有元素上指定的 HTML 屬性，多個屬性名稱之間可以用空格分隔。 ```js // 刪除集合中所有元素上的一個屬性 $('div').removeAttr('username'); // 刪除集合中所有元素上的多個屬性 $('div').removeAttr('username lastname'); ``` ### `.val()` {#val} 回傳集合中第一個元素的值。 如果元素是 ``、``、`