HTMLDialogElement
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2022.
Das HTMLDialogElement
-Interface bietet Methoden zur Manipulation von <dialog>
-Elementen. Es erbt Eigenschaften und Methoden vom HTMLElement
-Interface.
Instanz-Eigenschaften
Erbt auch Eigenschaften von seinem Eltern-Interface, HTMLElement
.
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 festlegt oder zurückgibt.
Instanz-Methoden
Erbt auch Methoden von seinem Eltern-Interface, HTMLElement
.
HTMLDialogElement.close()
-
Schließt den Dialog. Es kann ein optionaler String 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 Inhalten außerhalb des Dialogs möglich.
HTMLDialogElement.showModal()
-
Zeigt den Dialog als Modal an, über alle anderen gegebenenfalls vorhandenen Dialoge. Alles außerhalb des Dialogs ist inert und die Interaktion außerhalb des Dialogs wird blockiert.
Ereignisse
Erbt auch Ereignisse von seinem Eltern-Interface, HTMLElement
.
Hören Sie diese Ereignisse mit addEventListener()
ab oder weisen Sie einen Ereignis-Listener der oneventname
-Eigenschaft dieses Interfaces zu.
cancel
-
Wird ausgelöst, wenn der Benutzer den aktuellen offenen Dialog mit der Escape-Taste schließt.
close
-
Wird ausgelöst, wenn der Dialog geschlossen wird, sei es mit der Escape-Taste, der
HTMLDialogElement.close()
-Methode oder durch Absenden eines Formulars innerhalb des Dialogs mitmethod="dialog"
.
Beispiele
Öffnen eines modalen Dialogs
Das folgende Beispiel zeigt einen Button, der beim Klicken die Funktion HTMLDialogElement.showModal()
verwendet, um einen modalen <dialog>
mit einem Formular zu öffnen.
Solange der Dialog geöffnet ist, ist alles andere als der Inhalt des modalen Dialogs inaktiv.
Sie können den Abbrechen-Button klicken, um den Dialog zu schließen (über die Funktion HTMLDialogElement.close()
), oder das Formular über den Bestätigen-Button absenden.
Das Beispiel zeigt, wie Sie alle "Zustandsänderungs"-Ereignisse verwenden könnten, die am 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>
JavaScript
Anzeigen des Dialogs
Der Code erhält zuerst Objekte für die <button>
-Elemente, das <dialog>
-Element und das <select>
-Element.
Dann wird ein Listener hinzugefügt, um die Funktion HTMLDialogElement.showModal()
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, was wiederum den Rückgabewert des Dialogs (HTMLDialogElement.returnValue
) auf den Auswahlwert bzw. null
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 box
cancelButton.addEventListener("click", () => {
dialog.close(); // Set dialog.returnValue to null
});
Das Aufrufen von close()
löst auch das close
-Ereignis aus, das wir unten implementieren, indem wir den Rückgabewert des Dialogs protokollieren.
Wenn der Bestätigen-Button geklickt wurde, sollte dies der im Dialog gewä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 "plattformabhängige Methoden" verwendet werden, um den Dialog zu schließen, wie z.B. die Esc-Taste.
Das Ereignis ist "abbrechbar", was bedeutet, dass wir es verwenden könnten, um den Dialog am Schließen zu hindern.
Hier behandeln wir das Abbrechen einfach als "Schließen"-Operation und setzen den HTMLDialogElement.returnValue
auf ""
, um einen möglicherweise gesetzten Wert zu löschen.
dialog.addEventListener("cancel", (event) => {
log(`cancel_event: (dialog.returnValue: "${dialog.returnValue}")`);
dialog.returnValue = ""; //Reset value
});
Toggle-Ereignis
Das [toggle
]-Ereignis](/de/docs/Web/API/HTMLElement/toggle_event) (geerbt von HTMLElement
) wird kurz 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, wenn der Dialog geöffnet und geschlossen wird.
Hinweis: Die Ereignisse toggle
und beforetoggle
werden möglicherweise nicht bei allen Browsern bei Dialogelementen ausgelöst.
In diesen Browserversionen können Sie stattdessen die HTMLDialogElement.open
Eigenschaft überprüfen, nachdem Sie versucht haben, den Dialog zu öffnen/zu schließen.
dialog.addEventListener("toggle", (event) => {
log(`toggle_event: Dialog ${event.newState}`);
});
Beforetoggle-Ereignis
Das [beforetoggle
]-Ereignis](/de/docs/Web/API/HTMLElement/beforetoggle_event) (geerbt von HTMLElement
) ist ein abbrechbares Ereignis, das kurz vor dem Öffnen oder Schließen eines Dialogs ausgelöst wird.
Falls erforderlich, kann dies verwendet werden, um zu verhindern, dass ein Dialog angezeigt wird, oder um Aktionen an anderen Elementen durchzuführen, die vom offenen/geschlossenen Zustand des Dialogs betroffen sind, wie das Hinzufügen von Klassen auf ihnen, um Animationen auszulösen.
In diesem Fall protokollieren 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 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 das Ergebnis den ausgewählten Dialogoptionen entsprechen sollte.
Spezifikationen
Specification |
---|
HTML Standard # htmldialogelement |
Browser-Kompatibilität
BCD tables only load in the browser
Siehe auch
- Das HTML-Element, das dieses Interface implementiert:
<dialog>
.