HTMLDialogElement

Instanzeigenschaften

Erbt auerdem Eigenschaften von ihrer bergeordneten Schnittstelle HTMLElement.

HTMLDialogElement.closedBy

Ein String, der das HTML-Attribut closedby setzt oder zurckgibt. 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 mglich ist.

HTMLDialogElement.returnValue

Ein String, der den Rckgabewert des Dialogs setzt oder zurckgibt.

Instanzmethoden

Erbt auerdem Methoden von ihrer bergeordneten Schnittstelle HTMLElement.

HTMLDialogElement.close()

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

HTMLDialogElement.requestClose()

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

HTMLDialogElement.showModal()

Zeigt den Dialog modal ber allen anderen mglicherweise vorhandenen Dialogen an. Alles auerhalb des Dialogs ist inert; Interaktionen auerhalb des Dialogs werden blockiert.

Ereignisse

Erbt auerdem Ereignisse von ihrer bergeordneten Schnittstelle HTMLElement.

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

cancel

Wird ausgelst, wenn das Schlieen 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 geffnet. Andernfalls wird der Dialog geschlossen und das Ereignis close ausgelst.

close

Wird ausgelst, wenn der Dialog geschlossen wird.

Beispiele

Einen modalen Dialog ffnen und schlieen

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

Solange der Dialog geffnet ist, ist alles auerhalb seines Inhalts inaktiv. Sie knnen auf die Schaltflche Close klicken, um den Dialog mit der Funktion close() zu schlieen, oder das Formular ber die Schaltflche Confirm absenden.

Das Beispiel zeigt:

1. Das Schlieen eines Formulars mit der Funktion close()
2. Das Schlieen eines Formulars beim Absenden und das Setzen des Dialog-returnValue ber returnValue
3. Das Schlieen eines Formulars mit der Taste Esc
4. Ereignisse bei Zustandsnderungen, die am 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

Den Dialog ffnen

Der Code ruft zunchst Objekte fr das <dialog>-Element, die <button>-Elemente und das <select>-Element ab. Anschlieend fgt er einen Event-Listener hinzu, der beim Anklicken der Schaltflche 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 Schaltflche Close schlieen

Als Nchstes fgen wir einen Event-Listener fr das Ereignis click der Schaltflche Close hinzu. Der Handler setzt returnValue und ruft die Funktion close() 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.
});

Den Dialog beim Anklicken der Schaltflche Confirm durch Absenden des Formulars schlieen

Als Nchstes fgen wir einen Event-Listener fr das Ereignis submit des <form>-Elements hinzu. Das Formular wird abgesendet, wenn das erforderliche <select>-Element einen Wert hat und die Schaltflche Confirm angeklickt wird. Hat das <select>-Element keinen Wert, wird das Formular nicht abgesendet 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();
});

returnValue bei close abrufen

Der Aufruf von close() (oder das erfolgreiche Absenden eines Formulars mit method="dialog") lst das Ereignis close aus. Im folgenden Beispiel protokollieren wir dabei den Rckgabewert des Dialogs.

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

Ereignis cancel

Das Ereignis cancel wird ausgelst, wenn zum Schlieen des Dialogs plattformspezifische Methoden wie die Taste Esc verwendet werden. Es wird auch ausgelst, wenn die Methode requestClose() aufgerufen wird. Das Ereignis kann abgebrochen werden. Damit liee sich verhindern, dass der Dialog geschlossen wird. Hier behandeln wir das Ereignis lediglich als Schlievorgang und setzen returnValue auf "" zurck, um einen mglicherweise gesetzten Wert zu lschen.

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 Schlieen eines Dialogs ausgelst, jedoch vor dem Ereignis close.

Hier fgen wir einen Event-Listener hinzu, der protokolliert, wann der Dialog geffnet 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 Schlieen eines Dialogs ausgelst. Bei Bedarf lsst sich damit verhindern, dass ein Dialog angezeigt wird. Sie knnen damit auch Aktionen an anderen Elementen ausfhren, die vom geffneten oder geschlossenen Zustand des Dialogs betroffen sind, etwa Klassen hinzufgen, um Animationen auszulsen.

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 Schaltflche Confirm als auch die Schaltflche Close das Ereignis close auslsen und das Ergebnis die im Dialog ausgewhlte Option widerspiegeln sollte.

Spezifikationen

Browser-Kompatibilitt

api.HTMLDialogElement

api.HTMLElement.beforetoggle_event.dialog_elements

api.HTMLElement.toggle_event.dialog_elements

Siehe auch

• HTML-Element <dialog>