HTMLDialogElement

Thuộc tính instance

Cũng kế thừa các thuộc tính từ giao diện cha, HTMLElement.

HTMLDialogElement.closedBy

Một chuỗi đặt hoặc trả về thuộc tính HTML closedby, cho biết các loại hành động của người dùng có thể dùng để đóng hộp thoại.

HTMLDialogElement.open

Một giá trị boolean phản ánh thuộc tính HTML open, cho biết hộp thoại có sẵn sàng để tương tác hay không.

HTMLDialogElement.returnValue

Một chuỗi đặt hoặc trả về giá trị trả về cho hộp thoại.

Phương thức instance

Cũng kế thừa các phương thức từ giao diện cha, HTMLElement.

HTMLDialogElement.close()

Đóng hộp thoại. Có thể truyền một chuỗi tùy chọn làm đối số, cập nhật returnValue của hộp thoại.

HTMLDialogElement.requestClose()

Yêu cầu đóng hộp thoại. Có thể truyền một chuỗi tùy chọn làm đối số, cập nhật returnValue của hộp thoại.

HTMLDialogElement.show()

Hiển thị hộp thoại ở chế độ không modal, tức là vẫn cho phép tương tác với nội dung bên ngoài hộp thoại.

HTMLDialogElement.showModal()

Hiển thị hộp thoại dưới dạng modal, nằm trên cùng của bất kỳ hộp thoại nào khác có thể hiển thị. Mọi thứ bên ngoài hộp thoại đều ở trạng thái inert với các tương tác bên ngoài hộp thoại bị chặn.

Sự kiện

Cũng kế thừa các sự kiện từ giao diện cha, HTMLElement.

Lắng nghe các sự kiện này bằng cách sử dụng addEventListener() hoặc bằng cách gán trình xử lý sự kiện cho thuộc tính oneventname của giao diện này.

cancel

Được kích hoạt khi hộp thoại được yêu cầu đóng, dù bằng phím Escape, hoặc qua phương thức requestClose(). Nếu sự kiện bị hủy (thông qua Event.preventDefault()), hộp thoại sẽ vẫn mở. Nếu không bị hủy, hộp thoại sẽ đóng và sự kiện close sẽ được kích hoạt.

close

Được kích hoạt khi hộp thoại được đóng.

Ví dụ

Mở / đóng một hộp thoại modal

Ví dụ sau đây hiển thị một nút bấm, khi được nhấp vào, sẽ sử dụng hàm showModal() để mở một hộp thoại modal chứa một biểu mẫu.

Trong khi mở, mọi thứ khác ngoài nội dung của hộp thoại modal đều ở trạng thái inert. Bạn có thể nhấp vào nút Đóng để đóng hộp thoại (thông qua hàm close()), hoặc gửi biểu mẫu thông qua nút Xác nhận.

Ví dụ minh họa:

1. Đóng một biểu mẫu bằng hàm close()
2. Đóng một biểu mẫu khi gửi biểu mẫu và thiết lập returnValue của hộp thoại
3. Đóng một biểu mẫu bằng phím Esc
4. Các sự kiện "thay đổi trạng thái" có thể được kích hoạt trên hộp thoại: cancel và close, cùng các sự kiện kế thừa beforetoggle và toggle.

HTML

<dialog id="dialog">
  <button id="close" type="button">Đóng</button>
  <form method="dialog" id="form">
    <p>
      <label for="fav-animal">Loài vật yêu thích:</label>
      <select id="fav-animal" name="favAnimal" required>
        <option></option>
        <option>Tôm nước mặn</option>
        <option>Gấu mèo đỏ</option>
        <option>Khỉ nhện</option>
      </select>
    </p>
    <div>
      <button id="submit" type="submit">Xác nhận</button>
    </div>
  </form>
</dialog>

<button id="open">Mở hộp thoại</button>

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

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

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

JavaScript

Mở hộp thoại

Đoạn mã đầu tiên lấy các đối tượng cho phần tử <dialog>, các phần tử <button>, và phần tử <select>. Sau đó thêm một trình lắng nghe để gọi hàm HTMLDialogElement.showModal() khi nút Mở hộp thoại được nhấp.

const dialog = document.getElementById("dialog");
const openButton = document.getElementById("open");

// Nút mở mở một hộp thoại modal
openButton.addEventListener("click", () => {
  log(`dialog: showModal()`);
  dialog.showModal();
});

Đóng hộp thoại khi nút Đóng được nhấp

Tiếp theo, chúng ta thêm một trình lắng nghe cho sự kiện click của nút Đóng. Trình xử lý thiết lập returnValue và gọi hàm close() để đóng hộp thoại.

// Nút đóng đóng hộp thoại
const closeButton = document.getElementById("close");
closeButton.addEventListener("click", () => {
  dialog.returnValue = ""; // Đặt lại giá trị trả về
  log(`dialog: close()`);
  dialog.close();
// Hoặc, chúng ta có thể dùng dialog.requestClose(""); với giá trị trả về rỗng.
});

Đóng hộp thoại khi nút Xác nhận được nhấp thông qua gửi biểu mẫu

Tiếp theo, chúng ta thêm một trình lắng nghe cho sự kiện submit của <form>. Biểu mẫu được gửi khi phần tử <select> bắt buộc có giá trị và nút Xác nhận được nhấp. Nếu phần tử <select> không có giá trị, biểu mẫu sẽ không được gửi và hộp thoại sẽ vẫn mở.

// Nút xác nhận đóng hộp thoại nếu có lựa chọn.
const form = document.getElementById("form");
const selectElement = document.getElementById("fav-animal");
form.addEventListener("submit", () => {
  log(`form: submit`);
  // Đặt giá trị trả về thành giá trị của tùy chọn đã chọn
  dialog.returnValue = selectElement.value;
  // Chúng ta không cần đóng hộp thoại ở đây
  // việc gửi biểu mẫu với method="dialog" sẽ tự động làm điều đó.
  // dialog.close();
});

Lấy returnValue khi close

Gọi close() (hoặc gửi thành công một biểu mẫu với method="dialog") sẽ kích hoạt sự kiện close, mà chúng ta triển khai bên dưới bằng cách ghi lại giá trị trả về của hộp thoại.

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

Sự kiện cancel

Sự kiện cancel được kích hoạt khi sử dụng các "phương thức cụ thể của nền tảng" để đóng hộp thoại, chẳng hạn như phím Esc. Nó cũng được kích hoạt khi phương thức requestClose() được gọi. Sự kiện này có thể "hủy" nghĩa là chúng ta có thể dùng nó để ngăn hộp thoại đóng. Ở đây chúng ta chỉ xem việc hủy như một thao tác "đóng", và đặt lại returnValue về "" để xóa bất kỳ giá trị nào có thể đã được thiết lập.

dialog.addEventListener("cancel", (event) => {
  log(`cancel_event: (dialog.returnValue: "${dialog.returnValue}")`);
  dialog.returnValue = ""; // Đặt lại giá trị
});

Sự kiện toggle

Sự kiện toggle (kế thừa từ HTMLElement) được kích hoạt ngay sau khi một hộp thoại mở hoặc đóng (nhưng trước sự kiện close).

Ở đây chúng ta thêm một trình lắng nghe để ghi lại khi hộp thoại mở và đóng.

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

Sự kiện beforetoggle

Sự kiện beforetoggle (kế thừa từ HTMLElement) là một sự kiện có thể hủy được kích hoạt ngay trước khi một hộp thoại mở hoặc đóng. Nếu cần, điều này có thể được sử dụng để ngăn hộp thoại hiển thị, hoặc để thực hiện các hành động trên các phần tử khác bị ảnh hưởng bởi trạng thái mở/đóng của hộp thoại, chẳng hạn như thêm các lớp trên chúng để kích hoạt hoạt ảnh.

Trong trường hợp này, chúng ta chỉ ghi lại trạng thái cũ và mới.

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

  // Gọi event.preventDefault() để ngăn hộp thoại mở
  /*
    if (shouldCancel()) {
        event.preventDefault();
    }
  */
});

Kết quả

Hãy thử ví dụ bên dưới. Lưu ý rằng cả hai nút Xác nhận và Đóng đều dẫn đến sự kiện close được kích hoạt, và kết quả sẽ phản ánh tùy chọn dialog đã chọn.

Đặc tả kỹ thuật

Tương thích trình duyệt

api.HTMLDialogElement

api.HTMLElement.beforetoggle_event.dialog_elements

api.HTMLElement.toggle_event.dialog_elements

Xem thêm

• Phần tử HTML <dialog>