CustomEvent#
CustomEvent.initCustomEvent()#
Metoda initCustomEvent() inicjuje dane prywatne zdarzenie wartościami przekazanymi do metody.
Składnia#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
customEvent.initCustomEvent(type, bubbles, cancelable, detail);
gdzie poszczególne człony oznaczają:
customEvent- prywatne zdarzenie będące obiektem kontekstu.type- typ prywatnego zdarzenia w postaci łańcucha znakowego. Może to być dowolny łańcuch znakowy (nawet pusty).bubbles- boolowsketrueoznacza, że prywatne zdarzenie zezwala na obsługę fazy bąbelkowania. Boolowskiefalsezabrania bąbelkowania.cancelable- boolowsketrueoznacza, że domyślne akcje dla prywatnego zdarzenia mogą zostać anulowane. Boolowskiefalsenie zezwala na przerywanie domyślnych akcji.detail- kontekstowe informacje dowolnego typu powiązane z prywatnym zdarzeniem.
Algorytm wywołania metody initCustomEvent(type, bubbles, cancelable, detail) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Wykonaj inicjowanie z typem
type, bąbelkowaniembubblesoraz anulowaniemcancelablena obiekcie kontekstu, a następnie ustaw jego właściwośćdetailnadetail.
Inicjowanie prywatnych zdarzeń metodą initCustomEvent() jest obowiązkowe w przypadku niezaufanych zdarzeń, przed ich wysłaniem za pomocą metody EventTarget.dispatchEvent(), które utworzone zostały za pomocą polecenia Document.createEvent(). Prywatne zdarzenia tworzone za pomocą konstruktora new CustomEvent(), i pochodnych, są inicjowane automatycznie. Także zaufane zdarzenia są inicjowane automatycznie przez daną implementacje.
W ramach uzupełnienia warto przeanalizować wady i zalety poszczególnych poleceń odpowiedzialnych za tworzenie niezaufanych zdarzeń.
Jeśli metoda initCustomEvent() jest wielokrotnie wywoływana przed wysłaniem prywatnego zdarzenia, to pod uwagę brane jest ostatnie takie wywołanie. Jeśli metoda initCustomEvent() zostanie wywołana w trakcie propagacji prywatnego zdarzenia (np. przez jakiś uchwyt zdarzenia), to nie powoduje ona żadnego efektu i musi zostać natychmiastowo zakończona.
Ze względów bezpieczeństwa prywatne zdarzenia modyfikowane przy użyciu metody initCustomEvent() muszą ustawiać wartość właściwości Event.isTrusted na boolowskie false.
Prosty przykład:
<script>
// Tworzymy nowe prywatne zdarzenie z domyślnymi wartościami
var customEvent = document.createEvent("CustomEvent");
document.write(customEvent); // [object CustomEvent]
document.write("<br>");
document.write(customEvent.type); // "" - pusty łańcuch
document.write("<br>");
document.write(customEvent.bubbles); // false
document.write("<br>");
document.write(customEvent.cancelable); // false
document.write("<br>");
document.write(customEvent.detail); // null
document.write("<br>");
document.write(customEvent.defaultPrevented); // false
document.write("<br>");
document.write(customEvent.isTrusted); // false
document.write("<br>");
document.write(customEvent.eventPhase); // 0
document.write("<br>");
document.write(customEvent.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
document.write("<br>");
document.write(customEvent.currentTarget); // null
document.write("<br>");
document.write(customEvent.target); // null
document.write("<br><br>");
customEvent.initCustomEvent("piesek", true, true, "husky"); // inicjujemy prywatne zdarzenie własnymi wartościami
document.write(customEvent); // [object CustomEvent]
document.write("<br>");
document.write(customEvent.type); // piesek
document.write("<br>");
document.write(customEvent.bubbles); // true
document.write("<br>");
document.write(customEvent.cancelable); // true
document.write("<br>");
document.write(customEvent.detail); // husky
document.write("<br>");
document.write(customEvent.defaultPrevented); // false
document.write("<br>");
document.write(customEvent.isTrusted); // false
document.write("<br>");
document.write(customEvent.eventPhase); // 0
document.write("<br>");
document.write(customEvent.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
document.write("<br>");
document.write(customEvent.currentTarget); // null
document.write("<br>");
document.write(customEvent.target); // null
</script>Metodę initCustomEvent() pozostawiono ze względu na polecenie Document.createEvent(). Warto nadmienić, że po zakończeniu obsługi wszystkich faz zdarzenia może ono zostać ponownie wysłane. Dzięki metodzie initCustomEvent() można zmienić jego podstawowe parametry (typ, bąbelkowanie, anulowanie i kontekstowe informacje), co byłoby niemożliwe przy wykorzystaniu podstawowych właściwości zdarzeń, ponieważ są one tylko do odczytu.
Interfejs Web IDL#
void initCustomEvent(DOMString type, boolean bubbles, boolean cancelable, any detail);