EventTarget#

EventTarget.dispatchEvent()#

Metoda dispatchEvent() wysyła konkretne zdarzenie (syntetyczne) do danego celu zdarzenia. Metoda zwraca także boolowską wartość false jeśli domyślne akcje dla zdarzenia zostały odwołane w czasie propagacji zdarzenia, w przeciwnym razie zwrócona zostanie wartość true.

Składnia#

Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
var prevented = eventTarget.dispatchEvent(event);

gdzie poszczególne człony oznaczają:

Algorytm wywołania metody dispatchEvent(event) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:

  1. Jeśli flaga wysłania dla event jest ustawiona lub flaga inicjalizacji dla event nie jest ustawiona, to zrzuć wyjątek "InvalidStateError".
  2. Ustaw atrybut isTrusted w event na boolowską wartość false.
  3. Wyślij event i zwróć wartość zwracaną przez ten algorytm.

Przed wysłaniem niezaufanych zdarzeń za pomocą metody dispatchEvent(), które utworzone zostały przy użyciu polecenia Document.createEvent(), należy je najpierw zainicjować. Zdarzenia tworzone za pomocą konstruktora new Event(), i pochodnych, są inicjowane automatycznie. Także zaufane zdarzenia są inicjowane automatycznie przez daną implementacje.

Ze względów bezpieczeństwa zdarzenia wysyłane przy użyciu metody dispatchEvent() muszą ustawiać wartość właściwości Event.isTrusted na boolowskie false.

Warto nadmienić, że po zakończeniu obsługi wszystkich faz zdarzenia może ono zostać ponownie wysłane. W razie konieczności obiekt zdarzenia można przeinicjować, czyli jeszcze raz ustawić jego kluczowe parametry, takie jak typ, bąbelkowanie lub anulowanie.

Prosty przykład:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
<script>

	// Tworzymy nowe syntetyczne zdarzenie
	var event = new CustomEvent("piesek", {"detail": "husky"});

	// Podpinamy uchwyt zdarzenia dla naszego syntetycznego zdarzenia
	window.addEventListener("piesek", function(e) {

		document.write(event); // [object CustomEvent]
		document.write("<br>");
		document.write(event.type); // piesek
		document.write("<br>");
		document.write(event.bubbles); // false
		document.write("<br>");
		document.write(event.cancelable); // false
		document.write("<br>");
		document.write(event.detail); // husky
		document.write("<br>");
		document.write(event.defaultPrevented); // false
		document.write("<br>");
		document.write(event.isTrusted); // false
		document.write("<br>");
		document.write(event.eventPhase); // 1
		document.write("<br>");
		document.write(event.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
		document.write("<br>");
		document.write(event.currentTarget); // [object Window]
		document.write("<br>");
		document.write(event.target); // [object HTMLDocument]

	}, true);

	// Wysyłamy syntetyczne zdarzenie z poziomu aplikacji
	var return_value = document.dispatchEvent(event);

	// Po upływie 2 s odczytujemy wartość zwracaną przez metodę dispatchEvent
	setTimeout(function(){

		document.body.innerHTML += "<br><br>" + return_value; // true

	}, 2000);

</script>

W przykładzie widać wyraźnie, że wysyłanie syntetycznych zdarzeń (nawet prywatnych) za pomocą metody dispatchEvent() spełnia wszystkie założenia mechanizmu przepływu zdarzeń DOM. Możemy tworzyć i wysyłać zdarzenia wprost z aplikacji do dowolnego obiektu (celu), a następnie przechwytywać je w konkretnej fazie propagacji zdarzenia za pomocą uchwytów zdarzeń.

Interfejs Web IDL#

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
boolean dispatchEvent(Event event);

Specyfikacje i inne materiały#

Pasek społecznościowy

SPIS TREŚCI AKTUALNEJ STRONY

EventTarget (H1) EventTarget.dispatchEvent() (H2) Składnia (H3) Interfejs Web IDL (H3) Specyfikacje i inne materiały (H3)