HTMLDialogElement

基线 2022

新可用

自 2022 年 3 月起，此功能可在最新的设备和浏览器版本中使用。此功能可能在较旧的设备或浏览器中不起作用。

HTMLDialogElement 接口提供用于操作 <dialog> 元素的方法。它继承自 HTMLElement 接口的属性和方法。

实例属性

继承其父级 HTMLElement 的属性。

HTMLDialogElement.open: 一个布尔值，反映 open HTML 属性，指示对话框是否可供交互。
HTMLDialogElement.returnValue: 一个字符串，设置或返回对话框的返回值。

实例方法

继承其父级 HTMLElement 的方法。

HTMLDialogElement.close(): 关闭对话框。可以将一个可选字符串作为参数传递，更新对话框的 returnValue。
HTMLDialogElement.show(): 以非模态方式显示对话框，即仍然允许与对话框外部的内容交互。
HTMLDialogElement.showModal(): 将对话框显示为模态对话框，覆盖可能存在的任何其他对话框。对话框外部的所有内容都处于惰性状态，阻止对话框外部的交互。

事件

还继承其父接口 HTMLElement 的事件。

使用 addEventListener() 或通过为该接口的 oneventname 属性分配事件侦听器来侦听这些事件。

close: 当对话框关闭时触发，无论是使用 Escape 键、HTMLDialogElement.close() 方法，还是通过使用 method="dialog" 在对话框中提交表单触发。

以下示例显示了一个按钮，单击该按钮会通过 HTMLDialogElement.showModal() 函数打开一个包含表单的模态 <dialog>。打开后，模态对话框的内容以外的所有内容都处于惰性状态。从那里您可以单击“取消”按钮关闭对话框（通过 HTMLDialogElement.close() 函数），或通过提交按钮提交表单。选择取消按钮会关闭对话框，创建一个 close 事件，而不是 cancel 事件。

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 type="submit">Confirm</button>
    </div>
  </form>
</dialog>

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

JavaScript

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

function openCheck(dialog) {
  if (dialog.open) {
    console.log("Dialog open");
  } else {
    console.log("Dialog closed");
  }
}

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

// Form cancel button closes the dialog box
cancelButton.addEventListener("click", () => {
  dialog.close("animalNotChosen");
  openCheck(dialog);
});

结果

规范

规范
HTML 标准 # htmldialogelement

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅

实现此接口的 HTML 元素：<dialog>。