快速入門

mdui 的元件都是標準的 Web Components 元件，你可以像使用 <div> 標籤一樣使用 mdui 元件。每個元件的文件中都詳細描述了其完整的 API，包括屬性、方法、事件、Slot、CSS Part、CSS 自訂屬性等。

本章將介紹 Web Components 的使用方法。

屬性

屬性分為 HTML 屬性和 JavaScript 屬性，它們通常是一一對應的，並且會保持同步。也就是說，當你更新 HTML 屬性值時，JavaScript 屬性值也會隨之更新；反之亦然。

HTML 屬性可以直接在元件的 HTML 字串中設定，並透過 getAttribute 和 setAttribute 方法進行讀取和修改：

<mdui-button variant="text">點我</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // 修改 HTML 屬性
  button.setAttribute('variant', 'outlined');

  // 讀取 HTML 屬性
  console.log(button.getAttribute('variant')); // outlined
</script>

JavaScript 屬性則可以直接讀取或設定元件實例的屬性值：

<mdui-button variant="text">點我</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // 設定 JavaScript 屬性
  button.variant = 'outlined';

  // 讀取 JavaScript 屬性
  console.log(button.variant); // outlined
</script>

某些屬性是布林型別，這些屬性的 HTML 屬性存在時，JavaScript 屬性為 true，否則為 false。但是，為了相容某些框架，mdui 會把字串 false 值也判定為布林值 false。

<!-- 這個元件存在 disabled 屬性，即預設 disabled 屬性值為 true -->
<mdui-button disabled></mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  button.removeAttribute('disabled'); // 等效於 button.disabled = false;
  button.setAttribute('disabled', ''); // 等效於 button.disabled = true;

  // 例外情況，設定為字串 false 值，等效於設定成布林值 false
  button.setAttribute('disabled', 'false'); // 等效於 button.disabled = false;
</script>

有時屬性值是陣列、物件或函式，這時只有 JavaScript 屬性，沒有對應的 HTML 屬性，例如 <mdui-slider> 元件的 labelFormatter 屬性是一個函式，你只能透過 JavaScript 來設定該屬性：

<mdui-slider></mdui-slider>

<script>
  const slider = document.querySelector('mdui-slider');
  slider.labelFormatter = (value) => `${value}%`;
</script>

以下以 <mdui-slider> 元件屬性文件的一部分為例：

這個元件的 name 屬性同時具有 HTML 屬性和 JavaScript 屬性，而 reflect 一欄表示更新 JavaScript 屬性時會同步更新 HTML 屬性。value 屬性在更新 JavaScript 屬性時不會更新 HTML 屬性，labelFormatter 屬性則只有 JavaScript 屬性。

方法

部分元件提供了公用方法，你可以透過呼叫這些方法來實作不同的功能。例如，<mdui-text-field> 元件的 focus() 方法可讓文字框取得焦點。

<mdui-text-field></mdui-text-field>

<script>
  const textField = document.querySelector('mdui-text-field');
  textField.focus();
</script>

可在各個元件的文件頁面查看所有可用的方法及其參數。

事件

部分元件在執行特定操作時會觸發事件。例如，<mdui-dialog> 元件在開啟時會觸發 open 事件，你可以監聽這個事件來執行自訂操作。

<mdui-dialog>Dialog</mdui-dialog>

<script>
  const dialog = document.querySelector('mdui-dialog');

  dialog.addEventListener('open', () => {
    console.log('對話框開始開啟時，會觸發該事件');
  });
</script>

可在各個元件的文件頁面查看所有可用的事件及其參數。

如果你在其他框架（如 Vue、React、Angular 等）中使用 mdui，你可以使用框架提供的語法來繫結事件。但是，一些框架（如 React）的事件繫結語法只能用於繫結標準事件（如 click 事件），而無法用於繫結自訂事件（如 open 事件）。因此，在 React 中繫結自訂事件時，你需要先取得元素的參考，然後使用 addEventListener 方法來繫結事件。

關於在 React 中使用 mdui 的更多資訊，參見 與框架整合 - React。

Slot

許多元件都提供了 Slot，用於將自訂的 HTML 內容插入到元件內部。

最常見的是預設 Slot，它是位於元件內部的一段普通 HTML 或純文字。例如 <mdui-button> 元件的預設 Slot 用於設定按鈕的文字。範例中的「點我」就是預設 Slot 的內容：

<mdui-button>點我</mdui-button>

部分元件還提供了具名 Slot，具名 Slot 需要在 HTML 的 slot 屬性中指定 Slot 名稱。下面的範例中，<mdui-icon> 元件指定了 slot="start"，表示這是名為 start 的具名 Slot，即這個圖示將被插入到元件內部的左側：

<mdui-button>
  <mdui-icon slot="start" name="settings"></mdui-icon>
  設定
</mdui-button>

如果一個元件使用了多個具名 Slot，那麼各個具名 Slot 之間的順序並不重要，只要它們位於元件內部，瀏覽器就會自動將它們放置到正確的位置。

可在各個元件的文件頁面查看所有支援的 Slot。

CSS 自訂屬性

CSS 自訂屬性是 CSS 中的變數。mdui 定義了一系列全域 CSS 自訂屬性，這些屬性在各個元件內部被參照，因此你可以透過修改這些 CSS 自訂屬性來全域修改 mdui 元件的樣式。

例如，下面的程式碼會縮小所有元件的圓角大小：

: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" 的元素及其子元素中縮小圓角大小：

.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 前綴。例如，下面的程式碼透過修改 <mdui-dialog> 元件的 --z-index 屬性，實作了修改 z-index 樣式：

mdui-dialog {
  --z-index: 3000;
}

可在各個元件的文件頁面查看元件支援的 CSS 自訂屬性。

CSS Part

mdui 元件使用 shadow DOM 來封裝樣式和行為，但是常規 CSS 選擇器無法選擇到 shadow DOM 內部的元素。因此，一些元件為 Shadow DOM 元素加入了 part 屬性，你可以使用 ::part CSS 選擇器來選擇到對應的元素，並重寫部分樣式。

例如，下面的程式碼使用 button part 修改了按鈕的內邊距，且使用 label、icon、end-icon part 分別修改了文字、左右圖示的顏色：

<mdui-button class="custom-button" icon="explore" end-icon="flight">Button</mdui-button>

<style>
  .custom-button::part(button) {
    padding: 0 2rem;
  }

  .custom-button::part(label) {
    color: blue;
  }

  .custom-button::part(icon) {
    color: red;
  }

  .custom-button::part(end-icon) {
    color: yellow;
  }
</style>

關於元件 shadow DOM 元素的結構和預設樣式，你可以開啟瀏覽器的開發人員工具進行查看。

在使用 CSS Part 之前，你應該先判斷使用全域 CSS 自訂屬性、及元件特有的 CSS 自訂屬性能否滿足你的需求，如果能滿足需求，則應優先使用 CSS 自訂屬性來訂製樣式。

可在各個元件的文件頁面查看元件公開的所有 part 屬性。

元件更新機制

mdui 元件是基於 Lit 開發的。Lit 是一個輕量級的函式庫，它使 Web Components 的開發更加簡單。在使用 mdui 元件時，你可能需要了解其渲染和更新機制。

當你修改 mdui 元件的屬性時，元件會進行重新渲染。但是，這個重新渲染過程並不是同步進行的。當你同時修改了多個屬性值時，Lit 會將這些變更快取起來，直到下一個更新週期，以確保無論你修改了多少次屬性值，每個元件只會重新渲染一次。並且，只有 shadow DOM 中發生變更的部分會被重新渲染。

在下面的範例中，我們將按鈕的 disabled JavaScript 屬性值設定為 true，然後立即查詢其 HTML 屬性。但是，由於此時元件還沒有進行重新渲染，因此查詢到的 HTML 屬性仍然是 false：

const button = document.querySelector('mdui-button');
button.disabled = true;

console.log(button.hasAttribute('disabled')); // false

如果要等待一個屬性值變更後的重新渲染完成，可以使用元件的 updateComplete 屬性。該屬性回傳 Promise，resolve 後即表示元件已完成重新渲染：

const button = document.querySelector('mdui-button');
button.disabled = true;

button.updateComplete.then(() => {
  console.log(button.hasAttribute('disabled')); // true
});