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. Syntetyczne zdarzenia różnią się od natywnych zdarzeń przeglądarki i można ich stosować wymiennie. Na przykład, w zdarzeniu onMouseLeave wartość event.nativeEvent będzie wskazywać na zdarzenie mouseout. Specyfikacja mapowania nie jest dostępna publicznie i może ulec zmianie w dowolnym momencie. 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()
void persist()
DOMEventTarget target
number timeStamp
string type

Uwaga:

Od wersji 17, wywołanie metody e.persist() nie robi nic, ponieważ SyntheticEvent nie jest już współdzielony w puli.

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().

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.

• Obsługa schowka
• Obsługa kompozycji
• Obsługa klawiatury
• Obsługa skupiania
• Obsługa formularzy
• Obsługa zdarzeń generycznych
• Obsługa myszy
• Obsługa wskaźnika
• Obsługa zaznaczania
• Obsługa dotyku
• Obsługa interfejsu użytkownika
• Obsługa pokrętła myszy
• Obsługa mediów
• Obsługa obrazów
• Obsługa animacji
• Obsługa tranzycji
• Inne zdarzenia

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

onFocus

Zdarzenie onFocus jest wywoływane, gdy element (lub któryś z zagnieżdżonych elementów) otrzymuje fokus. Przykładowo, zostanie ono wywołane, gdy użytkownik kliknie na polu tekstowym.

function Example() {
  return (
    <input
      onFocus={(e) => {
        console.log('Fokus jest na polu tekstowym');
      }}
      placeholder="onFocus zostanie wywołane po kliknięciu na tym polu."
    />
  )
}

onBlur

Zdarzenie onBlur jest wywołane, gdy element (lub któryś z zagnieżdżonych elementów) stracił fokus. Przykładowo, zostanie ono wywołane, gdy użytkownik kliknie gdzieś poza polem tekstowym.

function Example() {
  return (
    <input
      onBlur={(e) => {
        console.log('Wywołano, bo pole straciło fokus');
      }}
      placeholder="onBlur zostanie wywołane, gdy klikniesz na tym polu, a następnie klikniesz poza nim."
    />
  )
}

Wykrywanie fokusa i jego utraty

Aby rozróżnić, czy zdarzenia dotyczące fokusa pochodzą spoza rodzica, możesz sprawdzić wartości pól currentTarget i relatedTarget. Poniżej znajdziesz kod, który pokazuje, jak wykryć fokus na elemencie potomnym, jak na samym elemencie, a jak wykryć taki, który dotyczy całego poddrzewa elementów.

function Example() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('fokus na sobie');
        } else {
          console.log('fokus na elemencie potomnym', e.target);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus aktywny poza poddrzewem');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('fokus utracony na sobie');
        } else {
          console.log('fokus utracony na elemencie potomnym', e.target);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('fokus poza poddrzewem');
        }
      }}
    >
      <input id="1" />
      <input id="2" />
    </div>
  );
}

Obsługa formularzy

Nazwy zdarzeń:

onChange onInput onInvalid onReset onSubmit 

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

Obsługa zdarzeń generycznych

Nazwy zdarzeń:

onError onLoad

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

Uwaga:

Podcząwszy od Reacta 17, zdarzenie onScroll nie jest propagowane w górę. Odpowiada to zachowaniu przeglądarki i pozwala uniknąć niejasności, gdy to zagnieżdżony element z suwakiem generował zdarzenia na odległych rodzicach.

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