合成イベント (SyntheticEvent)
この記事は古くなっており、今後更新されません。新しい React 日本語ドキュメントである ja.react.dev をご利用ください。
以下の新しいドキュメントで最新の React の使い方がライブサンプル付きで学べます。
このリファレンスガイドでは、React のイベントシステムの一部を構成する SyntheticEvent（合成イベント）ラッパについて説明します。詳細については、イベント処理ガイドを参照してください。
概要
イベントハンドラには、SyntheticEvent のインスタンスが渡されます。これはブラウザのネイティブイベントに対するクロスブラウザ版のラッパです。stopPropagation() と preventDefault() を含む、ブラウザのネイティブイベントと同じインターフェイスを持ちつつ、ブラウザ間で同じ挙動をするようになっています。
何らかの理由で実際のブラウザイベントが必要な場合は、単に nativeEvent 属性を使用するだけで取得できます。合成イベントはブラウザのネイティブイベントとは別物であり、直接の対応があるわけでもありません。例えば onMouseLeave イベントの場合、event.nativeEvent は mouseout イベントになっています。個々の対応については公開 API の範疇ではなく、常に変わる可能性があります。すべての SyntheticEvent オブジェクトは以下の属性を持っています。
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補足
v17 以降、
SyntheticEventはプーリングされなくなったため、e.persist()は何も行わなくなります。
補足
v0.14 以降、イベントハンドラから
falseを返してもイベントの伝播は止まりません。代わりに、e.stopPropagation()またはe.preventDefault()を手動で呼び出す必要があります。
サポートするイベント
React は異なるブラウザ間でも一貫したプロパティを持つようにイベントを正規化します。
以下のイベントハンドラはイベント伝搬のバブリングフェーズで呼び出されます。キャプチャフェーズのイベントハンドラを登録するには、イベント名に Capture を追加します。たとえば、キャプチャフェーズでクリックイベントを処理するには onClick の代わりに onClickCapture を使用します。
- クリップボードイベント
- コンポジションイベント
- キーボードイベント
- フォーカスイベント
- フォームイベント
- 汎用イベント
- マウスイベント
- ポインタイベント
- 選択イベント
- タッチイベント
- UI イベント
- ホイールイベント
- メディアイベント
- 画像イベント
- アニメーションイベント
- 遷移イベント
- その他のイベント
リファレンス
クリップボードイベント
イベント名：
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 whichkey プロパティは DOM Level 3 Events spec に記載されている任意の値を取ることができます。
フォーカスイベント
イベント名：
onFocus onBlurこれらのフォーカスイベントは、フォーム要素だけでなくすべての React DOM 要素で動作します。
プロパティ：
DOMEventTarget relatedTargetonFocus
onFocus イベントは要素（あるいはその内部の別の要素）がフォーカスを受け取った時に呼び出されます。例えば、ユーザがテキスト入力をクリックした際に呼び出されます。
function Example() {
return (
<input
onFocus={(e) => {
console.log('Focused on input');
}}
placeholder="onFocus is triggered when you click this input."
/>
)
}onBlur
onBlur イベントハンドラは要素（あるいはその内部の別の要素）からフォーカスが外れた場合に呼び出されます。例えば、ユーザが既にフォーカスされているテキスト入力の外側でクリックした場合に呼び出されます。
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."
/>
)
}フォーカスが当たった・外れたことの検出
currentTarget と relatedTarget を用いることで、フォーカスが当たった・外れた際のイベントが親要素の外側で起こったかどうかを判定できます。以下のコピー・ペーストで使えるデモでは、子要素のどれかへのフォーカス、要素自身へのフォーカス、サブツリー全体から出入りするフォーカスを、それぞれどのように検出するかを示しています。
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>
);
}フォームイベント
イベント名：
onChange onInput onInvalid onReset onSubmit onChange イベントの詳細については、Forms を参照してください。
汎用イベント
イベント名：
onError onLoadマウスイベント
イベント名：
onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit
onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
onMouseMove onMouseOut onMouseOver onMouseUponMouseEnter と onMouseLeave イベントは通常のバブリングとは異なり、（ポインタが）出て行った要素から入ってきた要素に伝播し、キャプチャフェーズを持ちません。
プロパティ：
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 onPointerOutonPointerEnter と onPointerLeave イベントは通常のバブリングとは異なり、（ポインタが）出て行った要素から入ってきた要素に伝播し、キャプチャフェーズを持ちません。
プロパティ：
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-dom のバンドルサイズを大幅に増加させるため、React は意図的にその他ブラウザのためのポリフィルを提供しません。
アプリケーションでポインタイベントが必要な場合は、サードパーティのポインタイベントポリフィルを追加することをお勧めします。
選択イベント
イベント名：
onSelectタッチイベント
イベント名：
onTouchCancel onTouchEnd onTouchMove onTouchStartプロパティ：
boolean altKey
DOMTouchList changedTouches
boolean ctrlKey
boolean getModifierState(key)
boolean metaKey
boolean shiftKey
DOMTouchList targetTouches
DOMTouchList touchesUI イベント
イベント名：
onScroll補足
React 17 以降、
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