HTMLDialogElement

Instanzeigenschaften

Erbt außerdem Eigenschaften von ihrer übergeordneten Schnittstelle HTMLElement.

HTMLDialogElement.closedBy

Ein String, der das HTML-Attribut closedby setzt oder zurückgibt. Dieses gibt an, durch welche Benutzeraktionen der Dialog geschlossen werden kann.

HTMLDialogElement.open

Ein boolescher Wert, der das HTML-Attribut open widerspiegelt und angibt, ob eine Interaktion mit dem Dialog möglich ist.

HTMLDialogElement.returnValue

Ein String, der den Rückgabewert des Dialogs setzt oder zurückgibt.

Instanzmethoden

Erbt außerdem Methoden von ihrer übergeordneten Schnittstelle HTMLElement.

HTMLDialogElement.close()

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

HTMLDialogElement.requestClose()

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

HTMLDialogElement.show()

Zeigt den Dialog nichtmodal an. Eine Interaktion mit Inhalten außerhalb des Dialogs bleibt dabei möglich.

HTMLDialogElement.showModal()

Zeigt den Dialog modal über allen anderen möglicherweise vorhandenen Dialogen an. Alles außerhalb des Dialogs ist inert; Interaktionen außerhalb des Dialogs werden blockiert.

Ereignisse

Erbt außerdem Ereignisse von ihrer übergeordneten Schnittstelle HTMLElement.

Sie können diese Ereignisse mit addEventListener() überwachen oder der Eigenschaft oneventname dieser Schnittstelle einen Event-Listener zuweisen.

cancel

Wird ausgelöst, wenn das Schließen des Dialogs angefordert wird, sei es mit der Escape-Taste oder über die Methode requestClose(). Wird das Ereignis abgebrochen (mit Event.preventDefault()), bleibt der Dialog geöffnet. Andernfalls wird der Dialog geschlossen und das Ereignis close ausgelöst.

close

Wird ausgelöst, wenn der Dialog geschlossen wird.

Beispiele

Einen modalen Dialog öffnen und schließen

Das folgende Beispiel zeigt eine Schaltfläche, die beim Anklicken mit der Funktion showModal() einen modalen Dialog mit einem Formular öffnet.

Solange der Dialog geöffnet ist, ist alles außerhalb seines Inhalts inaktiv. Sie können auf die Schaltfläche Close klicken, um den Dialog mit der Funktion close() zu schließen, oder das Formular über die Schaltfläche Confirm absenden.

Das Beispiel zeigt:

1. Das Schließen eines Formulars mit der Funktion close()
2. Das Schließen eines Formulars beim Absenden und das Setzen des Dialog-returnValue über returnValue
3. Das Schließen eines Formulars mit der Taste Esc
4. Ereignisse bei Zustandsänderungen, die am Dialog ausgelöst werden können: 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

Den Dialog öffnen

Der Code ruft zunächst Objekte für das <dialog>-Element, die <button>-Elemente und das <select>-Element ab. Anschließend fügt er einen Event-Listener hinzu, der beim Anklicken der Schaltfläche Open Dialog die Funktion HTMLDialogElement.showModal() aufruft.

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

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

Den Dialog beim Anklicken der Schaltfläche Close schließen

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

// 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.
});

Den Dialog beim Anklicken der Schaltfläche Confirm durch Absenden des Formulars schließen

Als Nächstes fügen wir einen Event-Listener für das Ereignis submit des <form>-Elements hinzu. Das Formular wird abgesendet, wenn das erforderliche <select>-Element einen Wert hat und die Schaltfläche Confirm angeklickt wird. Hat das <select>-Element keinen Wert, wird das Formular nicht abgesendet und der Dialog bleibt geöffnet.

// 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();
});

returnValue bei close abrufen

Der Aufruf von close() (oder das erfolgreiche Absenden eines Formulars mit method="dialog") löst das Ereignis close aus. Im folgenden Beispiel protokollieren wir dabei den Rückgabewert des Dialogs.

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

Ereignis cancel

Das Ereignis cancel wird ausgelöst, wenn zum Schließen des Dialogs „plattformspezifische Methoden“ wie die Taste Esc verwendet werden. Es wird auch ausgelöst, wenn die Methode requestClose() aufgerufen wird. Das Ereignis kann abgebrochen werden. Damit ließe sich verhindern, dass der Dialog geschlossen wird. Hier behandeln wir das Ereignis lediglich als Schließvorgang und setzen returnValue auf "" zurück, um einen möglicherweise gesetzten Wert zu löschen.

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

Ereignis toggle

Das von HTMLElement geerbte Ereignis toggle wird unmittelbar nach dem Öffnen oder Schließen eines Dialogs ausgelöst, jedoch vor dem Ereignis close.

Hier fügen wir einen Event-Listener hinzu, der protokolliert, wann der Dialog geöffnet und geschlossen wird.

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

Ereignis beforetoggle

Das von HTMLElement geerbte Ereignis beforetoggle kann abgebrochen werden und wird unmittelbar vor dem Öffnen oder Schließen eines Dialogs ausgelöst. Bei Bedarf lässt sich damit verhindern, dass ein Dialog angezeigt wird. Sie können damit auch Aktionen an anderen Elementen ausführen, die vom geöffneten oder geschlossenen Zustand des Dialogs betroffen sind, etwa Klassen hinzufügen, um Animationen auszulösen.

In diesem Fall protokollieren wir lediglich 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 Schaltfläche Confirm als auch die Schaltfläche Close das Ereignis close auslösen und das Ergebnis die im Dialog ausgewählte Option widerspiegeln sollte.

Spezifikationen

Browser-Kompatibilität

api.HTMLDialogElement

api.HTMLElement.beforetoggle_event.dialog_elements

api.HTMLElement.toggle_event.dialog_elements

Siehe auch

• HTML-Element <dialog>