JavaScriptDOM i zdarzenia

EventTarget.dispatchEvent()

Wywołuje zdarzenie na elemencie z poziomu kodu. Razem z CustomEvent pozwala tworzyć własne zdarzenia z dodatkowymi danymi.

Zwraca: false, jeśli zdarzenie z cancelable: true zostało anulowane przez preventDefault(), w przeciwnym razie true.

Na tej stronie

Przykład
Definicja i zastosowanie
Składnia
Parametry
Więcej przykładów
Obsługa przeglądarek
Dobre praktyki
Powiązane hasła

Przykład

JavaScript

const finish = document.querySelector('#finish')
const points = document.querySelector('#points')

document.addEventListener('lesson:complete', (event) => {
  const total = Number(points.textContent) + event.detail.points
  points.textContent = total
  console.log(`${event.detail.title}: +${event.detail.points} pkt, razem ${total}`)
})

finish.addEventListener('click', () => {
  const event = new CustomEvent('lesson:complete', {
    bubbles: true,
    detail: { title: 'Pętle', points: 30 }
  })
  finish.dispatchEvent(event)
})

finish.click()

Konsola

Pętle: +30 pkt, razem 150

Przycisk ogłasza ukończenie lekcji, a licznik punktów nasłuchuje na document. Zdarzenie dociera tam dzięki bubbles: true. Każde kliknięcie w podglądzie doda kolejne 30 punktów.

Definicja i zastosowanie

Metoda dispatchEvent() wysyła przygotowany obiekt zdarzenia do elementu, a przeglądarka uruchamia wszystkie funkcje obsługi zarejestrowane dla tego typu. Dzieje się to synchronicznie: kod zapisany po dispatchEvent() wykona się dopiero wtedy, gdy wszystkie obsługi skończą działać.

Zdarzenie tworzysz konstruktorem, np. new Event("input"), new KeyboardEvent("keydown", { key: "Enter" }) albo new CustomEvent("nazwa", { detail }). CustomEvent służy do własnych zdarzeń: w polu detail przekażesz dowolne dane, np. liczbę zdobytych punktów. Dzięki temu jedna część aplikacji może ogłosić „ukończono lekcję”, a inne mogą na to zareagować, nie wiedząc nic o sobie nawzajem.

Utworzone w ten sposób zdarzenie domyślnie nie bąbelkuje do rodziców i nie da się go anulować. Zmieniają to opcje bubbles: true i cancelable: true. Metoda zwraca false, jeśli któraś obsługa wywołała preventDefault() na zdarzeniu z cancelable: true, a w przeciwnym razie true.

Zdarzenia wywołane z kodu mają event.isTrusted równe false. Zwykle nie uruchamiają też domyślnych działań przeglądarki: sztuczne keydown nie wpisze znaku do pola, a zdarzenie submit nie wyśle formularza. Do symulowania kliknięcia najprościej użyć element.click(), a do wysłania formularza form.requestSubmit().

Składnia

target.dispatchEvent(event)

new Event(type, options)
new CustomEvent(type, { detail, bubbles, cancelable })

Parametry

event
obiekt Event
Zdarzenie do wysłania, utworzone np. przez new Event() albo new CustomEvent().
type
napis (w konstruktorze)
Nazwa zdarzenia. Własne zdarzenia nazywaj tak, żeby nie kolidowały z wbudowanymi, np. "lesson:complete".
options
opcjonalny obiekt (w konstruktorze)
detail (dowolne dane, tylko w CustomEvent), bubbles i cancelable. Obie ostatnie mają domyślnie wartość false.

Parametr	Typ	Opis
event	obiekt Event	Zdarzenie do wysłania, utworzone np. przez `new Event()` albo `new CustomEvent()`.
type	napis (w konstruktorze)	Nazwa zdarzenia. Własne zdarzenia nazywaj tak, żeby nie kolidowały z wbudowanymi, np. `"lesson:complete"`.
options	opcjonalny obiekt (w konstruktorze)	`detail` (dowolne dane, tylko w `CustomEvent`), `bubbles` i `cancelable`. Obie ostatnie mają domyślnie wartość `false`.

Więcej przykładów

Wywołanie synchroniczne i isTrusted

JavaScript

const search = document.querySelector('#search')

search.addEventListener('input', (event) => {
  console.log('Szukam:', search.value, '| isTrusted:', event.isTrusted)
})

search.value = 'python'
console.log('Przed dispatchEvent()')
search.dispatchEvent(new Event('input'))
console.log('Po dispatchEvent()')

Konsola

Przed dispatchEvent()

Szukam: python | isTrusted: false

Po dispatchEvent()

Obsługa wykonuje się w trakcie dispatchEvent(), zanim kod pójdzie dalej. Gdy wpiszesz coś w pole w podglądzie, isTrusted będzie miało wartość true, bo zdarzenie wywoła użytkownik.

Anulowanie zdarzenia i wynik metody

JavaScript

const leave = document.querySelector('#leave')
let unsavedChanges = true

leave.addEventListener('lesson:leave', (event) => {
  if (unsavedChanges) event.preventDefault()
})

function tryLeave() {
  const allowed = leave.dispatchEvent(new CustomEvent('lesson:leave', { cancelable: true }))
  console.log(allowed ? 'Wychodzę z lekcji' : 'Najpierw zapisz zmiany')
}

tryLeave()
unsavedChanges = false
tryLeave()

Konsola

Najpierw zapisz zmiany

Wychodzę z lekcji

Bez bubbles rodzic nie usłyszy zdarzenia

JavaScript

const list = document.querySelector('#list')
const item = document.querySelector('#item')

list.addEventListener('task:done', () => console.log('Lista: zadanie ukończone'))

item.dispatchEvent(new CustomEvent('task:done'))
console.log('Bez bubbles lista nic nie wypisała')

item.dispatchEvent(new CustomEvent('task:done', { bubbles: true }))

Konsola

Bez bubbles lista nic nie wypisała

Lista: zadanie ukończone

Obsługa przeglądarek

Szeroko dostępne

Działa we wszystkich nowoczesnych przeglądarkach, także na telefonach. Możesz używać bez obaw.

Chrome
Edge
Firefox
Safari

Dobre praktyki

Nazwy własnych zdarzeń pisz małymi literami, z przedrostkiem, np. "cart:add". Unikniesz kolizji z wbudowanymi zdarzeniami przeglądarki.
Jeśli zdarzenie ma dotrzeć do rodziców (np. do obsługi na document), ustaw bubbles: true. Domyślnie trafia tylko do elementu, na którym je wywołano.
Dane przekazuj w polu detail obiektu CustomEvent. Dopisywanie własnych właściwości do zwykłego Event jest mniej czytelne.

Powiązane hasła

Widzisz błąd albo brakuje przykładu? Napisz do nas.

Darmowy kursPrzećwicz JavaScript w kursie JavaScript i ReactZadania z podpowiedziami, edytor kodu i postępy zapisywane na bieżąco.Zobacz kurs