SyntheticEvent

這份參考指南紀錄了 SyntheticEvent 這個形成 React 事件系統的 wrapper。想了解更多,請參考事件處理

概觀

你的 event handler 將會是 SyntheticEvent 被傳遞的 instance,它是一個跨瀏覽器的、瀏覽器原生事件的 wrapper。它和瀏覽器原生事件有相同的介面,包含 stopPropagation()preventDefault(),除了原生事件在所有的瀏覽器都以相同的方式運作這點以外。

如果你發現因為某些原因你需要使用瀏覽器的底層事件,你只需要使用 nativeEvent 這個 attribute 即可。每個 SyntheticEvent object 都有下列的 attribute:

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

注意:

截至 v0.14 為止,從 event handler 回傳 false 並不會停止事件冒泡(event propagation)。因此你可以選擇是情況手寫觸發 e.stopPropagation()e.preventDefault()

事件結合

SyntheticEvent 是透過結合事件而來的。這表示 SyntheticEvent 這個 object 會被重複使用,且所有的屬性都會在事件的 callback 被呼叫後變成無效。 這是出於效能考量。 因此,你不能用非同步的方式讀取這些事件:

function onClick(event) {
  console.log(event); // => 無效的 object。
  console.log(event.type); // => "click"
  const eventType = event.type; // => "click"

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

  // 不會產生任何作用,this.state.clickEvent 只會包含 null
  this.setState({clickEvent: event});

  // 你仍可以導出事件屬性
  this.setState({eventType: event.type});
}

注意:

如果你想要用非同步的方式讀取這些事件,你應該在該事件上呼叫 event.persist()。此方法將會把該合成事件從事件組合中移出,並允許使用者程式保留對該事件的引用。

支援的事件

React 將事件規格化,已讓它們在不同的瀏覽器中有ㄧ致的屬性。

以下的 event handler 會在冒泡階段時被一個事件觸發。如果你想註冊捕獲階段的 event handler,請在事件名稱的後面加上 Capture。例如,假設你想在捕獲階段捕捉 click 事件的話,你需要用 onClickCapture 而不是 onClick


參考

剪貼板事件

事件名稱:

onCopy onCut onPaste

屬性:

DOMDataTransfer clipboardData

組合事件

事件名稱:

onCompositionEnd onCompositionStart onCompositionUpdate

屬性:

string data

鍵盤事件

事件名稱:

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 內記錄的任意值。


焦點事件

事件名稱:

onFocus onBlur

這些焦點事件在 React DOM 中所有的 element 上都可以使用,不限於表單 element。

屬性:

DOMEventTarget relatedTarget

表單事件

事件名稱:

onChange onInput onInvalid onReset onSubmit

想了解關於 onChange 事件的資訊,請參考表單


Generic 事件

事件名稱:

onError onLoad

滑鼠事件

事件名稱:

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

onMouseEnteronMouseLeave 事件從離開的 element 向正在進入的 element 傳播,而不是正常的冒泡,也沒有捕獲階段。

屬性:

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

指標事件

事件名稱:

onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture
onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut

onPointerEnteronPointerLeave 事件從離開的 element 向正在進入的 element 傳播,而不是正常的冒泡,也沒有捕獲階段。

屬性:

如同在 W3 spec 內定義的,指標事件是滑鼠事件的延伸,並帶有以下屬性:

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

關於跨瀏覽器支援的說明:

目前為止,並非所有的瀏覽器都支援指標事件(在這篇文章撰寫的時候,支援該事件的瀏覽器有:Chrome、Firefox、Edge 以及 Internet Explorer)。React 刻意不通過 polyfill 的方式支援其他瀏覽器,因為符合標準的 polyfill 會明顯地增加 react-dom 的 bundle 大小。

如果你的應用程式需要指標事件,我們建議你加上第三方的指針事件 polyfill。


選擇事件

事件名稱:

onSelect

觸摸事件

事件名稱:

onTouchCancel onTouchEnd onTouchMove onTouchStart

屬性:

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

UI 事件

事件名稱:

onScroll

屬性:

number detail
DOMAbstractView view

滾輪事件

事件名稱:

onWheel

屬性:

number deltaMode
number deltaX
number deltaY
number deltaZ

媒體事件

事件名稱:

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

圖片事件

事件名稱:

onLoad onError

動畫事件

事件名稱:

onAnimationStart onAnimationEnd onAnimationIteration

屬性:

string animationName
string pseudoElement
float elapsedTime

過渡事件

事件名稱:

onTransitionEnd

屬性:

string propertyName
string pseudoElement
float elapsedTime

其他事件

事件名稱:

onToggle