SyntheticEvent

В этом справочном руководстве описана обёртка 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

Примечание:

Начиная с версии 0.14, возврат false из обработчика событий больше не останавливает всплытие. Вместо этого нужно вручную вызывать e.stopPropagation() или e.preventDefault().

Пул событий

События SyntheticEvent содержатся в пуле. Это означает, что объект SyntheticEvent будет повторно использован, а все его свойства будут очищены после вызова обработчика события. Это необходимо из соображений производительности. Именно поэтому нельзя использовать синтетические события асинхронно.

function onClick(event) {
  console.log(event); // => null-объект.
  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 нормализует события так, чтобы они содержали одинаковые свойства во всех браузерах.

Обработчики ниже вызываются на фазе всплытия (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

События формы

Названия событий:

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

Свойства:

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