HTMLDialogElement

例項屬性

它還繼承了其父介面 HTMLElement 的屬性。

HTMLDialogElement.closedBy: 一個字串，用於設定或返回 <dialog> 元素的 closedby 屬性值，該屬性指示可用於關閉對話方塊的使用者操作型別。
HTMLDialogElement.open: 一個布林值，反映 open HTML 屬性，指示對話方塊是否可用於互動。
HTMLDialogElement.returnValue: 一個字串，用於設定或返回對話方塊的返回值。

例項方法

它還繼承了其父介面 HTMLElement 的方法。

HTMLDialogElement.close(): 關閉對話方塊。可以傳遞一個可選字串作為引數，該引數將更新對話方塊的 returnValue。
HTMLDialogElement.requestClose(): 請求關閉對話方塊。可以傳遞一個可選字串作為引數，該引數將更新對話方塊的 returnValue。
HTMLDialogElement.show(): 以非模態方式顯示對話方塊，即仍然允許與對話方塊外部的內容進行互動。
HTMLDialogElement.showModal(): 以模態方式顯示對話方塊，置於任何其他可能存在的對話方塊之上。對話方塊外部的所有內容都將 inert，對話方塊外部的互動將被阻止。

事件

它還繼承了其父介面 HTMLElement 的事件。

使用 addEventListener() 監聽這些事件，或透過將事件監聽器分配給此介面的 oneventname 屬性。

cancel: 當對話方塊被請求關閉時觸發，無論是透過 Escape 鍵還是透過 HTMLDialogElement.requestClose() 方法。
close: 當對話方塊關閉時觸發，無論是透過 Escape 鍵、HTMLDialogElement.close() 方法，還是透過提交對話方塊內的表單（使用 method="dialog"）。

示例

開啟模態對話方塊

下面的示例展示了一個按鈕，點選該按鈕會使用 HTMLDialogElement.showModal() 函式開啟一個包含表單的模態 <dialog> 元素。

在對話方塊開啟期間，除對話方塊內容外，其他所有內容都處於 inert 狀態。您可以點選“取消”按鈕（透過 HTMLDialogElement.close() 函式）關閉對話方塊，或透過“確認”按鈕提交表單。

該示例演示瞭如何使用對話方塊上可能觸發的所有“狀態更改”事件：cancel 和 close，以及繼承的事件 beforetoggle 和 toggle。

HTML

html

<!-- pop-up dialog box, containing a form -->
<dialog id="favDialog">
  <form method="dialog">
    <p>
      <label for="favAnimal">Favorite animal:</label>
      <select id="favAnimal" name="favAnimal">
        <option></option>
        <option>Brine shrimp</option>
        <option>Red panda</option>
        <option>Spider monkey</option>
      </select>
    </p>
    <div>
      <button id="cancel" type="reset">Cancel</button>
      <button id="submit" type="submit">Confirm</button>
    </div>
  </form>
</dialog>

<div>
  <button id="updateDetails">Update details</button>
</div>

<pre id="log"></pre>

#log {
  height: 150px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

顯示對話方塊

程式碼首先獲取 <button> 元素、<dialog> 元素和 <select> 元素的對像。然後，當單擊“更新”按鈕時，新增一個監聽器來呼叫 HTMLDialogElement.showModal() 函式。

const updateButton = document.getElementById("updateDetails");
const confirmButton = document.getElementById("submit");
const cancelButton = document.getElementById("cancel");
const dialog = document.getElementById("favDialog");
const selectElement = document.getElementById("favAnimal");

// Update button opens a modal dialog
updateButton.addEventListener("click", () => {
  dialog.showModal();
});

取消和確認按鈕

接下來，我們為“確認”和“取消”按鈕的 click 事件新增監聽器。處理程式呼叫 HTMLDialogElement.close()，並傳遞（如果存在）選擇值和 null 值，這分別將對話方塊的返回值（HTMLDialogElement.returnValue）設定為選擇值和 null。

// Confirm button closes dialog if there is a selection.
confirmButton.addEventListener("click", () => {
  if (selectElement.value) {
    // Set dialog.returnValue to selected value
    dialog.close(selectElement.value);
  }
});

// Cancel button closes the dialog box
cancelButton.addEventListener("click", () => {
  dialog.close(); // Set dialog.returnValue to null
});

呼叫 close() 還會觸發 close 事件，我們在下面透過記錄對話方塊的返回值來實現這一點。如果單擊了“確認”按鈕，則應顯示對話方塊中選定的值，否則應為 null。

dialog.addEventListener("close", (event) => {
  log(`close_event: (dialog.returnValue: "${dialog.returnValue}")`);
});

取消事件

當使用“平臺特定方法”（如 Esc 鍵）關閉對話方塊時，會觸發 cancel 事件。呼叫 HTMLDialogElement.requestClose() 方法時也會觸發此事件。該事件是“可取消的”，這意味著我們可以用它來阻止對話方塊關閉。在這裡，我們只是將取消視為“關閉”操作，並將 HTMLDialogElement.returnValue 重置為 ""，以清除可能已設定的任何值。

dialog.addEventListener("cancel", (event) => {
  log(`cancel_event: (dialog.returnValue: "${dialog.returnValue}")`);
  dialog.returnValue = ""; // Reset value
});

切換事件

toggle 事件（繼承自 HTMLElement）在對話方塊開啟或關閉後立即觸發（但在 closed 事件之前）。

在這裡，我們新增一個監聽器來記錄對話方塊何時開啟和關閉。

注意： 並非所有瀏覽器都會在對話方塊元素上觸發 toggle 和 beforetoggle 事件。在這些瀏覽器版本中，您可以在嘗試開啟/關閉對話方塊後檢查 HTMLDialogElement.open 屬性。

dialog.addEventListener("toggle", (event) => {
  log(`toggle_event: Dialog ${event.newState}`);
});

beforetoggle 事件

beforetoggle 事件（繼承自 HTMLElement）是一個可取消的事件，在對話方塊開啟或關閉之前觸發。如有需要，可使用此事件來阻止對話方塊顯示，或對受對話方塊開啟/關閉狀態影響的其他元素執行操作，例如為其新增類來觸發動畫。

在這種情況下，我們只是記錄舊狀態和新狀態。

dialog.addEventListener("beforetoggle", (event) => {
  log(
    `beforetoggle event: oldState: ${event.oldState}, newState: ${event.newState}`,
  );

  // Call event.preventDefault() to prevent a dialog opening
  /*
    if (shouldCancel()) {
        event.preventDefault();
    }
  */
});

結果

請嘗試下面的示例。請注意，“確認”和“取消”按鈕都會導致 close 事件被觸發，並且結果應反映所選的對話方塊選項。

規範

規範
HTML # htmldialogelement
HTML # event-beforetoggle
HTML # event-toggle

實現此介面的 HTML 元素：<dialog>。

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ⁨2025 年 6 月 25 日⁩，由 MDN 貢獻者。

在 GitHub 上檢視此頁面 • 報告此內容的錯誤