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:

Common components (e.g. <div>)

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

Is this page useful?Отредактировать эту страницу