HTMLDialogElement

Erbt auch Eigenschaften von ihrer Elternschnittstelle, HTMLElement.

HTMLDialogElement.open

Ein boolescher Wert, der das HTML-Attribut open widerspiegelt, welches anzeigt, ob der Dialog zur Interaktion verfügbar ist.

HTMLDialogElement.returnValue

Ein Zeichenfolgenwert, der den Rückgabewert für das Dialogfeld setzt oder zurückgibt.

Erbt auch Methoden von ihrer Elternschnittstelle, HTMLElement.

HTMLDialogElement.close()

Schließt den Dialog. Es kann optional eine Zeichenfolge als Argument übergeben werden, die den returnValue des Dialogs aktualisiert.

HTMLDialogElement.requestClose()

Fordert das Schließen des Dialogs an. Es kann optional eine Zeichenfolge als Argument übergeben werden, die den returnValue des Dialogs aktualisiert.

HTMLDialogElement.show()

Zeigt den Dialog modellfrei an, d.h. es ist weiterhin möglich, mit Inhalten außerhalb des Dialogs zu interagieren.

HTMLDialogElement.showModal()

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

Erbt auch Ereignisse von ihrer Elternschnittstelle, HTMLElement.

Diese Ereignisse können Sie mit addEventListener() abhören oder einen Ereignis-Listener der oneventname-Eigenschaft dieser Schnittstelle zuweisen.

cancel

Wird ausgelöst, wenn der Dialog das Schließen angefordert wird, sei es mit der Escape-Taste oder über die Methode HTMLDialogElement.requestClose().

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 innerhalb des Dialogs mit method="dialog".

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

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

Das Beispiel demonstriert, wie Sie alle "Zustandsänderung"-Ereignisse nutzen können, die im Dialog ausgelöst werden können: cancel und close, und 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

Den Dialog anzeigen

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

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() auf, mit dem Auswahlswert (falls vorhanden) und keinem Wert, wodurch der Rückgabewert des Dialogs (HTMLDialogElement.returnValue) auf den Auswahlswert bzw. null gesetzt wird.

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

Cancel-Ereignis

Das cancel-Ereignis 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 Methode HTMLDialogElement.requestClose() aufgerufen wird. Das Ereignis ist "cancelable", 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"-Operation und setzen den HTMLDialogElement.returnValue auf "", um jeden Wert zu löschen, der möglicherweise gesetzt wurde.

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

Toggle-Ereignis

Das toggle-Ereignis (geerbt von HTMLElement) wird unmittelbar nach dem Öffnen oder Schließen eines Dialogs ausgelöst (aber 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 unmittelbar bevor ein Dialog geöffnet oder geschlossen wird, ausgelöst wird. Falls erforderlich, kann dies verwendet werden, um zu verhindern, dass ein Dialog angezeigt wird, oder um Aktionen auf anderen Elementen auszuführen, die vom Dialogzustand zum Öffnen/Schließen betroffen sind, wie z.B. das Hinzufügen von Klassen zu ihnen, um Animationen auszulösen.

In diesem Fall protokollieren wir nur 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 Bestätigen- als auch die Abbrechen-Schaltflächen das close-Ereignis auslösen und dass das Ergebnis die im Dialog ausgewählte Option widerspiegeln sollte.

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