HTMLDialogElement

Erbt auch Eigenschaften von seiner Elternschnittstelle, 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 des Dialogs setzt oder zurückgibt.

Erbt auch Methoden von seiner Elternschnittstelle, HTMLElement.

HTMLDialogElement.close()

Schließt das Dialogfeld. Ein optionaler String kann als Argument übergeben werden, um den returnValue des Dialogs zu aktualisieren.

HTMLDialogElement.requestClose() Experimentell

Fordert das Schließen des Dialogs an. Ein optionaler String kann als Argument übergeben werden, um den returnValue des Dialogs zu aktualisieren.

HTMLDialogElement.show()

Zeigt das Dialogfeld modeless an, d. h. erlaubt weiterhin die Interaktion mit Inhalten außerhalb des Dialogs.

HTMLDialogElement.showModal()

Zeigt das Dialogfeld als Modal an, über anderen möglicherweise vorhandenen Dialogen. Alles außerhalb des Dialogs ist inert, wobei Interaktionen außerhalb des Dialogs blockiert sind.

Erbt auch Ereignisse von seiner Elternschnittstelle, HTMLElement.

Hören Sie auf diese Ereignisse mit addEventListener() oder durch Zuweisen eines Ereignis-Listeners zur oneventname-Eigenschaft dieser Schnittstelle.

cancel

Wird ausgelöst, wenn das Dialogfeld geschlossen werden soll, sei es mit der Escape-Taste oder über die HTMLDialogElement.requestClose()-Methode.

close

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

Das folgende Beispiel zeigt eine Schaltfläche, die beim Anklicken die HTMLDialogElement.showModal()-Funktion verwendet, um ein modales <dialog> mit einem Formular zu öffnen.

Während es geöffnet ist, ist alles außer den Inhalten des modalen Dialogs inert. Sie können die Abbrechen-Schaltfläche anklicken, um den Dialog zu schließen (über die HTMLDialogElement.close()-Funktion), oder das Formular über die Bestätigen-Schaltfläche absenden.

Das Beispiel zeigt, wie Sie alle "Zustandsänderungs"-Ereignisse nutzen können, die auf dem Dialog ausgelöst 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

Anzeigen des Dialogs

Der Code erhält zuerst Objekte für die <button>-Elemente, das <dialog>-Element und das <select>-Element. Dann wird ein Listener hinzugefügt, um die HTMLDialogElement.showModal()-Funktion aufzurufen, wenn die Aktualisieren-Schaltfläche angeklickt 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();
});

Abbrechen- und Bestätigen-Schaltflächen

Als nächstes fügen wir Listener für die click-Ereignisse der Bestätigen- und Abbrechen-Schaltflächen hinzu. Die Handler rufen HTMLDialogElement.close() mit dem Auswahlwert (falls vorhanden) und ohne 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
});

Der Aufruf von close() löst auch das close-Ereignis aus, das wir unten implementieren, indem wir den Rückgabewert des Dialogs protokollieren. Wenn die Bestätigen-Schaltfläche angeklickt wurde, sollte dies der ausgewählte Wert im Dialog sein, andernfalls sollte es null sein.

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

Abbrechen-Ereignis

Das cancel-Ereignis wird ausgelöst, wenn "plattform-spezifische Methoden" verwendet werden, um das Dialogfeld zu schließen, wie die Esc-Taste. Es wird auch ausgelöst, wenn die HTMLDialogElement.requestClose()-Methode aufgerufen wird. Das Ereignis ist "abbrechbar", was bedeutet, dass wir es verwenden könnten, um das Schließen des Dialogs zu verhindern. Hier behandeln wir den Abbruch einfach als "Schließen"-Vorgang und setzen den HTMLDialogElement.returnValue auf "", um jeden 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 (von HTMLElement geerbt) wird unmittelbar nach dem Öffnen oder Schließen eines Dialogs (aber vor dem closed-Ereignis) ausgelöst.

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 (von HTMLElement geerbt) ist ein abbrechbares Ereignis, das unmittelbar vor dem Öffnen oder Schließen eines Dialogs ausgelöst wird. Falls nötig, kann dies verwendet werden, um das Anzeigen eines Dialogs zu verhindern oder um Aktionen bei anderen Elementen auszuführen, die vom Dialog-Öffnen/Schließen-Zustand betroffen sind, z. B. um Klassen hinzuzufügen, 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 Beispiel unten aus. Beachten Sie, dass sowohl die Bestätigen- als auch die Abbrechen-Schaltflächen das close-Ereignis auslösen und dass das Ergebnis die ausgewählte Dialogoption widerspiegeln sollte.

• Das HTML-Element, das diese Schnittstelle implementiert: <dialog>.