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:
В этом справочном руководстве описана обёртка SyntheticEvent
, которая является частью системы событий React. Смотрите руководство Обработка событий для детальной информации.
Обзор
Ваши обработчики событий получают экземпляр 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
Примечание:
Начиная с 17 версии, вызов
e.persist()
не имеет смысла, потому что объекты событийSyntheticEvent
больше не добавляются в пул.
Примечание:
Начиная с версии v0.14, возврат
false
из обработчика события больше не приведёт к прекращению всплытия события. Вместо этого, следует вручную вызыватьe.stopPropagation()
илиe.preventDefault()
, если это требуется.
Поддерживаемые события
React нормализует события так, чтобы они содержали одинаковые свойства во всех браузерах.
Обработчики ниже вызываются на фазе всплытия (bubbling). А чтобы зарегистрировать событие на фазе перехвата (capture), просто добавьте 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 which
Свойство key
может содержать любое из документированных значений в спецификации событий DOM третьего уровня.
События фокуса
Названия событий:
onFocus onBlur
Эти события фокуса работают не только на элементах формы, но и на всех остальных элементах в React DOM.
Свойства:
DOMEventTarget relatedTarget
onFocus
Событие onFocus
вызывается при перемещении фокуса на элемент (включая дочерние элементы внутри него). Например, это событие запустится, если пользователь кликнет на текстовое поле ввода.
function Example() {
return (
<input
onFocus={(e) => {
console.log('Получен фокус на поле ввода');
}}
placeholder="onFocus выполнится при нажатии на это поле ввода."
/>
)
}
onBlur
Событие onBlur
вызывается при пропадании фокуса с элемента (включая дочерние элементы внутри него). Например, это событие запустится, если пользователь кликнет за пределы текстового поля ввода, находящегося в фокусе.
function Example() {
return (
<input
onBlur={(e) => {
console.log('Пропал фокус с поля ввода');
}}
placeholder="onBlur выполнится в случае изменения фокуса с этого поля ввода на любой другой элемент."
/>
)
}
Отслеживание получения и перемещения фокуса
Можно использовать свойства currentTarget
и relatedTarget
, чтобы определить, когда наступили события появления или исчезновения фокуса за пределами родительского элемента. Ниже приводится пример для выполнения в песочнице, который показывает, как можно поймать состояние фокуса на родительском и дочернем элементах, а также отследить фокус на всём поддереве элементов.
function Example() {
return (
<div
tabIndex={1}
onFocus={(e) => {
if (e.currentTarget === e.target) {
console.log('фокус на родительском элементе установлен');
} else {
console.log('фокус на дочернем элементе установлен', e.target);
}
if (!e.currentTarget.contains(e.relatedTarget)) {
// Не срабатывает при перемещении фокуса между дочерними элементами
console.log('фокус находится внутри родительского элемента');
}
}}
onBlur={(e) => {
if (e.currentTarget === e.target) {
console.log('фокус на родительском элементе снят');
} else {
console.log('фокус на дочернем элементе снят', e.target);
}
if (!e.currentTarget.contains(e.relatedTarget)) {
// Не срабатывает при перемещении фокуса между дочерними элементами
console.log('фокус потерян изнутри родительского элемента');
}
}}
>
<input id="1" />
<input id="2" />
</div>
);
}
События формы
Названия событий:
onChange onInput onInvalid onReset onSubmit
Больше информации о событии onChange тут — Формы.
Общие события
Названия событий:
onError onLoad
События мыши
Названия событий:
onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit
onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
onMouseMove onMouseOut onMouseOver onMouseUp
События onMouseEnter
и 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 onPointerOut
События onPointerEnter
и 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 сознательно не добавляет полифил для поддержки в других браузерах, потому что это значительно бы увеличило размер пакета react-dom
.
Если вашему приложению нужны события указателя, мы рекомендуем использовать сторонний полифил.
События выбора
Названия событий:
onSelect
Сенсорные события
Названия событий:
onTouchCancel onTouchEnd onTouchMove onTouchStart
Свойства:
boolean altKey
DOMTouchList changedTouches
boolean ctrlKey
boolean getModifierState(key)
boolean metaKey
boolean shiftKey
DOMTouchList targetTouches
DOMTouchList touches
События UI
Названия событий:
onScroll
Примечание
Начиная с React 17, событие
onScroll
не всплывает в React. Это согласуется с работой браузера и предотвращает путаницу, когда вложенный прокручиваемый элемент запускает события на родительском элементе.
Свойства:
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