HTMLDialogElement

Instanzeigenschaften

Erbt auch Eigenschaften von seinem bergeordneten Interface, HTMLElement.

HTMLDialogElement.closedBy

Ein String, der das closedby-HTML-Attribut setzt oder zurckgibt, welches die Typen von Benutzeraktionen angibt, die zum Schlieen des Dialogs verwendet werden knnen.

HTMLDialogElement.open

Ein boolescher Wert, der das open-HTML-Attribut widerspiegelt und angibt, ob der Dialog fr Interaktionen verfgbar ist.

HTMLDialogElement.returnValue

Ein String, der den Rckgabewert fr den Dialog setzt oder zurckgibt.

Instanzmethoden

Erbt auch Methoden von seinem bergeordneten Interface, HTMLElement.

HTMLDialogElement.close()

Schliet den Dialog. Ein optionaler String kann als Argument bergeben werden, der den returnValue des Dialogs aktualisiert.

HTMLDialogElement.requestClose()

Fordert das Schlieen 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 auerhalb des Dialogs sind weiterhin mglich.

HTMLDialogElement.showModal()

Zeigt den Dialog als Modal an, das ber allen anderen mglicherweise vorhandenen Dialogen schwebt. Alles auerhalb des Dialogs ist inert und Interaktionen auerhalb des Dialogs werden blockiert.

Events

Erbt auch Events von seinem bergeordneten Interface, HTMLElement.

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

cancel

Wird ausgelst, wenn der Dialog angefordert wird zu schlieen, sei es ber die Escape-Taste oder ber die requestClose()-Methode. Wenn das Event abgebrochen wird (ber Event.preventDefault()), bleibt der Dialog geffnet. Wird es nicht abgebrochen, schliet der Dialog und das close-Event wird ausgelst.

close

Wird ausgelst, wenn der Dialog geschlossen wird.

Beispiele

ffnen/Schlieen eines modalen Dialogs

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

Whrend der ffnung ist alles auer dem Inhalt des modalen Dialogs inert. Sie knnen auf den Close-Button klicken, um den Dialog zu schlieen (ber die close()-Funktion), oder das Formular ber den Confirm-Button absenden.

Das Beispiel demonstriert:

1. Ein Formular mit der close()-Funktion schlieen
2. Ein Formular bei Formularabsendung schlieen und den returnValue des Dialogs setzen
3. Ein Formular mit der Esc-Taste schlieen
4. "Statusnderungs"-Ereignisse, die auf dem Dialog ausgelst werden knnen: cancel und close, sowie die geerbten Ereignisse beforetoggle und toggle.

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>

<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

Dialog ffnen

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

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 schlieen, wenn der Close-Button angeklickt wird

Als nchstes fgen wir einen Listener fr das Close-Button-click-Event hinzu. Der Handler setzt den returnValue und ruft die close()-Funktion auf, um den Dialog zu schlieen.

// 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 schlieen, wenn der Confirm-Button durch Formulareinreichung geklickt wird

Als nchstes fgen wir einen Listener fr 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 geffnet.

// 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"") lst das close-Event aus, was wir unten implementieren, indem wir den Rckgabewert des Dialogs protokollieren.

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

cancel-Event

Das cancel-Event wird ausgelst, wenn "plattform-spezifische Methoden" verwendet werden, um den Dialog zu schlieen, wie die Esc-Taste. Es wird auch ausgelst, wenn die requestClose()-Methode aufgerufen wird. Das Event ist "abbrechbar", was bedeutet, dass wir es verwenden knnten, um den Dialog daran zu hindern, sich zu schlieen. Hier behandeln wir das Abbrechen einfach als "Schlieen"-Aktion und setzen den returnValue auf "" zurck, um einen ggf. gesetzten Wert zu lschen.

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 Schlieen eines Dialogs ausgelst (aber vor dem close-Event).

Hier fgen wir einen Listener hinzu, um zu protokollieren, wann der Dialog geffnet und geschlossen wird.

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 Schlieen eines Dialogs ausgelst wird. Falls erforderlich, kann dies verwendet werden, um zu verhindern, dass ein Dialog angezeigt wird, oder um Aktionen auf anderen Elementen durchzufhren, die vom ffnen/Schlieen-Zustand des Dialogs betroffen sind, etwa durch das Hinzufgen von Klassen, um Animationen auszulsen.

In diesem Fall protokollieren wir einfach den alten und den 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 unten stehende Beispiel aus. Beachten Sie, dass sowohl die Confirm- als auch die Close-Schaltflchen dazu fhren, dass das close-Event ausgelst wird und dass das Ergebnis die ausgewhlte Dialogoption widerspiegeln sollte.

Spezifikationen

Browser-Kompatibilitt

api.HTMLDialogElement

api.HTMLElement.beforetoggle_event.dialog_elements

api.HTMLElement.toggle_event.dialog_elements

Siehe auch

• HTML <dialog> Element