基於 Material Design 3 與 Web Components 的全新 mdui 2 現已發佈，前往查看 mdui 2 開發文件。

對話框

mdui 中的對話框是一個用途極廣的元件，經常被用來向使用者詢問資訊、通知或警告使用者。

同一時間只會有一個對話框處於顯示狀態。若目前的對話框尚未關閉就開啟下一個對話框，下一個對話框會先加入佇列，等目前對話框關閉後再開啟。

呼叫方式

透過自訂屬性呼叫
透過 JavaScript 呼叫

樣式

標準對話框

這是一個標準的對話框。

範例

<div class="mdui-dialog">
  <div class="mdui-dialog-title">Are you sure?</div>
  <div class="mdui-dialog-content">You'll lose all photos and media!</div>
  <div class="mdui-dialog-actions">
    <button class="mdui-btn mdui-ripple">cancel</button>
    <button class="mdui-btn mdui-ripple">erase</button>
  </div>
</div>

不含標題列

這個對話框不含標題列。

範例

<div class="mdui-dialog">
  <div class="mdui-dialog-content">Discard draft?</div>
  <div class="mdui-dialog-actions">
    <button class="mdui-btn mdui-ripple">cancel</button>
    <button class="mdui-btn mdui-ripple">discard</button>
  </div>
</div>

按鈕垂直排列

對話框底部的按鈕預設水平排列。只需在 <div class="mdui-dialog-actions"></div> 上添加類別 .mdui-dialog-actions-stacked 即可將按鈕設定為垂直排列。

範例

<div class="mdui-dialog">
  <div class="mdui-dialog-title">Use Google's location service?</div>
  <div class="mdui-dialog-content">Let Google help apps determine location. This means sending anonymous location data to Google, even when no apps are running.</div>
  <div class="mdui-dialog-actions mdui-dialog-actions-stacked">
    <button class="mdui-btn mdui-ripple">turn on speed boost</button>
    <button class="mdui-btn mdui-ripple">no thanks</button>
  </div>
</div>

固定標題和按鈕

在對話框內容超出對話框高度時，.mdui-dialog-content 中的內容會產生捲軸。

如果將 .mdui-dialog-title 和 .mdui-dialog-actions 放到 .mdui-dialog-content 內部，標題和底部按鈕就會隨著捲軸捲動；反之標題和按鈕將分別固定在頂部和底部，不隨捲軸捲動。

範例

<div class="mdui-dialog">
  <div class="mdui-dialog-content">
    <div class="mdui-dialog-title">Use Google's location service?</div>
    Let Google help apps determine location. This means sending anonymous location data to Google, even when no apps are running.
    <br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test<br/>test
  </div>
  <div class="mdui-dialog-actions">
    <button class="mdui-btn mdui-ripple">no thanks</button>
    <button class="mdui-btn mdui-ripple">turn on speeboost</button>
  </div>
</div>

自訂內容

對話框中只有 <div class="mdui-dialog"></div> 是必須的，該元素內的內容可以替換為任意 HTML。

下面範例中在對話框中放了一個分頁：

範例

<div class="mdui-dialog" id="example-4">
  <div class="mdui-tab mdui-tab-full-width" id="example4-tab">
    <a href="#example4-tab1" class="mdui-ripple">web</a>
    <a href="#example4-tab2" class="mdui-ripple">shopping</a>
    <a href="#example4-tab3" class="mdui-ripple">videos</a>
  </div>
  <div id="example4-tab1" class="mdui-p-a-2">
    <p>tab 1</p>
    <p>tab 1</p>
    <p>tab 1</p>
    <p>tab 1</p>
    <p>tab 1</p>
    <p>tab 1</p>
  </div>
  <div id="example4-tab2" class="mdui-p-a-2">
    <p>tab 2</p>
    <p>tab 2</p>
    <p>tab 2</p>
    <p>tab 2</p>
    <p>tab 2</p>
    <p>tab 2</p>
  </div>
  <div id="example4-tab3" class="mdui-p-a-2">
    <p>tab 3</p>
    <p>tab 3</p>
    <p>tab 3</p>
    <p>tab 3</p>
    <p>tab 3</p>
    <p>tab 3</p>
  </div>
</div>

<script>
  var tab = new mdui.Tab('#example4-tab');
  document.getElementById('example-4').addEventListener('open.mdui.dialog', function () {
    tab.handleUpdate();
  });
</script>

呼叫方式

透過自訂屬性呼叫

使用該方式無需編寫 JavaScript 程式碼。只要在一個具控制作用的元素（例如：按鈕）上新增 mdui-dialog="options" 屬性即可。透過自訂屬性呼叫時，需要額外添加一個 target 參數，用於指定被控制的對話框，其值為被控制的對話框的 CSS 選取器。

範例

<button class="mdui-btn mdui-ripple mdui-color-theme-accent" mdui-dialog="{target: '#exampleDialog'}">open</button>

<div class="mdui-dialog" id="exampleDialog">
  <div class="mdui-dialog-title">Are you sure?</div>
  <div class="mdui-dialog-content">You'll lose all photos and media!</div>
  <div class="mdui-dialog-actions">
    <button class="mdui-btn mdui-ripple" mdui-dialog-close>cancel</button>
    <button class="mdui-btn mdui-ripple" mdui-dialog-confirm>erase</button>
  </div>
</div>

在對話框內的元素上可以添加一些屬性來綁定事件，這些屬性在使用 JavaScript 呼叫時也可以使用。

屬性	說明
`mdui-dialog-close`	點擊該元素會觸發 `close.mdui.dialog` 事件，並關閉對話框。
`mdui-dialog-cancel`	點擊該元素會觸發 `cancel.mdui.dialog` 事件。
`mdui-dialog-confirm`	點擊該元素會觸發 `confirm.mdui.dialog` 事件。

透過 JavaScript 呼叫

實例化元件：

// selector 為對話框的 CSS 選取器或 DOM 元素或 HTML 字串
// options 為配置參數，見下面的參數清單
var inst = new mdui.Dialog(selector, options);

執行

參數

參數名稱	類型	預設值	說明
`overlay`	`boolean`	`true`	開啟對話框時是否顯示遮罩。
`history`	`boolean`	`true`	開啟對話框時是否添加 url hash，若為 true，則開啟對話框後可以透過瀏覽器的後退按鈕或 Android 的返回鍵關閉對話框。
`modal`	`boolean`	`false`	是否模態化對話框。為 false 時點擊對話框外面的區域時關閉對話框，否則不關閉。
`closeOnEsc`	`boolean`	`true`	按下 Esc 鍵時是否關閉對話框。
`closeOnCancel`	`boolean`	`true`	按下取消按鈕時是否關閉對話框。
`closeOnConfirm`	`boolean`	`true`	按下確認按鈕時是否關閉對話框。
`destroyOnClosed`	`boolean`	`false`	關閉對話框後是否自動銷毀對話框。

方法

方法名稱	說明
`open()`	開啟對話框。
`close()`	關閉對話框。
`toggle()`	切換對話框的開啟狀態。
`getState()`	取得對話框狀態。共包含四種狀態（`opening`、`opened`、`closing`、`closed`）。
`destroy()`	銷毀對話框。
`handleUpdate()`	重新調整對話框位置和捲軸高度。在開啟對話框後，如果修改了對話框內容，需要呼叫該方法。

事件

事件名稱	說明	目標	參數
`open.mdui.dialog`	對話框開始開啟動畫時，事件將被觸發。	`<div class="mdui-dialog"></div>`	`event._detail.inst`：實例
`opened.mdui.dialog`	對話框結束開啟動畫時，事件將被觸發。
`close.mdui.dialog`	對話框開始關閉動畫時，事件將被觸發。
`closed.mdui.dialog`	對話框結束關閉動畫時，事件將被觸發。
`cancel.mdui.dialog`	按下取消按鈕時，事件將被觸發。
`confirm.mdui.dialog`	按下確認按鈕時，事件將被觸發。

預定義對話框

mdui 針對常用場景封裝了幾個預定義的對話框函式，這些預定義的對話框只透過 JavaScript 呼叫，無需編寫 HTML 程式碼。

這些函式都傳回對話框實例。

mdui.dialog()

開啟一個對話框，標題、內容、按鈕等都可以自訂。該方法比較通用，後面的 mdui.alert()、mdui.confirm()、mdui.prompt() 都是使用該方法進行的封裝。

mdui.dialog(options)

範例

mdui.dialog({
  title: 'title',
  content: 'content',
  buttons: [
    {
      text: '取消'
    },
    {
      text: '確認',
      onClick: function(inst){
        mdui.alert('點擊確認按鈕的回呼');
      }
    }
  ]
});

參數

參數名稱	類型	預設值	說明
`title`	`string`		對話框的標題。
`content`	`string`		對話框內容。
`buttons`	`array`		按鈕陣列，每個按鈕都是一個帶按鈕參數的物件（見下面表格）。
`stackedButtons`	`boolean`	`false`	按鈕是否垂直排列。
`cssClass`	`string`		添加到 `.mdui-dialog` 上的 CSS 類別。
`history`	`boolean`	`true`	是否監聽 `hashchange` 事件，為 true 時可以透過 Android 的返回鍵或瀏覽器後退按鈕關閉對話框。
`overlay`	`boolean`	`true`	開啟對話框後是否顯示遮罩層。
`modal`	`boolean`	`false`	是否模態化對話框。為 false 時點擊對話框外面的區域時關閉對話框，否則不關閉。
`closeOnEsc`	`boolean`	`true`	按下 Esc 鍵時是否關閉對話框。
`destroyOnClosed`	`boolean`	`true`	關閉對話框後是否自動銷毀對話框。
`onOpen`	`function`		開啟動畫開始時的回呼。參數是對話框的實例。
`onOpened`	`function`		開啟動畫結束時的回呼。參數是對話框的實例。
`onClose`	`function`		關閉動畫開始時的回呼。參數是對話框的實例。
`onClosed`	`function`		關閉動畫結束時的回呼。參數是對話框的實例。

按鈕的參數：

參數名稱	類型	預設值	說明
`text`	`string`		按鈕文字。
`bold`	`boolean`	`false`	按鈕文字是否加粗。
`close`	`boolean`	`true`	點擊按鈕後是否關閉對話框。
`onClick`	`function`		點擊按鈕的回呼函式。

mdui.alert()

開啟一個警告框，可以包含標題、內容和一個確認按鈕：

mdui.alert(text, onConfirm, options)

mdui.alert(text, title, onConfirm, options)

範例

// 僅含文字
mdui.alert('content');

// 含標題和文字
mdui.alert('content', 'title');

// 含回呼
mdui.alert('content', 'title', function() {
  mdui.alert('點擊了確認按鈕');
});

// 含文字和回呼
mdui.alert('content', function() {
  mdui.alert('點擊了確認按鈕');
});

text: 文字
title: （可選）標題
onConfirm: （可選）點擊確認按鈕的回呼。參數是對話框的實例。
options: （可選）參數，見下表。

參數名稱	類型	預設值	說明
`confirmText`	`string`	`ok`	確認按鈕的文字。
`history`	`boolean`	`true`	是否監聽 `hashchange` 事件，為 true 時可以透過 Android 的返回鍵或瀏覽器後退按鈕關閉對話框。
`modal`	`boolean`	`false`	是否模態化對話框。為 false 時點擊對話框外面的區域時關閉對話框，否則不關閉。
`closeOnEsc`	`boolean`	`true`	按下 Esc 鍵時是否關閉對話框。
`closeOnConfirm`	`boolean`	`true`	按下確認按鈕時是否關閉對話框。

mdui.confirm()

開啟一個確認框，可以包含標題、內容、一個確認按鈕和一個取消按鈕：

mdui.confirm(text, onConfirm, onCancel, options)

mdui.confirm(text, title, onConfirm, onCancel, options)

範例

// 含文字和確認回呼
mdui.confirm('content', function(){
  mdui.alert('點擊了確認按鈕');
});

// 含文字、確認按鈕和取消按鈕回呼
mdui.confirm('content',
  function(){
    mdui.alert('點擊了確認按鈕');
  },
  function(){
    mdui.alert('點擊了取消按鈕');
  }
);

// 含文字、標題和確認按鈕回呼
mdui.confirm('content', 'title', function(){
  mdui.alert('點擊了確認按鈕');
});

// 含文字、標題確認按鈕和取消按鈕回呼
mdui.confirm('content', 'title',
  function(){
    mdui.alert('點擊了確認按鈕');
  },
  function(){
    mdui.alert('點擊了取消按鈕');
  }
);

text: 文字
title: （可選）標題
onConfirm: （可選）點擊確認按鈕的回呼。參數為對話框的實例。
onCancel: （可選）點擊取消按鈕的回呼。參數為對話框的實例。
options: （可選）參數，見下表。

參數名稱	類型	預設值	說明
`confirmText`	`string`	`ok`	確認按鈕的文字。
`cancelText`	`string`	`cancel`	取消按鈕的文字。
`history`	`boolean`	`true`	是否監聽 `hashchange` 事件，為 true 時可以透過 Android 的返回鍵或瀏覽器後退按鈕關閉對話框。
`modal`	`boolean`	`false`	是否模態化對話框。為 false 時點擊對話框外面的區域時關閉對話框，否則不關閉。
`closeOnEsc`	`boolean`	`true`	按下 Esc 鍵時是否關閉對話框。
`closeOnCancel`	`boolean`	`true`	按下取消按鈕時是否關閉對話框。
`closeOnConfirm`	`boolean`	`true`	按下確認按鈕時是否關閉對話框。

mdui.prompt()

開啟一個提示使用者輸入的對話框，可以包含標題、內容、文字方塊、一個確認按鈕和一個取消按鈕：

mdui.prompt(label, onConfirm, onCancel, options)

mdui.prompt(label, title, onConfirm, onCancel, options)

範例

// 單行文字方塊
mdui.prompt('這是一個單行文字方塊',
  function (value) {
    mdui.alert('您輸入了：' + value + ', 點擊了確認按鈕');
  },
  function (value) {
    mdui.alert('您輸入了：' + value + ', 點擊了取消按鈕');
  }
);

// 多行文字方塊
mdui.prompt('這是一個多行文字方塊',
  function (value) {
    mdui.alert('您輸入了：' + value + ', 點擊了確認按鈕');
  },
  function (value) {
    mdui.alert('您輸入了：' + value + ', 點擊了取消按鈕');
  },
  {
    type: 'textarea'
  }
);

// 含標題
mdui.prompt('請輸入文字', 'title',
  function (value) {
    mdui.alert('您輸入了：' + value + ', 點擊了確認按鈕');
  },
  function (value) {
    mdui.alert('您輸入了：' + value + ', 點擊了取消按鈕');
  }
);

label: 文字方塊浮動標籤的文字
title: （可選）標題
onConfirm: （可選）點擊確認按鈕的回呼。含兩個參數，分別為文字方塊的值和對話框的實例。
onCancel: （可選）點擊取消按鈕的回呼。含兩個參數，分別為文字方塊的值和對話框的實例。
options: （可選）參數，見下表

參數名稱	類型	預設值	說明
`confirmText`	`string`	`ok`	確認按鈕的文字
`cancelText`	`string`	`cancel`	取消按鈕的文字
`history`	`boolean`	`true`	是否監聽 `hashchange` 事件，為 true 時可以透過 Android 的返回鍵或瀏覽器後退按鈕關閉對話框。
`modal`	`boolean`	`false`	是否模態化對話框。為 false 時點擊對話框外面的區域時關閉對話框，否則不關閉。
`closeOnEsc`	`boolean`	`true`	按下 Esc 鍵時是否關閉對話框。
`closeOnCancel`	`boolean`	`true`	按下取消按鈕時是否關閉對話框
`closeOnConfirm`	`boolean`	`true`	按下確認按鈕時是否關閉對話框
`confirmOnEnter`	`boolean`	`false`	按下 Enter 鍵時觸發 `onConfirm` 回呼函式。
`type`	`string`	`text`	文字方塊的類型。 `text`: 單行文字方塊 `textarea`: 多行文字方塊
`maxlength`	`int`	`0`	最大輸入字元數量
`defaultValue`	`string`	`''`	文字方塊的預設值

CSS 類別清單

類別名稱	說明
`.mdui-dialog`	定義一個對話框元件。
`.mdui-dialog-title`	定義對話框的標題。
`.mdui-dialog-content`	定義對話框的內容。
`.mdui-dialog-actions`	定義對話框的動作列。
`.mdui-dialog-actions-stacked`	使對話框動作列的按鈕垂直排列。

表格

選單

對話框

呼叫方式

相關閱讀

樣式

標準對話框

不含標題列

按鈕垂直排列

固定標題和按鈕

自訂內容

呼叫方式

透過自訂屬性呼叫

透過 JavaScript 呼叫

參數

方法

事件

預定義對話框

mdui.dialog()

mdui.alert()

mdui.confirm()

mdui.prompt()

CSS 類別清單