HTMLDialogElement

Erbt auch Eigenschaften von seinem übergeordneten Interface, HTMLElement.

HTMLDialogElement.open

Ein boolescher Wert, der das HTML-Attribut open widerspiegelt und angibt, ob das Dialogfeld zur Interaktion verfügbar ist.

HTMLDialogElement.returnValue

Ein String, der den Rückgabewert für den Dialog festlegt oder zurückgibt.

Erbt auch Methoden von seinem übergeordneten Interface, HTMLElement.

HTMLDialogElement.close()

Schließt den Dialog. Es kann ein optionaler String als Argument übergeben werden, um den returnValue des Dialogs zu aktualisieren.

HTMLDialogElement.show()

Zeigt den Dialog modelless, d. h. ohne die Interaktion mit Inhalten außerhalb des Dialogs zu blockieren.

HTMLDialogElement.showModal()

Zeigt den Dialog als Modal über allen anderen Dialogen an, die möglicherweise vorhanden sind. Alles außerhalb des Dialogs ist inert und Interaktionen außerhalb des Dialogs werden blockiert.

Erbt auch Ereignisse von seinem übergeordneten Interface, HTMLElement.

Hören Sie diese Ereignisse mit addEventListener() ab oder indem Sie einen Event-Listener auf die oneventname-Eigenschaft dieses Interfaces zuweisen.

cancel

Wird ausgelöst, wenn der Benutzer das aktuell offene Dialogfeld mit der Escape-Taste schließt.

close

Wird ausgelöst, wenn der Dialog geschlossen wird, sei es mit der Escape-Taste, der Methode HTMLDialogElement.close() oder durch das Absenden eines Formulars im Dialog mit method="dialog".

Das folgende Beispiel zeigt einen Button, der beim Anklicken die Funktion HTMLDialogElement.showModal() verwendet, um ein modales <dialog> mit einem Formular zu öffnen.

Während des Öffnens ist alles außer dem Inhalt des modalen Dialogs inaktiv. Sie können auf den Cancel-Button klicken, um den Dialog zu schließen (über die Funktion HTMLDialogElement.close()), oder das Formular über den Confirm-Button absenden.

Das Beispiel demonstriert, wie Sie alle "Zustandsänderungs"-Ereignisse nutzen können, die im Dialog ausgeführt werden können: cancel und close, sowie die geerbten Ereignisse beforetoggle und 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>

<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

Dialog anzeigen

Der Code holt sich zunächst Objekte für die <button>-Elemente, das <dialog>-Element und das <select>-Element. Dann wird ein Listener hinzugefügt, um die Funktion HTMLDialogElement.showModal() aufzurufen, wenn der Update-Button geklickt wird.

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

Bestätigen- und Abbrechen-Buttons

Als Nächstes fügen wir Listener für die click-Ereignisse der Confirm- und Cancel-Buttons hinzu. Die Handler rufen HTMLDialogElement.close() mit dem Auswahlwert (falls vorhanden) und keinem Wert auf, was wiederum den Rückgabewert des Dialogs (HTMLDialogElement.returnValue) auf den Auswahlwert bzw. null setzt.

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

Das Aufrufen von close() löst auch das close-Ereignis aus, das wir unten implementieren, indem wir den Rückgabewert des Dialogs protokollieren. Wenn der Confirm-Button geklickt wurde, sollte dies der ausgewählte Wert im Dialog sein, andernfalls sollte er null sein.

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

Cancel-Ereignis

Das cancel-Ereignis wird ausgelöst, wenn "plattform-spezifische Methoden" verwendet werden, um den Dialog zu schließen, etwa die Esc-Taste. Das Ereignis ist "abbrechbar", was bedeutet, dass wir es verwenden könnten, um zu verhindern, dass der Dialog geschlossen wird. Hier behandeln wir das Abbrechen einfach als eine "Schließen"-Operation und setzen den HTMLDialogElement.returnValue auf "", um einen möglicherweise gesetzten Wert zu löschen.

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

Toggle-Ereignis

Das toggle-Ereignis (geerbt von HTMLElement) wird kurz nach dem Öffnen oder Schließen eines Dialogs ausgelöst (jedoch vor dem closed-Ereignis).

Hier fügen wir einen Listener hinzu, um zu protokollieren, wann der Dialog geöffnet und geschlossen wird.

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

Beforetoggle-Ereignis

Das beforetoggle-Ereignis (geerbt von HTMLElement) ist ein abbrechbares Ereignis, das kurz vor dem Öffnen oder Schließen eines Dialogs ausgelöst wird. Bei Bedarf kann dies genutzt werden, um zu verhindern, dass ein Dialog angezeigt wird, oder um Aktionen bei anderen Elementen auszuführen, die vom Dialog-Öffnungs-/Schließzustand betroffen sind, wie etwa das Hinzufügen von Klassen, um Animationen auszulösen.

In diesem Fall protokollieren wir einfach den alten und neuen Zustand.

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

Ergebnis

Probieren Sie das folgende Beispiel aus. Beachten Sie, dass sowohl die Buttons Confirm als auch Cancel dazu führen, dass das close-Ereignis ausgelöst wird, und dass das Ergebnis die ausgewählte Dialogoption widerspiegeln sollte.

• Das HTML-Element, das dieses Interface implementiert: <dialog>.