[译]合成事件对象

前言

本文为意译，翻译过程当中掺杂本人的理解，若有误导，请放弃继续阅读。

原文地址:SyntheticEvent

简介

这是一份关于SyntheticEvent wrapper的文档。SyntheticEvent wrapper是什么？能够这么说，react的合成事件系统是由（React’s Event SystemSyn）一个个的SyntheticEvent wrapper组成的。而SyntheticEvent wrapper有时候又简称为SyntheticEvent，中文翻译为合成事件对象。要想了解更多?请参考如何应用合成事件对象。

概览

在run time中，你的react事件处理器将会被传入一个SyntheticEvent实例对象做为实参。SyntheticEvent是一个对浏览器原生事件对象（native event）进行跨浏览器封装的wrapper。它与浏览器的原生事件对象有着一样的接口，好比，它也包括了stopPropagation()和preventDefault()这两个方法。它的目的是使得事件对象在不一样的浏览器上都表现一致，提高开发者的开发体验。

若是你发现，你由于某种缘由须要使用到浏览器原生的事件对象，那么你能够简单地经过读取SyntheticEvent对象的nativeEvent属性来访问它。像下面那样：

class SomeComponent extends React.Component {
    handleClick=(e)=> {
        const nativeEvent = e.nativeEvent;
        console.log(nativeEvent)
    }
    render(){
        return <button onClick={this.handleClick}>click me</button>
    }
}
复制代码

每个SyntheticEvent实例对象都包含了如下属性：

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
复制代码

注意： 自v0.14版本起，在一个事件处理器中返回false，已是没法阻止事件的传播了。你须要手动地调用e.stopPropagation()或者e.preventDefault()方法才行。

事件对象的共享机制（Event Pooling）

pooling,在这里我意译为“共享”。由于react的事件系统中，1) 同一个事件类型下的全部事件处理器都是共享同一个SyntheticEvent实例对象; 2) 在不手动持久化的前提下，同一个事件处理器在不一样的调用次序中都是共享同一个SyntheticEvent实例对象。基于上述的事实，我以为把它翻译为“共享”较为贴切。这个翻译参考了剑桥英语词典对该单词的释义。也有人把它翻译为“池化”，我不知道哪一个扑街带头这么干的，详见知乎吐槽。

SyntheticEvent实例对象是共享的。这意味着SyntheticEvent实例对象是会被反复使用的，而且会在事件处理器被调用以后回收。所谓的回收，就是对该对象的全部属性值置为空值（will be nullified ），以便于在下一轮事件传播中使用。之因此采用这种机制，是为了提高react的运行性能。因此说，你不能使用异步的方式来访问SyntheticEvent实例对象的属性值。

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

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

  // will not work. this.state.clickEvent will only contain null values.
  this.setState({clickEvent: event});

  // You can still export event properties.
  this.setState({eventType: event.type});
}
复制代码

上面的setTimeout虽然是写在的事件处理器里面，可是它终究是异步代码。上面代码的实际执行流程是：同步代码 --> SyntheticEvent对象(属性)置空值 --> 异步代码。由于异步代码老是在置空值的后面才执行，因此，咱们访问到的老是空值。

注意： 若是你想在异步代码里面访问SyntheticEvent对象的属性。那么你应该手动调用event.persist(),你一旦这么作了，react就会把这个SyntheticEvent对象从共享池中去掉。这样子，用户就能够放心地去访问这个被从共享池中解放出来的SyntheticEvent对象了。

支持的事件

React对合成事件对象作了统一化，使得在不一样的浏览器上对象所支持的属性都是一致的。

若是你想把一个事件处理器绑定在捕获阶段（capture phase），那么你就须要在该事件名后面追加一个Capture：例如，若是你想把点击事件的事件处理器绑定在事件的捕获阶段，那么在事件注册时，你应该写onClickCapture，而不是onClick。

如下都是一些在事件冒泡阶段触发（bubbling phase）的事件。

• Clipboard Events
• Composition Events
• Keyboard Events
• Focus Events
• Form Events
• Mouse Events
• Pointer Events
• Touch Events
• UI Events
• Wheel Events
• Media Events
• Animation Events
• Transiton Events
• Other Events

参考指南

Clipboard Events

事件名：

onCopy
onCut
onPaste
复制代码

属性：

DOMDataTransfer clipboardData
复制代码

composition Events

The DOM CompositionEvent represents events that occur due to the user indirectly entering text. --- MDN

事件名：

onCompositionStart
onCompositionUpdate
onCompositionEnd
复制代码

属性：

string data
复制代码

keyboard Events

事件名：

onKeyDown
onKeyPress
onKeyUp
复制代码

属性：

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
复制代码

key的属性值的取值为任意DOM Level 3 Events spec所指定的值。

Focus Events

事件名：

onFocus
onBlue
复制代码

属性：

DOMEventTarget relatedTarget
复制代码

注意：不一样于浏览器原生的focus事件只会在form元素上触发，这个合成的focus事件会在全部的React DOM元素上触发

Form Events

事件名：

onChange
onInput
onInvalid
onSubmit
复制代码

更多关于onChange事件的信息，详见Forms。

Mouse Events

事件名：

onClick
onDoubleClick
onDrag
onDragEnd
onDragEnter
onDragExit
onDragLeave
onDragOver
onDragStart
onDrop
onMouseDown
onMouseEnter
onMouseLeave
onMouseMove
onMouseOut
onMouseOver
onMouseUp
onContextMenu
onInvalid
onSubmit
复制代码

The onMouseEnter and onMouseLeave events propagate from the element being left to the one being entered instead of ordinary bubbling and do not have a capture phase.(这段话意思难懂)。

属性名：

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
复制代码

Pointer Events

Pointer应该是在HTML5增长的事件，具体见MDN。

事件名：

onPointerDown
onPointerMove
onPointerUp
onPointerCancel
onGotPointerCapture
onLostPointerCapture
onPointerEnter
onPointerLeave
onPointerOver
onPointerOut
复制代码

The onPointerEnter and onPointerLeave events propagate from the element being left to the one being entered instead of ordinary bubbling and do not have a capture phase.（again）

属性：

如W3C规范所规定的那样，pointer事件继承自Mouse Events,而且多出了如下如下属性：

number pointerId
number width
number height
number pressure
number tangentialPressure
number tiltX
number tiltY
number twist
string pointerType
boolean isPrimary
复制代码

在跨浏览器支持方面的一个提示：

Pointer events are not yet supported in every browser (at the time of writing this article, supported browsers include: Chrome, Firefox, Edge, and Internet Explorer). React之因此故意不对其余不支持的浏览器添加相应的polyfill，那是由于一个符合标准的（standard-conform）的polyfill会大大地增长react-dom的文件大小。

若是你的应用中须要用到pointer事件，那么咱们会建议你单独引入一个第三方的pointer事件的polyfill。

selection Events

事件名：

onSelect
复制代码

Touch Events

事件名：

onTouchStart
onTouchMove
onTouchCancel
onTouchEnd
复制代码

属性：

boolean altKey
DOMTouchList changedTouches
boolean ctrlKey
boolean getModifierState(key)
boolean metaKey
boolean shiftKey
DOMTouchList targetTouches
DOMTouchList touches
复制代码

UI Events

事件名：

onScroll
复制代码

属性：

number detail
DOMAbstractView view
复制代码

Wheel Events

事件名：

onWheel
复制代码

属性：

number deltaMode
number deltaX
number deltaY
number deltaZ
复制代码

Media Events

事件名：

onAbort
onCanPlay
onCanPlayThrough
onDurationChange // 播放时长的改变事件
onEmptied // https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/emptied_event
onEncrypted // 多媒体加密事件
onEnded
onError
onLoadedData
onLoadedMetadata
onLoadStart
onPause
onPlay
onPlaying
onProgress
onRateChange
onSeeked
onSeeking
onStalled // stalled的意思是“停滞不前的”
onSuspend
onTimeUpdate
onVolumeChange
onWaiting
复制代码

Image Events

事件名：

onLoad
onError
复制代码

Animation Events

事件名：

onAnimationStart
onAnimationEnd
onAnimationIteration // 在一次动画迭代结束的时候触发
复制代码

属性名：

string animationName
string pseudoElement
float elapsedTime
复制代码

Transition Events

事件名：

onTransitionEnd
复制代码

属性名：

string propertyName
string pseudoElement
float elapsedTime
复制代码

其余事件

事件名：

onToggle
复制代码