HTMLDialogElement
Das HTMLDialogElement
Interface stellt Methoden zur Manipulation von <dialog>
-Elementen bereit. Es erbt Eigenschaften und Methoden vom HTMLElement
Interface.
Instanzeigenschaften
Erbt auch Eigenschaften von seinem übergeordneten Interface, HTMLElement
.
HTMLDialogElement.open
-
Ein boolescher Wert, der das HTML-Attribut
open
widerspiegelt und anzeigt, ob der Dialog für Interaktionen verfügbar ist. HTMLDialogElement.returnValue
-
Ein String, der den Rückgabewert des Dialogs festlegt oder zurückgibt.
Instanzmethoden
Erbt auch Methoden von seinem übergeordneten Interface, HTMLElement
.
HTMLDialogElement.close()
-
Schließt den Dialog. Ein optionaler String kann als Argument übergeben werden, um den
returnValue
des Dialogs zu aktualisieren. HTMLDialogElement.requestClose()
-
Fordert das Schließen des Dialogs an. Ein optionaler String kann als Argument übergeben werden, um den
returnValue
des Dialogs zu aktualisieren. HTMLDialogElement.show()
-
Zeigt den Dialog nicht-modular an, d.h. es ist weiterhin möglich, mit Inhalten außerhalb des Dialogs zu interagieren.
HTMLDialogElement.showModal()
-
Zeigt den Dialog als Modal an, über jeglichen anderen eventuell vorhandenen Dialogen. Alles außerhalb des Dialogs wird inert, und Interaktionen außerhalb des Dialogs werden blockiert.
Ereignisse
Erbt auch Ereignisse von seinem übergeordneten Interface, HTMLElement
.
Diese Ereignisse können mit addEventListener()
abgefangen werden oder indem ein Event-Listener der oneventname
-Eigenschaft dieses Interfaces zugewiesen wird.
cancel
-
Wird ausgelöst, wenn das Schließen des Dialogs angefordert wird, sei es durch die Escape-Taste oder durch die Methode
HTMLDialogElement.requestClose()
. close
-
Wird ausgelöst, wenn der Dialog geschlossen wird, sei es durch die Escape-Taste, die Methode
HTMLDialogElement.close()
, oder durch das Absenden eines Formulars innerhalb des Dialogs mitmethod="dialog"
.
Beispiele
Öffnen eines modalen Dialogs
Das folgende Beispiel zeigt einen Button, der bei einem Klick die Funktion HTMLDialogElement.showModal()
verwendet, um einen modalen <dialog>
mit einem Formular zu öffnen.
Während der Dialog geöffnet ist, ist alles andere als der Inhalt des modalen Dialogs inert.
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, die beim Dialog ausgelöst werden können: cancel
und close
, sowie die geerbten Ereignisse beforetoggle
und toggle
, verwenden könnten.
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 holt sich 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 angeklickt 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ätigungs-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 keinem Wert auf, was wiederum den Rückgabewert des Dialogs (HTMLDialogElement.returnValue
) auf den Auswahlwert und 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
});
Der Aufruf von close()
löst ebenfalls das close
-Ereignis aus, welches wir im Folgenden implementieren, indem der Rückgabewert des Dialogs protokolliert wird.
Wenn der Bestätigen-Button 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}")`);
});
Abbrechen-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 HTMLDialogElement.requestClose()
-Methode aufgerufen wird.
Das Ereignis ist "abbrechbar", was bedeutet, dass wir es verwenden könnten, um zu verhindern, dass der Dialog geschlossen wird.
Hier behandeln wir das Abbrechen einfach als eine "Schließen"-Operation und setzen den HTMLDialogElement.returnValue
auf ""
, um jeglichen 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 (geerbt von HTMLElement
) wird direkt nach dem Öffnen oder Schließen eines Dialogs (aber vor dem closed
-Ereignis) ausgelöst.
Hier fügen wir einen Listener hinzu, um zu protokollieren, wann der Dialog geöffnet und geschlossen wird.
Hinweis:
Die toggle
- und beforetoggle
-Ereignisse werden möglicherweise nicht in allen Browsern für Dialogelemente ausgelöst.
In diesen Browserversionen können Sie stattdessen die Eigenschaft HTMLDialogElement.open
überprüfen, nachdem Sie versucht haben, den Dialog zu öffnen/schließen.
dialog.addEventListener("toggle", (event) => {
log(`toggle_event: Dialog ${event.newState}`);
});
Beforetoggle-Ereignis
Das beforetoggle
-Ereignis (geerbt von HTMLElement
) ist ein abbrechbares 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 Öffnen/Schließen-Status des Dialogs betroffen sind, wie z. B. das Hinzufügen von Klassen, 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 Beispiel unten aus.
Beachten Sie, dass sowohl der Bestätigen
- als auch der Abbrechen
-Button das close
-Ereignis auslösen, und dass das Ergebnis die ausgewählte Dialogoption widerspiegeln sollte.
Spezifikationen
Specification |
---|
HTML # htmldialogelement |
HTML # event-beforetoggle |
HTML # event-toggle |
Browser-Kompatibilität
api.HTMLDialogElement
BCD tables only load in the browser
api.HTMLElement.beforetoggle_event.dialog_elements
BCD tables only load in the browser
api.HTMLElement.toggle_event.dialog_elements
BCD tables only load in the browser
Siehe auch
- Das HTML-Element, das dieses Interface implementiert:
<dialog>
.