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 上查看此页面 • 报告此内容的错误