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