HTMLDialogElement

Übernimmt auch Eigenschaften von ihrer Eltern-Schnittstelle, HTMLElement.

HTMLDialogElement.closedBy

Ein String, der den closedby-Attributwert des <dialog>-Elements setzt oder zurückgibt, was die Arten von Benutzeraktionen angibt, die zum Schließen des Dialogs verwendet werden können.

HTMLDialogElement.open

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

HTMLDialogElement.returnValue

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

Übernimmt auch Methoden von ihrer Eltern-Schnittstelle, 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 modellfrei an, d.h. es ist weiterhin eine Interaktion mit dem Inhalt außerhalb des Dialogs möglich.

HTMLDialogElement.showModal()

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

Übernimmt auch Ereignisse von ihrer Eltern-Schnittstelle, HTMLElement.

Hören Sie diesen Ereignissen mit addEventListener() zu oder weisen Sie einen Ereignis-Listener der oneventname-Eigenschaft dieser Schnittstelle zu.

cancel

Wird ausgelöst, wenn das Schließen des Dialogs 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 einen Button, der beim Klicken die Funktion HTMLDialogElement.showModal() verwendet, um einen modalen <dialog> zu öffnen, der ein Formular enthält.

Wenn es geöffnet ist, wird alles außer dem Inhalt des modalen Dialogs inert. Sie können den Abbrechen-Button klicken, um den Dialog (über die Funktion HTMLDialogElement.close()) zu schließen oder das Formular über den Bestätigen-Button abschicken.

Das Beispiel zeigt, wie Sie alle „Zustandsänderungs“-Ereignisse verwenden können, die beim 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

Den Dialog anzeigen

Der Code ruft zunächst Objekte für die <button>-Elemente, das <dialog>-Element und das <select>-Element ab. Anschließend wird ein Listener hinzugefügt, um die Funktion HTMLDialogElement.showModal() zu aufzurufen, wenn der Aktualisieren-Button 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-Buttons

Als Nächstes fügen wir Listener für die click-Ereignisse der Bestätigen- und Abbrechen-Buttons hinzu. Die Handler rufen HTMLDialogElement.close() mit dem Auswahlwert (falls vorhanden) und ohne Wert auf, wodurch der Rückgabewert des Dialogs (HTMLDialogElement.returnValue) auf den Auswahlwert bzw. auf 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
});

Das Aufrufen von close() löst auch das close-Ereignis aus, welches wir unten implementieren, indem wir den Rückgabewert des Dialogs protokollieren. Wenn der Bestätigen-Button geklickt wurde, sollte dies der im Dialog ausgewählte Wert 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“ zum Schließen des Dialogs verwendet werden, wie z.B. die Esc-Taste. Es wird auch ausgelöst, wenn die Methode HTMLDialogElement.requestClose() aufgerufen wird. Das Ereignis ist „unterdrückbar“, was bedeutet, dass wir es verwenden könnten, um das Schließen des Dialogs zu verhindern. Hier behandeln wir das Abbrechen einfach als eine „Schließen“-Operation und setzen den HTMLDialogElement.returnValue auf "", um etwaige gesetzte Werte zu löschen.

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 unterdrückbares Ereignis, das unmittelbar vor dem Öffnen oder Schließen eines Dialogs ausgelöst wird. Bei Bedarf kann dies verwendet werden, um zu verhindern, dass ein Dialog angezeigt wird, oder um Aktionen an anderen Elementen auszuführen, die vom Dialogzustand betroffen sind, wie z.B. das Hinzufügen von Klassen zu ihnen, um Animationen auszulösen.

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 folgende Beispiel aus. Beachten Sie, dass sowohl die Bestätigen- als auch die Abbrechen-Buttons dazu führen, dass das close-Ereignis ausgelöst wird und dass das Ergebnis die ausgewählte Dialogoption widerspiegeln sollte.

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