Document#
Document.createEvent()#
Metoda createEvent() tworzy nowe zdarzenie (tzw. niezaufane zdarzenie) o określonym ogólnym interfejsie zdarzenia dla danego dokumentu.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var new_event = document.createEvent(interface);gdzie poszczególne człony oznaczają:
- new_event - referencja do nowego zdarzenia.
- document - dokument będący obiektem kontekstu.
- interface - łańcuch znakowy reprezentujący jeden z ogólnych interfejsów dostępnych dla nowego zdarzenia.
Algorytm wywołania metody createEvent(interface) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Niech constructor będzie wartością
null. Jeśli interface pasuje pod względem nieczułości na wielkość znaków ASCII do któregokolwiek łańcucha znakowego w pierwszej kolumnie poniższej tabeli, to ustaw constructor na interfejs z drugiej kolumny tego samego wiersza, co dopasowany łańcuch znakowy:
Łańcuch znakowy Interfejs Uwagi " customevent"CustomEvent Specyfikacja DOM4 (bazowe interfejsy) " event"Event " events"" htmlevents"" keyboardevent"KeyboardEvent Specyfikacje D3E i UIE " mouseevent"MouseEvent " mouseevents"" uievent"UIEvent " uievents"" messageevent"MessageEvent Specyfikacja HTML5 " touchevent"TouchEvent Specyfikacja Touch Events Wszystkie aktualne przeglądarki internetowe obsługują szerszy zestaw dopuszczalnych łańcuchów i niewykluczone, że w przyszłości powyższa lista ulegnie rozszerzeniu o nazwy implementowane przez wiodące silniki (Mozilla - Bug 1251198, Chromium - Bug 569690, WebKit - Bug 103423).
- Jeśli constructor ma wartość
null, to zrzuć wyjątek"NotSupportedError". - Niech event będzie rezultatem tworzenia zdarzenia poprzez wywołanie interfejsu constructor w roli konstruktora, z domyślnymi wartościami i argumentem w postaci pustego łańcuch znakowego.
- Usuń flagę inicjalizacji w event.
- Zwróć event.
Nowe zdarzenie zwracane przez metodę createEvent() ma ustawiane domyślne wartości dla wszystkich swoich właściwości. Ponadto nie może zostać wysłane za pomocą metody EventTarget.dispatchEvent() dopóty, dopóki nie zostanie zainicjowane za pomocą metody Event.initEvent() lub analogicznej metody właściwej dla konkretnego interfejsu zdarzenia. Zdarzenia tworzone wprost z konstruktora new Event(), i pochodnych, są inicjowane automatycznie. Także wszystkie zaufane zdarzenia są inicjowane automatycznie przez daną implementację.
Ze względów bezpieczeństwa wszystkie zdarzenia generowane po stronie kodu JS bezpośrednio przez programistę, np. przy użyciu metody createEvent() czy też dedykowanego konstruktora, muszą ustawiać wartość właściwości Event.isTrusted na boolowskie false.
Obiekt zwracany przez metodę createEvent() implementuje interfejs Event (lub inny bardziej wyspecjalizowany interfejs dziedziczący po nim), dlatego ma dostęp do wszystkich poleceń z tego interfejsu (oraz z kolejnych interfejsów w łańcuchu dziedziczenia).
W ramach uzupełnienia najlepiej samodzielnie przeanalizować wady i zalety poszczególnych mechanizmów odpowiedzialnych za tworzenie niezaufanych zdarzeń bezpośrednio przez programistę.
Prosty przykład:
<!DOCTYPE html>
<html>
<head>
<script>
function createEvt(interface){
function getInfoEvt(whatEvt){
info.innerHTML = "Interfejs zdarzenia: " + whatEvt
+ "<br>" + "Argument z metody: " + interface
+ "<br><br>" + "Właściwość type: " + whatEvt.type
+ "<br>" + "Właściwość bubbles: " + whatEvt.bubbles
+ "<br>" + "Właściwość cancelable: " + whatEvt.cancelable
+ "<br>" + "Właściwość defaultPrevented: " + whatEvt.defaultPrevented
+ "<br>" + "Właściwość isTrusted: " + whatEvt.isTrusted
+ "<br>" + "Właściwość eventPhase: " + whatEvt.eventPhase
+ "<br>" + "Właściwość timeStamp: " + whatEvt.timeStamp
+ "<br>" + "Właściwość currentTarget: " + whatEvt.currentTarget
+ "<br>" + "Właściwość target: " + whatEvt.target + "<br><br>";
try{
window.dispatchEvent(whatEvt);
}
catch(e){
info.innerHTML += "Wysłanie niezainicjowanego zdarzenia utworzonego metodą createEvent() zrzuca błąd:"
+ "<br>" + e // opis zależny od przeglądarki
+ "<br>" + e.constructor; // function DOMException() { [native code] }
}
}
var info = document.getElementById("info");
try{
var newEvt = document.createEvent(interface);
getInfoEvt(newEvt);
}
catch(e){
info.innerHTML = "Przekazanie do metody createEvent() nieobsługiwanego interfejsu '" + interface + "' zrzuca błąd:"
+ "<br>" + e // opis zależny od przeglądarki
+ "<br>" + e.constructor; // function DOMException() { [native code] }
}
}
</script>
</head>
<body>
<p>Kliknij konkretny przycisk by utworzyć standardowe zdarzenie o określonym interfejsie zdarzenia:</p>
<input type="button" value="createEvent('event')" onclick="createEvt('event')">
<input type="button" value="createEvent('events')" onclick="createEvt('events')">
<input type="button" value="createEvent('htmlevents')" onclick="createEvt('htmlevents')">
<input type="button" value="createEvent('customevent')" onclick="createEvt('customevent')">
<input type="button" value="createEvent('mouseevent')" onclick="createEvt('mouseevent')">
<input type="button" value="createEvent('mouseevents')" onclick="createEvt('mouseevents')">
<input type="button" value="createEvent('mouseevents')" onclick="createEvt('mouseevents')">
<input type="button" value="createEvent('keyboardevent')" onclick="createEvt('keyboardevent')">
<input type="button" value="createEvent('uievent')" onclick="createEvt('uievent')">
<input type="button" value="createEvent('uievents')" onclick="createEvt('uievents')">
<input type="button" value="createEvent('messageevent')" onclick="createEvt('messageevent')">
<p>Zdarzenie dostępne tylko w przeglądarkach dotykowych (lub z trybem emulacji dotyku):</p>
<input type="button" value="createEvent('touchevent')" onclick="createEvt('touchevent')">
<p>Kilka niestandardowych nazw dla zdarzeń:</p>
<input type="button" value="createEvent('keyevents')" onclick="createEvt('keyevents')">
<input type="button" value="createEvent('DragEvent')" onclick="createEvt('DragEvent')">
<input type="button" value="createEvent('CompositionEvent')" onclick="createEvt('CompositionEvent')">
<input type="button" value="createEvent('HashChangeEvent')" onclick="createEvt('HashChangeEvent')">
<input type="button" value="createEvent('MutationEvent')" onclick="createEvt('MutationEvent')">
<input type="button" value="createEvent('StorageEvent')" onclick="createEvt('StorageEvent')">
<input type="button" value="createEvent('TextEvent')" onclick="createEvt('TextEvent')">
<p>Zmyślone nazwy dla zdarzenia:</p>
<input type="button" value="createEvent('źdźbło')" onclick="createEvt('źdźbło')">
<input type="button" value="createEvent('')" onclick="createEvt('')">
<p style="color: blue;">Szczegółowe informacje o nowym zdarzeniu:</p>
<p id="info"></p>
</body>
</html>W poprzedniej specyfikacji metoda createEvent() definiowana była w specjalnym interfejsie DocumentEvent, ale z dopiskiem, że powinna być implementowana bezpośrednio w interfejsie Document.
Składnia Web IDL#
interface Document : Node { [NewObject] Event createEvent(DOMString interface); };