CustomEvent#
new CustomEvent()#
Interfejs CustomEvent może być wywoływany w roli konstruktora, dzięki czemu pozwala na bezpośrednie tworzenie nowych prywantych zdarzeń (syntetycznych) wprost z interfejsu. Przy tworzeniu nowego prywatnego zdarzenia od razu ustalany jest jego typ (pierwszy argument) oraz specyficzne cechy ustawiane za pomocą opcjonalnego słownika CustomEventInit (drugi argument).
Składnia#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var new_customEvent = new CustomEvent(type [, customEventInitDict]);
gdzie poszczególne człony oznaczają:
new_customEvent- referencja do nowego prywatnego zdarzenia.type- typ prywatnego zdarzenia w postaci łańcucha znakowego. Może to być dowolny łańcuch znakowy (nawet pusty).customEventInitDict- opcjonalny obiekt określający szczegółowe kryteria inicjalizacji prywatnego zdarzenia. Oto dostępne właściwości dla obiektu:bubbles- boolowsketrueoznacza, że zdarzenie zezwala na obsługę fazy bąbelkowania. Domyślną wartością jest boolowskiefalse(dziedziczone z EventInit).cancelable- boolowsketrueoznacza, że domyślne akcje dla zdarzenia mogą zostać anulowane. Domyślną wartością jest boolowskiefalse(dziedziczone z EventInit).detail- prywatne dane dowolnego typu (np. liczba, łańcuch znakowy, obiekt itd.). Domyślną wartością jest wartośćnull.
Algorytm wywołania konstruktora new CustomEvent(type, customEventInitDict) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Zwróć nowe zdarzenie za pomocą algorytmu tworzenia zdarzenia z typem
typei słownikiemcustomEventInitDict(jeśli występuje).
Obiekt zwracany przez konstruktor new CustomEvent() implementuje interfejs CustomEvent, dlatego ma dostęp do wszystkich poleceń z tego interfejsu (oraz z kolejnych interfejsów w łańcuchu dziedziczenia). Warto podkreślić, że i opcjonalny słownik CustomEventInit dziedziczy ze słownika EventInit, dlatego ma dostęp do wszystkich jego członków w chwili przekazania do konstruktora.
Nowy obiekt prywatnego zdarzenia będzie miał ustawiane domyślne wartości dla wszystkich swoich właściwości i dodatkowo zostanie automatycznie zainicjowany zgodnie z przekazanymi argumentami przy jego wywołaniu, w przeciwieństwie do polecenia Document.createEvent(), dlatego może być od razu wysłany za pomocą metody EventTarget.dispatchEvent().
W ramach uzupełnienia warto przeanalizować wady i zalety poszczególnych poleceń odpowiedzialnych za tworzenie niezaufanych zdarzeń.
Ze względów bezpieczeństwa prywatne zdarzenia generowane przy użyciu konstruktora new CustomEvent() muszą ustawiać wartość właściwości Event.isTrusted na boolowskie false.
Prosty przykład:
<script>
// Tworzymy nowe prywatne zdarzenie
var customEvent1 = new CustomEvent("piesek");
document.write(customEvent1); // [object CustomEvent]
document.write("<br>");
document.write(customEvent1.type); // piesek
document.write("<br>");
document.write(customEvent1.bubbles); // false
document.write("<br>");
document.write(customEvent1.cancelable); // false
document.write("<br>");
document.write(customEvent1.detail); // null
document.write("<br>");
document.write(customEvent1.defaultPrevented); // false
document.write("<br>");
document.write(customEvent1.isTrusted); // false
document.write("<br>");
document.write(customEvent1.eventPhase); // 0
document.write("<br>");
document.write(customEvent1.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
document.write("<br>");
document.write(customEvent1.currentTarget); // null
document.write("<br>");
document.write(customEvent1.target); // null
document.write("<br><br>");
// Tworzymy kolejne prywatne zdarzenie
var customEvent2 = new CustomEvent("click", {
bubbles: true,
cancelable: true,
detail: "husky"
});
document.write(customEvent2); // [object CustomEvent]
document.write("<br>");
document.write(customEvent2.type); // click
document.write("<br>");
document.write(customEvent2.bubbles); // true
document.write("<br>");
document.write(customEvent2.cancelable); // true
document.write("<br>");
document.write(customEvent2.detail); // "husky"
document.write("<br>");
document.write(customEvent2.defaultPrevented); // false
document.write("<br>");
document.write(customEvent2.isTrusted); // false
document.write("<br>");
document.write(customEvent2.eventPhase); // 0
document.write("<br>");
document.write(customEvent2.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
document.write("<br>");
document.write(customEvent2.currentTarget); // null
document.write("<br>");
document.write(customEvent2.target); // null
</script>Na chwilę obecną wszystkie aktualne przeglądarki pozwalają na wywoływanie interfejsu CustomEvent w roli konstruktora, oczywiście z wyjątkiem IE11.
Interfejs Web IDL#
[Constructor(DOMString type, optional CustomEventInit customEventInitDict)], Exposed=(Window,Worker)]
interface CustomEvent : Event {
};
dictionary CustomEventInit : EventInit {
any detail = null;
};