HTMLDialogElement - Web-APIs | MDN

Seitenleiste umschalten

Farbschema

Systemeinstellung
Hell
Dunkel

Deutsch

Sprache merken Mehr erfahren

HTMLDialogElement

Baseline Weitgehend verfügbar *

Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit März 2022 browserübergreifend verfügbar.

* Einige Teile dieser Funktion werden möglicherweise unterschiedlich gut unterstützt.

Das HTMLDialogElement-Interface bietet Methoden zur Manipulation von <dialog>-Elementen. Es erbt Eigenschaften und Methoden vom HTMLElement-Interface.

EventTarget Node Element HTMLElement HTMLDialogElement

In diesem Artikel

Instanzeigenschaften

Erbt auch Eigenschaften von seinem übergeordneten Interface, HTMLElement.

HTMLDialogElement.closedBy

Ein String, der das closedby-HTML-Attribut setzt oder zurückgibt, welches die Typen von Benutzeraktionen angibt, die zum Schließen des Dialogs verwendet werden können.

HTMLDialogElement.open

Ein boolescher Wert, der das open-HTML-Attribut widerspiegelt und angibt, ob der Dialog für Interaktionen verfügbar ist.

HTMLDialogElement.returnValue

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

Instanzmethoden

Erbt auch Methoden von seinem übergeordneten Interface, HTMLElement.

HTMLDialogElement.close()

Schließt den Dialog. Ein optionaler String kann als Argument übergeben werden, der den returnValue des Dialogs aktualisiert.

HTMLDialogElement.requestClose()

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

HTMLDialogElement.show()

Zeigt den Dialog nicht-modal an, d.h. Interaktionen mit Inhalten außerhalb des Dialogs sind weiterhin möglich.

HTMLDialogElement.showModal()

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

Events

Erbt auch Events von seinem übergeordneten Interface, HTMLElement.

Hören Sie auf diese Events mit addEventListener() oder durch Zuweisen eines Event-Listeners zur oneventname-Eigenschaft dieses Interfaces.

cancel

Wird ausgelöst, wenn der Dialog angefordert wird zu schließen, sei es über die Escape-Taste oder über die requestClose()-Methode. Wenn das Event abgebrochen wird (über Event.preventDefault()), bleibt der Dialog geöffnet. Wird es nicht abgebrochen, schließt der Dialog und das close-Event wird ausgelöst.

Wird ausgelöst, wenn der Dialog geschlossen wird.

Beispiele

Öffnen/Schließen eines modalen Dialogs

Das folgende Beispiel zeigt eine Schaltfläche, die, wenn sie angeklickt wird, die showModal()-Funktion verwendet, um einen modalen Dialog mit einem Formular zu öffnen.

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

Das Beispiel demonstriert:

Ein Formular mit der close()-Funktion schließen
Ein Formular bei Formularabsendung schließen und den returnValue des Dialogs setzen
Ein Formular mit der Esc-Taste schließen
"Statusänderungs"-Ereignisse, die auf dem Dialog ausgelöst werden können: cancel und close, sowie die geerbten Ereignisse beforetoggle und toggle.

HTML

html
<dialog id="dialog">
  <button id="close" type="button">Close</button>
  <form method="dialog" id="form">
    <p>
      <label for="fav-animal">Favorite animal:</label>
      <select id="fav-animal" name="favAnimal" required>
        <option></option>
        <option>Brine shrimp</option>
        <option>Red panda</option>
        <option>Spider monkey</option>
      </select>
    </p>
    <div>
      <button id="submit" type="submit">Confirm</button>
    </div>
  </form>
</dialog>

<button id="open">Open dialog</button>

#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

Dialog öffnen

Der Code holt zuerst Objekte für das <dialog>-Element, die <button>-Elemente und das <select>-Element. Dann wird ein Listener hinzugefügt, um die HTMLDialogElement.showModal()-Funktion aufzurufen, wenn der Open Dialog-Button angeklickt wird.

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

// Open button opens a modal dialog
openButton.addEventListener("click", () => {
  log(`dialog: showModal()`);
  dialog.showModal();
});

Dialog schließen, wenn der Close-Button angeklickt wird

Als nächstes fügen wir einen Listener für das Close-Button-click-Event hinzu. Der Handler setzt den returnValue und ruft die close()-Funktion auf, um den Dialog zu schließen.

js
// Close button closes the dialog box
const closeButton = document.getElementById("close");
closeButton.addEventListener("click", () => {
  dialog.returnValue = ""; // Reset return value
  log(`dialog: close()`);
  dialog.close();
  // Alternatively, we could use dialog.requestClose(""); with an empty return value.
});

Dialog schließen, wenn der Confirm-Button durch Formulareinreichung geklickt wird

Als nächstes fügen wir einen Listener für das <form>-submit-Event hinzu. Das Formular wird eingereicht, wenn das erforderliche <select>-Element einen Wert hat und der Confirm-Button angeklickt wird. Wenn das <select>-Element keinen Wert hat, wird das Formular nicht eingereicht und der Dialog bleibt geöffnet.

js
// Confirm button closes dialog if there is a selection.
const form = document.getElementById("form");
const selectElement = document.getElementById("fav-animal");
form.addEventListener("submit", () => {
  log(`form: submit`);
  // Set the return value to the selected option value
  dialog.returnValue = selectElement.value;
  // We don't need to close the dialog here
  // submitting the form with method="dialog" will do that automatically.
  // dialog.close();
});

Den returnValue bei close abrufen

Das Aufrufen von close() (oder das erfolgreiche Einreichen eines Formulars mit method="dialog"") löst das close-Event aus, was wir unten implementieren, indem wir den Rückgabewert des Dialogs protokollieren.

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

cancel-Event

Das cancel-Event wird ausgelöst, wenn "plattform-spezifische Methoden" verwendet werden, um den Dialog zu schließen, wie die Esc-Taste. Es wird auch ausgelöst, wenn die requestClose()-Methode aufgerufen wird. Das Event ist "abbrechbar", was bedeutet, dass wir es verwenden könnten, um den Dialog daran zu hindern, sich zu schließen. Hier behandeln wir das Abbrechen einfach als "Schließen"-Aktion und setzen den returnValue auf "" zurück, um einen ggf. gesetzten Wert zu löschen.

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

toggle-Event

Das toggle-Event (geerbt von HTMLElement) wird unmittelbar nach dem Öffnen oder Schließen eines Dialogs ausgelöst (aber vor dem close-Event).

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

Hinweis: Die toggle und beforetoggle-Ereignisse werden möglicherweise nicht bei Dialogelementen in allen Browsern ausgelöst. Bei diesen Browserversionen können Sie stattdessen die open-Eigenschaft überprüfen, nachdem Sie versucht haben, den Dialog zu öffnen oder zu schließen.

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

beforetoggle-Event

Das beforetoggle-Event (geerbt von HTMLElement) ist ein abbrechbares Event, das unmittelbar vor dem Öffnen oder Schließen eines Dialogs ausgelöst wird. Falls erforderlich, kann dies verwendet werden, um zu verhindern, dass ein Dialog angezeigt wird, oder um Aktionen auf anderen Elementen durchzuführen, die vom Öffnen/Schließen-Zustand des Dialogs betroffen sind, etwa durch das Hinzufügen von Klassen, um Animationen auszulösen.

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

js
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 unten stehende Beispiel aus. Beachten Sie, dass sowohl die Confirm- als auch die Close-Schaltflächen dazu führen, dass das close-Event ausgelöst wird und dass das Ergebnis die ausgewählte Dialogoption widerspiegeln sollte.