SyntheticEvent

Poniższa dokumentacja dotyczy SyntheticEvent (pol. zdarzenie syntetyczne) - klasy opakowującej zdarzenia, będącej częścią systemu obsługi zdarzeń Reacta. Samej obsłudze zdarzeń w Reakcie poświęciliśmy osobny rozdział.

Informacje ogólne

Napisane przez ciebie procedury obsługi zdarzeń będą otrzymywać jako argument instancję SyntheticEvent - klasy opakowującej natywne zdarzenie, niezależnej od przeglądarki. Posiada ona taki sam interfejs jak natywne zdarzenia, wliczając w to metody stopPropagation() oraz preventDefault(), gwarantuje jednak identyczne działanie na wszystkich przeglądarkach.

Jeśli w którymś momencie zechcesz skorzystać z opakowanego, natywnego zdarzenia, możesz odwołać się do niego poprzez właściwość nativeEvent. Każdy obiekt klasy SyntheticEvent posiada następujące właściwości:

boolean bubbles
boolean cancelable
DOMEventTarget currentTarget
boolean defaultPrevented
number eventPhase
boolean isTrusted
DOMEvent nativeEvent
void preventDefault()
boolean isDefaultPrevented()
void stopPropagation()
boolean isPropagationStopped()
DOMEventTarget target
number timeStamp
string type

Uwaga:

Od wersji v0.14 wzwyż, zwracanie wartości false przez procedurę obsługi nie zatrzymuje propagacji zdarzenia. Zamiast tego należy ręcznie wywoływać odpowiednią metodę: e.stopPropagation() lub e.preventDefault().

Pula zdarzeń

Obiekty SyntheticEvent są przechowywane w puli. Oznacza to, że są one używane wielokrotnie, a ich właściwości są czyszczone zaraz po wywołaniu procedury obsługi zdarzenia. Ma to pozytywny wpływ na szybkość działania aplikacji. Przez to jednak nie można odczytywać stanu zdarzenia w sposób asynchroniczny.

function onClick(event) {
  console.log(event); // => wyczyszczony obiekt.
  console.log(event.type); // => "click"
  const eventType = event.type; // => "click"

  setTimeout(function() {
    console.log(event.type); // => null
    console.log(eventType); // => "click"
  }, 0);

  // Nie zadziała. Obiekt this.state.clickEvent będzie zawierał same wartości null.
  this.setState({clickEvent: event});

  // Możesz jednak przekazywać poszczególne właściwości zdarzenia.
  this.setState({eventType: event.type});
}

Uwaga:

Jeśli chcesz odczytać właściwości zdarzenia w sposób asynchroniczny, wywołaj jego metodę event.persist(). Zdarzenie to zostanie wyciągnięte z puli zdarzeń, co pozwoli na zachowanie referencji do późniejszego użytku w kodzie.

Obsługiwane zdarzenia

React normalizuje zdarzenia, tak by ich właściwości były jednakowe w różnych przeglądarkach.

Przedstawione na liście poniżej procedury obsługi zdarzeń są wywoływane przez zdarzenie w fazie bąbelkowania (ang. bubbling phase). Aby zarejestrować procedurę obsługi w fazie przechwytywania (ang. capturing phase), dodaj na końcu nazwy Capture, np. zamiast onClick użyj onClickCapture.


Dokumentacja

Obsługa schowka

Nazwy zdarzeń:

onCopy onCut onPaste

Właściwości:

DOMDataTransfer clipboardData

Obsługa kompozycji

Nazwy zdarzeń:

onCompositionEnd onCompositionStart onCompositionUpdate

Właściwości:

string data

Obsługa klawiatury

Nazwy zdarzeń:

onKeyDown onKeyPress onKeyUp

Właściwości:

boolean altKey
number charCode
boolean ctrlKey
boolean getModifierState(key)
string key
number keyCode
string locale
number location
boolean metaKey
boolean repeat
boolean shiftKey
number which

Właściwość key przyjmuje dowolną z wartości wymienionych w specyfikacji Zdarzeń DOM 3. Poziomu.


Obsługa skupiania

Nazwy zdarzeń:

onFocus onBlur

Powyższe zdarzenia działają na wszystkich elementach w React DOM, nie tylko na kontrolkach formularza.

Właściwości:

DOMEventTarget relatedTarget

Obsługa formularzy

Nazwy zdarzeń:

onChange onInput onInvalid onSubmit

Więcej informacji odnośnie zdarzenia onChange opisaliśmy w rozdziale pt. “Formularze”.


Obsługa myszy

Nazwy zdarzeń:

onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit
onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
onMouseMove onMouseOut onMouseOver onMouseUp

Zdarzenia onMouseEnter oraz onMouseLeave, zamiast zwykłego bąbelkowania, propagowane są z elementu opuszczanego do elementu wskazywanego, a ponadto nie mają fazy przechwytywania (ang. capture phase).

Właściwości:

boolean altKey
number button
number buttons
number clientX
number clientY
boolean ctrlKey
boolean getModifierState(key)
boolean metaKey
number pageX
number pageY
DOMEventTarget relatedTarget
number screenX
number screenY
boolean shiftKey

Obsługa wskaźnika

Nazwy zdarzeń:

onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture
onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut

Zdarzenia onPointerEnter oraz onPointerLeave, zamiast zwykłego bąbelkowania, propagowane są z elementu opuszczanego do elementu wskazywanego, a ponadto nie mają fazy przechwytywania (ang. capture phase).

Właściwości:

Zgodnie ze specyfikacją W3, zdarzenia wskaźnika rozszerzają zdarzenia obsługi myszy o następujące właściwości:

number pointerId
number width
number height
number pressure
number tangentialPressure
number tiltX
number tiltY
number twist
string pointerType
boolean isPrimary

Informacja o kompatybilności z przeglądarkami:

Zdarzenia wskaźnika nie są jeszcze obsługiwane przez wszystkie przeglądarki (w chwili pisania tego artykułu wspierają je: Chrome, Firefox, Edge i Internet Explorer). React celowo nie dostarcza łatki (ang. polyfill) dla pozostałych przeglądarek, ponieważ łatka zgodna ze standardem znacząco zwiększyłaby rozmiar paczki react-dom.

Jeśli twoja aplikacja wymaga obsługi wskaźników, zalecamy dołączenie odpowiedniej paczki zewnętrznej.


Obsługa zaznaczania

Nazwy zdarzeń:

onSelect

Obsługa dotyku

Nazwy zdarzeń:

onTouchCancel onTouchEnd onTouchMove onTouchStart

Właściwości:

boolean altKey
DOMTouchList changedTouches
boolean ctrlKey
boolean getModifierState(key)
boolean metaKey
boolean shiftKey
DOMTouchList targetTouches
DOMTouchList touches

Obsługa interfejsu użytkownika

Nazwy zdarzeń:

onScroll

Właściwości:

number detail
DOMAbstractView view

Obsługa pokrętła myszy

Nazwy zdarzeń:

onWheel

Właściwości:

number deltaMode
number deltaX
number deltaY
number deltaZ

Obsługa mediów

Nazwy zdarzeń:

onAbort onCanPlay onCanPlayThrough onDurationChange onEmptied onEncrypted
onEnded onError onLoadedData onLoadedMetadata onLoadStart onPause onPlay
onPlaying onProgress onRateChange onSeeked onSeeking onStalled onSuspend
onTimeUpdate onVolumeChange onWaiting

Obsługa obrazów

Nazwy zdarzeń:

onLoad onError

Obsługa animacji

Nazwy zdarzeń:

onAnimationStart onAnimationEnd onAnimationIteration

Właściwości:

string animationName
string pseudoElement
float elapsedTime

Obsługa tranzycji

Nazwy zdarzeń:

onTransitionEnd

Właściwości:

string propertyName
string pseudoElement
float elapsedTime

Inne zdarzenia

Nazwy zdarzeń:

onToggle