SyntheticEvent

Aquesta guia de referència documenta el contenidor SyntheticEvent que forma part del sistema d’esdeveniments de React. Consulta la guia Controlant esdeveniments per aprendre’n més.

Resum

Als teus gestors d’esdeveniments se li passaran instàncies de SyntheticEvent, un contenidor compatible amb diversos navegadors que conté l’esdeveniment natiu del navegador. Té la mateixa interfície que l’esdeveniment natiu del navegador, incloent stopPropagation() i preventDefault(), excepte que els esdeveniments funcionen de forma idèntica a tots els navegadors.

Si creus que necessites l’esdeveniment natiu del navegador per alguna raó, només cal que facis servir l’atribut nativeEvent per obtenir-lo. Els esdeveniments sintètics són diferents dels esdeveniments natius del navegador i no es corresponen directament. Per exemple a onMouseLeave event.nativeEvent apuntarà a un esdeveniment mouseout. La relació específica no és part de l’API pública i pot canviar en qualsevol moment. Cada objecte SyntheticEvent té els següents atributs:

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

Nota:

A partir de la v17, e.persist() no fa res perquè SyntheticEvent ja no està pooled.

Nota:

A partir de la v0.14, retornar false des d’un gestor d’esdeveniments ja no atura la propagació d’esdeveniments. Per tant, e.stopPropagation() o e.preventionDefault() s’han d’activar manualment, segons correspongui.

Esdeveniments suportats

React normalitza els esdeveniments perquè les seves propietats siguin coherents entre els diferents tipus de navegadors.

Els gestors d’esdeveniments que segueixen a continuació els desencadena un esdeveniment en la seva fase de propagació. Per registrar un gestor d’esdeveniments que es desencadeni a la fase de captura, cal afegir Capture al nom de l’esdeveniment; per exemple, en lloc d’utilitzar onClick, utilitzaríem onClickCapture per gestionar l’esdeveniment de clic a la fase de captura.

Esdeveniments de Porta-retalls
Esdeveniments de Composició
Esdeveniments de Teclat
Esdeveniments d’Enfocament
Esdeveniments de Formulari
Esdeveniments Genèrics
Esdeveniments de Ratolí
Esdeveniments de Punter
Esdeveniments de Selecció
Esdeveniments Tàctils
Esdeveniments de UI
Esdeveniments de Roda del Ratolí
Esdeveniments de Multimèdia
Esdeveniments d’Imatge
Esdeveniments d’Animació
Esdeveniments de Transició
Altres Esdeveniments

Referència

Esdeveniments de Porta-retalls

Nom dels esdeveniments:

onCopy onCut onPaste

Propietats:

DOMDataTransfer clipboardData

Esdeveniments de Composició

Nom dels esdeveniments:

onCompositionEnd onCompositionStart onCompositionUpdate

Propietats:

string data

Esdeveniments de Teclat

Nom dels esdeveniments:

onKeyDown onKeyPress onKeyUp

Propietats:

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

La propietat key pot prendre qualsevol dels valors documentats en l’especificació Esdeveniments del DOM de nivell 3 (en anglès).

Esdeveniments d’Enfocament

Nom dels esdeveniments:

onFocus onBlur

Aquests esdeveniments d’enfocament funcionen a tots els elements del DOM de React, no només als elements de formulari.

Propietats:

DOMEventTarget relatedTarget

onFocus

The onFocus event is called when the element (or some element inside of it) receives focus. For example, it’s called when the user clicks on a text input.

function Example() {
  return (
    <input
      onFocus={(e) => {
        console.log('Focused on input');
      }}
      placeholder="onFocus is triggered when you click this input."
    />
  )
}

onBlur

The onBlur event handler is called when focus has left the element (or left some element inside of it). For example, it’s called when the user clicks outside of a focused text input.

function Example() {
  return (
    <input
      onBlur={(e) => {
        console.log('Triggered because this input lost focus');
      }}
      placeholder="onBlur is triggered when you click this input and then you click outside of it."
    />
  )
}

Detecting Focus Entering and Leaving

You can use the currentTarget and relatedTarget to differentiate if the focusing or blurring events originated from outside of the parent element. Here is a demo you can copy and paste that shows how to detect focusing a child, focusing the element itself, and focus entering or leaving the whole subtree.

function Example() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused self');
        } else {
          console.log('focused child', e.target);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus entered self');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused self');
        } else {
          console.log('unfocused child', e.target);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus left self');
        }
      }}
    >
      <input id="1" />
      <input id="2" />
    </div>
  );
}

Esdeveniments de Formulari

Nom dels esdeveniments:

onChange onInput onInvalid onReset onSubmit

Per a més informació sobre l’esdeveniment onChange, consulta els Formularis.

Esdeveniments Genèrics

Nom dels esdeveniments:

onError onLoad

Esdeveniments de Ratolí

Nom dels esdeveniments:

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

Els esdeveniments onMouseEnter i onMouseLeave es propaguen des de l’element que es deixa fins a l’element on s’entra en lloc de fer la propagació normal i no tenen fase de captura.

Propietats:

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

Esdeveniments de Punter

Nom dels esdeveniments:

onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture
onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut

Els esdeveniments onPointerEnter i onPointerLeave es propaguen des de l’element que es deixa fins a l’element on s’entra en lloc de fer la propagació normal i no tenen una fase de captura.

Propietats:

Tal com es defineix a W3 spec (en anglès), els esdeveniments del punter amplien els Esdeveniments de Ratolí amb les següents propietats:

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

Una nota sobre la compatibilitat amb els diversos navegadors:

Els esdeveniments de punter encara no són compatibles en tots els navegadors (en el moment d’escriure aquest article, els navegadors compatibles són: Chrome, Firefox, Edge i Internet Explorer). React deliberadament no és compatible amb la resta de navegadors perquè un polyfill estàndard augmentaria significativament la mida del paquet react-dom.

Si la vostra aplicació requereix esdeveniments de punter, recomanem afegir un polyfill d’esdeveniments d’un altre proveïdor.

Esdeveniments de Selecció

Nom dels esdeveniments:

onSelect

Esdeveniments Tàctils

Nom dels esdeveniments:

onTouchCancel onTouchEnd onTouchMove onTouchStart

Propietats:

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

Esdeveniments de UI

Nom dels esdeveniments:

onScroll

Nota

Començant amb React 17, l’esdveniment onScroll no es propaga a React. Això funciona igual que en navegador i evita la confusió quan elements embolcallats inicien esdveniments a un parent distant.

Propietats:

number detail
DOMAbstractView view

Esdeveniments de Roda de Ratolí

Nom dels esdeveniments:

onWheel

Propietats:

number deltaMode
number deltaX
number deltaY
number deltaZ

Esdeveniments de Multimèdia

Nom dels esdeveniments:

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

Esdeveniments d’Imatge

Nom dels esdeveniments:

onLoad onError

Esdeveniments d’Animació

Nom dels esdeveniments:

onAnimationStart onAnimationEnd onAnimationIteration

Propietats:

string animationName
string pseudoElement
float elapsedTime

Esdeveniments de Transició

Nom dels esdeveniments:

onTransitionEnd

Propietats:

string propertyName
string pseudoElement
float elapsedTime

Altres Esdeveniments

Nom dels esdeveniments:

onToggle

Is this page useful?Edit this page