Синтетический событие

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

Примечание:

Начиная с версии v17, e.persist() ничего не делает, потому что SyntheticEvent больше не пулируется.

Примечание:

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

Поддерживаемые события

React нормализует события, чтобы их свойства были согласованы в разных браузерах.

Обработчики событий ниже срабатывают при событии на фазе распространения. Для регистрации обработчика события на фазе захвата добавьте Capture к имени события; например, вместо использования onClick, вы бы использовали onClickCapture для обработки события клика на фазе захвата.

• События буфера обмена
• События составления
• События клавиатуры
• События фокуса
• События форм
• Общие события
• События мыши
• События указателя
• События выделения
• События касания
• События интерфейса
• События колесика
• События медиа
• События изображений
• События анимации
• События перехода
• Другие события

Справочник

События буфера обмена

Имена событий:

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 уровня 3 .

События фокуса

Имена событий:

onFocus onBlur

Эти события фокуса работают со всеми элементами в React DOM, а не только с элементами форм.

Свойства:

DOMEventTarget relatedTarget

onFocus

Событие 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."
    />
  )
}

Обнаружение входа и выхода из фокуса

Вы можете использовать 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>
  );
}

События форм

Имена событий:

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

События интерфейса

Имена событий:

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