HTMLDialogElement

Интерфейс HTMLDialogElement предоставляет методы для управления элементами <dialog>. Он наследует свойства и методы от интерфейса HTMLElement.

Также наследует свойства от родительского интерфейса HTMLElement.

HTMLDialogElement.open

Булевое значение, отражающее атрибут HTML open, указывающее, доступен ли диалог для взаимодействия.

HTMLDialogElement.returnValue

Строка, которая устанавливает или возвращает значение возврата для диалога.

Также наследует методы от родительского интерфейса HTMLElement.

HTMLDialogElement.close()

Закрывает диалог. В качестве аргумента можно передать необязательную строку, обновляющую returnValue диалога.

HTMLDialogElement.show()

Отображает диалог в бескомнатном режиме, то есть по-прежнему позволяя взаимодействовать с содержимым вне диалога.

HTMLDialogElement.showModal()

Отображает диалог в модальном режиме поверх всех других присутствующих диалогов. Всё за пределами диалога считается неактивным, взаимодействия вне диалога заблокированы.

Также наследует события от родительского интерфейса HTMLElement.

Подпишитесь на эти события с помощью addEventListener() или назначив обработчик событий свойству oneventname этого интерфейса.

cancel

Срабатывает, когда пользователь закрывает текущий открытый диалог клавишей Esc.

close

Срабатывает при закрытии диалога, независимо от того, было это сделано с помощью клавиши Esc, метода HTMLDialogElement.close() или путем отправки формы внутри диалога с использованием method="dialog".

В следующем примере показана кнопка, которая при нажатии использует функцию HTMLDialogElement.showModal() для открытия модального <dialog> содержащего форму.

Пока диалог открыт, всё кроме содержимого модального диалога неактивно. Можно нажать кнопку Отмена для закрытия диалога (с помощью функции HTMLDialogElement.close()) или отправить форму через кнопку Подтвердить.

Пример демонстрирует, как можно использовать все события «изменения состояния», которые могут быть сгенерированы диалогом: cancel и close, а также унаследованные события beforetoggle и toggle.

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>

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() с значением выбора (если оно есть) и без значения, что в свою очередь устанавливает значение возврата диалога (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}")`);
});

Событие Отмена

Событие cancel срабатывает, когда используются платформенно-специфичные методы для закрытия диалога, такие как нажатие клавиши Esc. Событие «отменяемое», что означает, что мы можем использовать его для предотвращения закрытия диалога. Здесь мы просто обрабатываем отмену как операцию «закрыть» и сбрасываем HTMLDialogElement.returnValue до "" для очистки любого установленного значения.

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

Событие Переключение

toggle событие (унаследованное от HTMLElement) генерируется сразу после открытия или закрытия диалога (но до события closed).

Здесь мы добавляем обработчик для записи, когда диалог открывается и закрывается.

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

Событие перед переключением

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();
    }
  */
});

Результат

Попробуйте пример ниже. Обратите внимание, что нажатие на обе кнопки Confirm и Cancel приводит к срабатыванию события close и что результат должен отражать выбранный параметр в диалоге.

• Элемент HTML, реализующий этот интерфейс: <dialog>.