합성 이벤트(SyntheticEvent)
These docs are old and won’t be updated. Go to react.dev for the new React docs.
These new documentation pages teach modern React and include live examples:
이 문서는 React의 이벤트 시스템 일부를 구성하는 SyntheticEvent 래퍼를 설명합니다. 더 많은 정보는 이벤트 처리하기 문서를 보세요.
개요
이벤트 핸들러는 모든 브라우저에서 이벤트를 동일하게 처리하기 위한 이벤트 래퍼 SyntheticEvent 객체를 전달받습니다. stopPropagation() 와 preventDefault()를 포함해서 인터페이스는 브라우저의 고유 이벤트와 같지만 모든 브라우저에서 동일하게 동작합니다.
브라우저의 고유 이벤트가 필요하다면 nativeEvent 어트리뷰트를 참조하세요. 합성 이벤트는 브라우저 고유 이벤트에 직접 대응되지 않으며 다릅니다. 예를 들어 onMouseLeave에서 event.nativeEvent는 mouseout 이벤트를 가리킵니다. 구체적인 연결은 공개된 API의 일부가 아니며 언제든지 변경될 수 있습니다. 모든 합성 이벤트 객체는 다음 어트리뷰트를 가집니다.
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부터
e.persist()는SyntheticEvent가 더 이상 풀링되지 않기 때문에 아무런 동작을 하지 않습니다.
주의
v0.14부터 이벤트 핸들러에서
false가 반환되더라도 이벤트 전파가 더 이상 중지되지 않습니다. 대신e.stopPropagation()또는e.preventDefault()를 적절하게 수동으로 호출해야 합니다.
지원하는 이벤트
React는 이벤트들을 다른 브라우저에서도 같은 속성을 가지도록 표준화합니다.
다음 이벤트 핸들러는 이벤트 버블링 단계에서 호출됩니다. 캡처 단계에 이벤트 핸들러를 등록하기 위해서는 이벤트 이름에 Capture를 덧붙이세요. 예를 들어 onClick 대신 onClickCapture를 사용해서 캡처 단계에서 클릭 이벤트 핸들러를 사용할 수 있습니다.
- Clipboard 이벤트
- Composition 이벤트
- Keyboard 이벤트
- Focus 이벤트
- Form 이벤트
- Generic 이벤트
- Mouse 이벤트
- Pointer 이벤트
- Selection 이벤트
- Touch 이벤트
- UI 이벤트
- Wheel 이벤트
- Media 이벤트
- Image 이벤트
- Animation 이벤트
- Transition 이벤트
- 기타 이벤트
참조
Clipboard 이벤트
이벤트 이름
onCopy onCut onPaste속성
DOMDataTransfer clipboardDataComposition 이벤트
이벤트 이름
onCompositionEnd onCompositionStart onCompositionUpdate속성
string dataKeyboard 이벤트
이벤트 이름
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 레벨 3 이벤트 명세에 있는 어떤 값이든 가질 수 있습니다.
Focus 이벤트
이벤트 이름
onFocus onBlur포커스 이벤트는 form 엘리먼트 뿐만이 아니라 모든 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." /> ) }Detecting Focus Entering and Leaving
부모 엘리먼트 바깥 영역으로부터 발생한 이벤트가 포커스 또는 블러중인지 구분하기 위해 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> ); }Form 이벤트
이벤트 이름
onChange onInput onInvalid onReset onSubmitonChange 이벤트에 대한 더 자세한 정보는 폼 문서를 참조하세요.
Generic 이벤트
이벤트 이름
onError onLoadMouse 이벤트
이벤트 이름
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 shiftKeyPointer 이벤트
이벤트 이름
onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOutonPointerEnter 및 onPointerLeave 이벤트는 일반적인 버블링 대신 포인터가 떠나는 엘리먼트에서 들어가는 엘리먼트로 전파되고 캡처 단계가 없습니다.
속성
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 이벤트
이벤트 이름
onSelectTouch 이벤트
이벤트 이름
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 viewWheel 이벤트
이벤트 이름
onWheel속성
number deltaMode number deltaX number deltaY number deltaZMedia 이벤트
이벤트 이름
onAbort onCanPlay onCanPlayThrough onDurationChange onEmptied onEncrypted onEnded onError onLoadedData onLoadedMetadata onLoadStart onPause onPlay onPlaying onProgress onRateChange onSeeked onSeeking onStalled onSuspend onTimeUpdate onVolumeChange onWaitingImage 이벤트
이벤트 이름
onLoad onErrorAnimation 이벤트
이벤트 이름
onAnimationStart onAnimationEnd onAnimationIteration속성
string animationName string pseudoElement float elapsedTimeTransition 이벤트
이벤트 이름
onTransitionEnd속성
string propertyName string pseudoElement float elapsedTime기타 이벤트
이벤트 이름
onToggle