합성 이벤트(SyntheticEvent)

이 문서는 React의 이벤트 시스템 일부를 구성하는 SyntheticEvent 래퍼를 설명합니다. 더 많은 정보는 이벤트 처리하기 문서를 보세요.

개요

이벤트 핸들러는 모든 브라우저에서 이벤트를 동일하게 처리하기 위한 이벤트 래퍼 SyntheticEvent 객체를 전달받습니다. stopPropagation()preventDefault()를 포함해서 인터페이스는 브라우저의 고유 이벤트와 같지만 모든 브라우저에서 동일하게 동작합니다.

브라우저의 고유 이벤트가 필요하다면 nativeEvent 어트리뷰트를 참조하세요. 모든 합성 이벤트 객체는 다음 어트리뷰트를 가집니다.

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

주의

0.14 버전부터 이벤트 핸들러가 false를 반환하더라도 이벤트 전파를 멈추지 않습니다. 대신 e.stopPropagation() 또는 e.preventDefault()를 필요할 때 호출하세요.

이벤트 풀링

SyntheticEvent풀링됩니다. 성능상의 이유로 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);

  // 동작하지 않습니다. this.state.clickEvent 은 null만 가지게 될 것입니다.
  this.setState({clickEvent: event});

  // 이벤트 속성을 추출할 수 있습니다.
  this.setState({eventType: event.type});
}

주의

비동기적으로 이벤트 속성을 참조하고 싶다면 이벤트 객체의 event.persist() 를 호출하세요. 합성 이벤트 풀에서 제거되고 사용자의 코드에서 참조가 가능해집니다.

지원하는 이벤트

React는 이벤트들을 다른 브라우저에서도 같은 속성을 가지도록 표준화합니다.

다음 이벤트 핸들러는 이벤트 버블링 단계에서 호출됩니다. 캡처 단계에 이벤트 핸들러를 등록하기 위해서는 이벤트 이름에 Capture를 덧붙이세요. 예를 들어 onClick 대신 onClickCapture를 사용해서 캡처 단계에서 클릭 이벤트 핸들러를 사용할 수 있습니다.


참조

Clipboard 이벤트

이벤트 이름

onCopy onCut onPaste

속성

DOMDataTransfer clipboardData

Composition 이벤트

이벤트 이름

onCompositionEnd onCompositionStart onCompositionUpdate

속성

string data

Keyboard 이벤트

이벤트 이름

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 레벨 3 이벤트 명세에 있는 어떤 값이든 가질 수 있습니다.


Focus 이벤트

이벤트 이름

onFocus onBlur

포커스 이벤트는 form 엘리먼트 뿐만이 아니라 모든 React DOM 엘리먼트에 작동합니다.

속성

DOMEventTarget relatedTarget

Form 이벤트

이벤트 이름

onChange onInput onInvalid onSubmit

onChange 이벤트에 대한 더 자세한 정보는 폼 문서를 참조하세요.


Mouse 이벤트

이벤트 이름

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

onMouseEnteronMouseLeave 이벤트는 일반적인 버블링 대신 마우스가 떠나는 엘리먼트에서 들어가는 엘리먼트로 전파되고 캡처 단계가 없습니다.

속성

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 이벤트

이벤트 이름

onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture
onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut

onPointerEnteronPointerLeave 이벤트는 일반적인 버블링 대신 포인터가 떠나는 엘리먼트에서 들어가는 엘리먼트로 전파되고 캡처 단계가 없습니다.

속성

W3 명세에 정의된 대로 포인터 이벤트는 마우스 이벤트와 다음 속성을 포함해 확장합니다.

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가 직접 브라우저 호환성을 위해 폴리필을 제공하진 않습니다.

애플리케이션이 포인터 이벤트를 의존한다면 직접 서드 파티 포인터 폴리필을 추가하세요.


Selection 이벤트

이벤트 이름

onSelect

Touch 이벤트

이벤트 이름

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

Wheel 이벤트

이벤트 이름

onWheel

속성

number deltaMode
number deltaX
number deltaY
number deltaZ

Media 이벤트

이벤트 이름

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

Image 이벤트

이벤트 이름

onLoad onError

Animation 이벤트

이벤트 이름

onAnimationStart onAnimationEnd onAnimationIteration

속성

string animationName
string pseudoElement
float elapsedTime

Transition 이벤트

이벤트 이름

onTransitionEnd

속성

string propertyName
string pseudoElement
float elapsedTime

기타 이벤트

이벤트 이름

onToggle