DieHTMLDialogElement-Schnittstelle bietet Methoden zur Manipulation von<dialog>-Elementen. Sie erbt Eigenschaften und Methoden von derHTMLElement-Schnittstelle.

Instanzeigenschaften

Erbt auch Eigenschaften von ihrer Elternschnittstelle,HTMLElement.

HTMLDialogElement.closedBy

Ein String, der den Wert desclosedby-Attributs des<dialog>-Elements festlegt oder zurückgibt, welches die Arten von Benutzeraktionen angibt, die zum Schließen des Dialogs verwendet werden können.

HTMLDialogElement.open

Ein boolescher Wert, der dasopen-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 festlegt oder zurückgibt.

Instanzmethoden

Erbt auch Methoden von ihrer Elternschnittstelle,HTMLElement.

HTMLDialogElement.close()

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

HTMLDialogElement.requestClose()

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

HTMLDialogElement.show()

Zeigt den Dialog modellfrei an, d.h. er erlaubt weiterhin Interaktionen mit dem Inhalt außerhalb des Dialogs.

HTMLDialogElement.showModal()

Zeigt den Dialog als Modal an, über allen anderen möglicherweise vorhandenen Dialogen. Alles außerhalb des Dialogs istinert und Interaktionen außerhalb des Dialogs sind blockiert.

Ereignisse

Erbt auch Ereignisse von ihrer Elternschnittstelle,HTMLElement.

Diese Ereignisse können Sie mitaddEventListener() abhören oder einen Ereignis-Listener deroneventname-Eigenschaft dieser Schnittstelle zuweisen.

cancel

Wird ausgelöst, wenn der Dialog geschlossen werden soll, entweder mit der Escape-Taste oder über die MethodeHTMLDialogElement.requestClose().

close

Wird ausgelöst, wenn der Dialog geschlossen wird, entweder mit der Escape-Taste, der MethodeHTMLDialogElement.close() oder durch das Absenden eines Formulars innerhalb des Dialogs mitmethod="dialog".

Beispiele

Öffnen eines modalen Dialogs

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

Während der Dialog geöffnet ist, ist alles andere als der Inhalt des modalen Dialogs inert.Sie können denAbbrechen-Button klicken, um den Dialog zu schließen (über die FunktionHTMLDialogElement.close()), oder das Formular über denBestätigen-Button absenden.

Das Beispiel demonstriert, wie Sie alle "Zustandsänderungs"-Ereignisse nutzen können, die im Dialog ausgelöst werden können:cancel undclose sowie die geerbten Ereignissebeforetoggle undtoggle.

HTML

<!-- pop-up dialog box, containing a form --><dialog>  <form method="dialog">    <p>      <label for="favAnimal">Favorite animal:</label>      <select name="favAnimal">        <option></option>        <option>Brine shrimp</option>        <option>Red panda</option>        <option>Spider monkey</option>      </select>    </p>    <div>      <button type="reset">Cancel</button>      <button type="submit">Confirm</button>    </div>  </form></dialog><div>  <button>Update details</button></div>

<pre></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 ruft zuerst Objekte für die<button>-Elemente, das<dialog>-Element und das<select>-Element ab.Dann wird ein Listener hinzugefügt, um die FunktionHTMLDialogElement.showModal() aufzurufen, wenn derAktualisieren-Button 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 dialogupdateButton.addEventListener("click", () => {  dialog.showModal();});

Bestätigen- und Abbrechen-Buttons

Als Nächstes fügen wir Listener für dieclick-Ereignisse derBestätigen- undAbbrechen-Buttons hinzu.Die Handler rufenHTMLDialogElement.close() mit dem Auswahlwert (falls vorhanden) und ohne Wert auf, was den Rückgabewert des Dialogs (HTMLDialogElement.returnValue) auf den Auswahlwert undnull 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 boxcancelButton.addEventListener("click", () => {  dialog.close(); // Set dialog.returnValue to null});

Der Aufruf vonclose() löst auch dasclose-Ereignis aus, das wir unten implementieren, indem wir den Rückgabewert des Dialogs loggen.Wenn derBestätigen-Button geklickt wurde, sollte dies der ausgewählte Wert im Dialog sein, andernfalls sollte esnull sein.

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

Abbrechen-Ereignis

Dascancel-Ereignis wird ausgelöst, wenn „plattform-spezifische Methoden“ verwendet werden, um den Dialog zu schließen, wie z.B. dieEsc-Taste.Es wird auch ausgelöst, wenn die MethodeHTMLDialogElement.requestClose() aufgerufen wird.Das Ereignis ist „abbrechbar“, was bedeutet, dass wir damit verhindern könnten, dass der Dialog geschlossen wird.Hier behandeln wir das Abbrechen einfach als „Schließen“-Vorgang und setzen denHTMLDialogElement.returnValue auf"" zurück, um einen gesetzten Wert zu löschen.

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

Umschalten-Ereignis

Dastoggle event (geerbt vonHTMLElement) wird direkt nach dem Öffnen oder Schließen eines Dialogs ausgelöst (aber vor demclosed-Ereignis).

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

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

Bevor-Umschalten-Ereignis

Dasbeforetoggle event (geerbt vonHTMLElement) ist ein abbrechbares Ereignis, das unmittelbar vor dem Öffnen oder Schließen eines Dialogs ausgelöst wird.Bei Bedarf kann es verwendet werden, um zu verhindern, dass ein Dialog angezeigt wird, oder um Aktionen an anderen Elementen auszuführen, die vom Öffnungs-/Schließzustand des Dialogs betroffen sind, wie z.B. das Hinzufügen von Klassen zu ihnen, um Animationen auszulösen.

In diesem Fall loggen 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 ButtonsBestätigen als auchAbbrechen dazu führen, dass dasclose-Ereignis ausgelöst wird und das Ergebnis die ausgewählte Dialogoption widerspiegeln sollte.

Spezifikationen

Browser-Kompatibilität

api.HTMLDialogElement

api.HTMLElement.beforetoggle_event.dialog_elements

api.HTMLElement.toggle_event.dialog_elements

Siehe auch

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