Общие компоненты (например, <div>)

• Справочник
  • Общие компоненты (например, <div>)
  • ref функция обратного вызова
  • Объект события React
  • AnimationEvent функция обработчика
  • ClipboardEvent функция обработчика
  • CompositionEvent функция обработчика
  • DragEvent функция обработчика
  • FocusEvent функция обработчика
  • Event функция обработчика
  • InputEvent функция обработчика
  • KeyboardEvent функция обработчика
  • MouseEvent функция обработчика
  • PointerEvent функция обработчика
  • TouchEvent функция обработчика
  • TransitionEvent функция обработчика
  • UIEvent функция обработчика
  • WheelEvent функция обработчика
• Использование
  • Применение стилей CSS
  • Обработка узла DOM с помощью ref
  • Опасное изменение внутреннего HTML
  • Обработка событий мыши
  • Обработка событий указателя
  • Обработка событий фокуса
  • Обработка событий клавиатуры

Справочник

Общие компоненты (например, <div>)

<div className="wrapper">Some content</div>

См. дополнительные примеры ниже.

Свойства

Для всех встроенных компонентов поддерживаются эти специальные свойства React:

• children: Узел React (элемент, строка, число, портал, пустой узел, например, null, undefined и булевы значения, или массив других узлов React). Определяет содержимое внутри компонента. Когда вы используете JSX, вы обычно неявно указываете свойство children путём вложения тегов, как <div><span /></div>.

• dangerouslySetInnerHTML: Объект вида { __html: '<p>some html</p>' } со строкой HTML внутри. Переопределяет свойство innerHTML узла DOM и отображает переданный HTML внутри. Использовать следует с большой осторожностью! Если HTML недоверен (например, если он основан на данных пользователя), вы рискуете ввести уязвимость XSS. Подробнее об использовании dangerouslySetInnerHTML.

• ref: Объект ref из useRef или createRef, или функция обратного вызова ref, или строка для legacy refs. Ваш ref будет заполнен элементом DOM для этого узла. Подробнее об обработке DOM с помощью ref.

• suppressContentEditableWarning: Булевое значение. Если true, подавляет предупреждение React для элементов, у которых одновременно есть children и contentEditable={true} (которые обычно не работают вместе). Используйте это, если вы разрабатываете библиотеку текстового ввода, которая вручную управляет содержимым contentEditable.

• suppressHydrationWarning: Булевое значение. Если вы используете рендеринг на сервере, обычно появляется предупреждение, когда сервер и клиент рендерят разное содержимое. В некоторых редких случаях (например, со временем), гарантировать точное совпадение очень сложно или невозможно. Если вы установите suppressHydrationWarning в true, React не будет предупреждать вас о несоответствиях в атрибутах и содержимом этого элемента. Работает только на один уровень вглубь и предназначен для использования в исключительных случаях. Не злоупотребляйте им. Подробнее о подавлении ошибок несоответствия при гидратации.

• style: Объект со стилями CSS, например { fontWeight: 'bold', margin: 20 }. Аналогично свойству DOM style, имена свойств CSS должны записываться как camelCase, например fontWeight вместо font-weight. Вы можете передавать строки или числа в качестве значений. Если вы передаёте число, например, width: 100, React автоматически добавит px («пиксели») к значению, если это не безусловное свойство. Мы рекомендуем использовать style только для динамических стилей, где вы не знаете значения стилей заранее. В других случаях применение обычных CSS-классов с className более эффективно. Подробнее о className и style.

Также поддерживаются стандартные свойства DOM для всех встроенных компонентов:

• accessKey: Строка. Указывает сочетание клавиш для элемента. Не рекомендуется в общем случае.
• aria-*: Атрибуты ARIA позволяют указать информацию о дереве доступности для данного элемента. См. атрибуты ARIA для полного справочника. В React все имена атрибутов ARIA полностью совпадают с именами в HTML.
• autoCapitalize: Строка. Указывает, как следует производить автоматическое приведение ввода пользователя к верхнему регистру.
• className: Строка. Указывает имя класса CSS элемента. Подробнее об применении стилей CSS.
• contentEditable: Булево значение. Если true, браузер позволяет пользователю редактировать рендеренный элемент напрямую. Это используется для реализации библиотек ввода форматированного текста, таких как Lexical. React предупреждает, если вы пытаетесь передать React-дочерние элементы элементу с contentEditable={true}, поскольку React не сможет обновить его содержимое после редактирования пользователем.
• data-*: Атрибуты данных позволяют прикрепить данные в виде строк к элементу, например, data-fruit="banana". В React они используются нечасто, так как обычно данные считываются из свойств (props) или состояния (state).
• dir: Либо 'ltr', либо 'rtl'. Указывает направление текста элемента.
• draggable: Булево значение. Указывает, может ли элемент быть перетаскиваемым. Часть API перетаскивания и опускания HTML.
• enterKeyHint: Строка. Указывает действие, которое должно быть представлено для клавиши Enter на виртуальной клавиатуре.
• htmlFor: Строка. Для <label> и <output>, позволяет связать метку с некоторым элементом управления. То же, что и for атрибут HTML. React использует стандартные имена свойств DOM (htmlFor) вместо имен атрибутов HTML.
• hidden: Булево значение или строка. Указывает, следует ли скрывать элемент.
• id: Строка. Указывает уникальный идентификатор для данного элемента, который может быть использован для его поиска позже или для связи с другими элементами. Генерируйте его с помощью useId, чтобы избежать конфликтов между несколькими экземплярами одного и того же компонента.
• is: Строка. Если задано, компонент будет вести себя как пользовательский элемент.
• inputMode: Строка. Указывает, какой тип клавиатуры отобразить (например, текст, число или телефон).
• itemProp: Строка. Указывает, какую свойство элемент представляет для структурированных данных.
• lang: Строка. Указывает язык элемента.
• onAnimationEnd: Функция-обработчик AnimationEvent. Срабатывает, когда анимация CSS завершается.
• onAnimationEndCapture: Версия onAnimationEnd , которая срабатывает в фазе захвата.
• onAnimationIteration: Функция-обработчик AnimationEvent. Срабатывает, когда итерация анимации CSS заканчивается, и начинается следующая.
• onAnimationIterationCapture: Версия onAnimationIteration , которая срабатывает в фазе захвата.
• onAnimationStart: Функция-обработчик AnimationEvent. Срабатывает, когда начинается анимация CSS.
• onAnimationStartCapture: onAnimationStart, но срабатывает в фазе захвата.
• onAuxClick: Функция-обработчик MouseEvent. Срабатывает при нажатии на дополнительную кнопку указателя.
• onAuxClickCapture: Версия onAuxClick , которая срабатывает в фазе захвата.
• onBeforeInput: Функция-обработчик InputEvent. Срабатывает перед изменением значения редактируемого элемента. React пока не использует родное событие beforeinput, а вместо этого пытается реализовать его с помощью других событий.
• onBeforeInputCapture: Версия onBeforeInput , которая срабатывает в фазе захвата.
• onBlur: Функция-обработчик FocusEvent. Срабатывает, когда элемент теряет фокус. В отличие от встроенного браузерного события blur, в React событие onBlur просачивается.
• onBlurCapture: Версия onBlur , которая срабатывает в фазе захвата.
• onClick: Функция-обработчик MouseEvent. Срабатывает, когда на устройстве ввода была нажата главная кнопка.
• onClickCapture: Версия onClick , которая срабатывает в фазе захвата.
• onCompositionStart: Функция-обработчик CompositionEvent. Срабатывает, когда редактор ввода начинает новую сессию составления текста.
• onCompositionStartCapture: Версия onCompositionStart , которая срабатывает в фазе захвата.
• onCompositionEnd: Функция-обработчик CompositionEvent. Срабатывает, когда редактор ввода завершает или отменяет сессию составления текста.
• onCompositionEndCapture: Версия onCompositionEnd , которая срабатывает в фазе захвата.
• onCompositionUpdate: Функция-обработчик CompositionEvent. Срабатывает, когда редактор ввода получает новый символ.
• onCompositionUpdateCapture: Версия onCompositionUpdate , которая срабатывает в фазе захвата.

• onContextMenu: Функция-обработчик MouseEvent. Срабатывает, когда пользователь пытается открыть контекстное меню.
• onContextMenuCapture: Вариант onContextMenu, который срабатывает на стадии захвата.
• onCopy: Функция-обработчик ClipboardEvent. Срабатывает, когда пользователь пытается скопировать что-либо в буфер обмена.
• onCopyCapture: Вариант onCopy, который срабатывает на стадии захвата.
• onCut: Функция-обработчик ClipboardEvent. Срабатывает, когда пользователь пытается вырезать что-либо в буфер обмена.
• onCutCapture: Вариант onCut, который срабатывает на стадии захвата.
• onDoubleClick: Функция-обработчик MouseEvent. Срабатывает при двойном щелчке. Соответствует событию браузера dblclick.
• onDoubleClickCapture: Вариант onDoubleClick, который срабатывает на стадии захвата.
• onDrag: Функция-обработчик DragEvent. Срабатывает во время перетаскивания пользователем чего-либо.
• onDragCapture: Вариант onDrag, который срабатывает на стадии захвата.
• onDragEnd: Функция-обработчик DragEvent. Срабатывает, когда пользователь прекращает перетаскивание чего-либо.
• onDragEndCapture: Вариант onDragEnd, который срабатывает на стадии захвата.
• onDragEnter: Функция-обработчик DragEvent. Срабатывает, когда перетаскиваемое содержимое попадает на допустимую область назначения.
• onDragEnterCapture: Вариант onDragEnter, который срабатывает на стадии захвата.
• onDragOver: Функция-обработчик DragEvent. Срабатывает на допустимой области назначения, пока перетаскиваемое содержимое находится над ней. Вам необходимо вызвать e.preventDefault() здесь, чтобы разрешить сброс.
• onDragOverCapture: Вариант onDragOver, который срабатывает на стадии захвата.
• onDragStart: Функция-обработчик DragEvent. Срабатывает, когда пользователь начинает перетаскивание элемента.
• onDragStartCapture: Вариант onDragStart, который срабатывает на стадии захвата.
• onDrop: Функция-обработчик DragEvent. Срабатывает, когда что-либо отпускается на допустимой области назначения.
• onDropCapture: Вариант onDrop, который срабатывает на стадии захвата.
• onFocus: Функция-обработчик FocusEvent. Срабатывает, когда элемент получает фокус. В отличие от встроенного события браузера focus, в React событие onFocus распространяется вверх.
• onFocusCapture: Вариант onFocus, который срабатывает на стадии захвата.
• onGotPointerCapture: Функция-обработчик PointerEvent. Срабатывает, когда элемент программно захватывает указатель.
• onGotPointerCaptureCapture: Вариант onGotPointerCapture, который срабатывает на стадии захвата.
• onKeyDown: Функция-обработчик KeyboardEvent. Срабатывает при нажатии клавиши.
• onKeyDownCapture: Вариант onKeyDown, который срабатывает на стадии захвата.
• onKeyPress: Функция-обработчик KeyboardEvent. Устаревшая. Используйте onKeyDown или onBeforeInput вместо этого.
• onKeyPressCapture: Вариант onKeyPress, который срабатывает на стадии захвата.
• onKeyUp: Функция-обработчик KeyboardEvent. Срабатывает при отпускании клавиши.
• onKeyUpCapture: Вариант onKeyUp, который срабатывает на стадии захвата.
• onLostPointerCapture: Функция-обработчик PointerEvent. Срабатывает, когда элемент прекращает захват указателя.
• onLostPointerCaptureCapture: Вариант onLostPointerCapture, который срабатывает на стадии захвата.
• onMouseDown: Функция-обработчик MouseEvent. Срабатывает при нажатии указателя.
• onMouseDownCapture: Вариант onMouseDown, который срабатывает на стадии захвата.
• onMouseEnter: Функция-обработчик MouseEvent. Срабатывает, когда указатель перемещается внутрь элемента. Не имеет стадии захвата. Вместо этого, onMouseLeave и onMouseEnter распространяются от элемента, который покидается, к элементу, в который входит.
• onMouseLeave: Функция-обработчик MouseEvent. Срабатывает, когда указатель перемещается за пределы элемента. Не имеет стадии захвата. Вместо этого, onMouseLeave и onMouseEnter распространяются от элемента, который покидается, к элементу, в который входит.
• onMouseMove: Функция-обработчик MouseEvent. Срабатывает, когда координаты указателя меняются.
• onMouseMoveCapture: Вариант onMouseMove, который срабатывает на стадии захвата.
• onMouseOut: Функция-обработчик MouseEvent. Срабатывает, когда указатель перемещается за пределы элемента или перемещается в дочерний элемент.
• onMouseOutCapture: Вариант onMouseOut, который срабатывает на стадии захвата.
• onMouseUp: Функция-обработчик MouseEvent. Срабатывает при отпускании указателя.
• onMouseUpCapture: Вариант onMouseUp, который срабатывает на стадии захвата.
• onPointerCancel: Функция-обработчик PointerEvent. Срабатывает, когда браузер отменяет взаимодействие с указателем.
• onPointerCancelCapture: Вариант onPointerCancel, который срабатывает на стадии захвата.
• onPointerDown: Функция-обработчик PointerEvent. Срабатывает, когда указатель становится активным.

• onPointerDownCapture: A version of onPointerDown that fires in the фазе захвата.
• onPointerEnter: A обработчик PointerEvent function. Срабатывает, когда указатель перемещается внутрь элемента. Не имеет фазы захвата. Вместо этого onPointerLeave и onPointerEnter распространяются от элемента, из которого уходит указатель, к элементу, в который он входит.
• onPointerLeave: A обработчик PointerEvent function. Срабатывает, когда указатель перемещается за пределы элемента. Не имеет фазы захвата. Вместо этого onPointerLeave и onPointerEnter распространяются от элемента, из которого уходит указатель, к элементу, в который он входит.
• onPointerMove: A обработчик PointerEvent function. Срабатывает, когда координаты указателя меняются.
• onPointerMoveCapture: A version of onPointerMove that fires in the фазе захвата.
• onPointerOut: A обработчик PointerEvent function. Срабатывает, когда указатель перемещается за пределы элемента, если взаимодействие с указателем отменено и по ряду других причин.
• onPointerOutCapture: A version of onPointerOut that fires in the фазе захвата.
• onPointerUp: A обработчик PointerEvent function. Срабатывает, когда указатель больше не активен.
• onPointerUpCapture: A version of onPointerUp that fires in the фазе захвата.
• onPaste: A обработчик ClipboardEvent function. Срабатывает, когда пользователь пытается вставить что-то из буфера обмена.
• onPasteCapture: A version of onPaste that fires in the фазе захвата.
• onScroll: An обработчик Event function. Срабатывает, когда элемент был прокручен. Это событие не распространяется.
• onScrollCapture: A version of onScroll that fires in the фазе захвата.
• onSelect: An обработчик Event function. Срабатывает после изменения выделения внутри изменяемого элемента, например, input. React расширяет событие onSelect для работы и с элементами contentEditable={true}. Кроме того, React расширяет его, чтобы срабатывать при пустом выделении и при редактировании (что может повлиять на выделение).
• onSelectCapture: A version of onSelect that fires in the фазе захвата.
• onTouchCancel: A обработчик TouchEvent function. Срабатывает, когда браузер отменяет взаимодействие с касанием.
• onTouchCancelCapture: A version of onTouchCancel that fires in the фазе захвата.
• onTouchEnd: A обработчик TouchEvent function. Срабатывает, когда одна или несколько точек касания удалены.
• onTouchEndCapture: A version of onTouchEnd that fires in the фазе захвата.
• onTouchMove: A обработчик TouchEvent function. Срабатывает, когда одна или несколько точек касания перемещаются.
• onTouchMoveCapture: A version of onTouchMove that fires in the фазе захвата.
• onTouchStart: A обработчик TouchEvent function. Срабатывает, когда одна или несколько точек касания помещаются.
• onTouchStartCapture: A version of onTouchStart that fires in the фазе захвата.
• onTransitionEnd: A обработчик TransitionEvent function. Срабатывает при завершении CSS-перехода.
• onTransitionEndCapture: A version of onTransitionEnd that fires in the фазе захвата.
• onWheel: A обработчик WheelEvent function. Срабатывает, когда пользователь вращает колесо мыши.
• onWheelCapture: A version of onWheel that fires in the фазе захвата.
• role: A string. Определяет роль элемента для вспомогательных технологий.
• slot: A string. Определяет имя слота при использовании shadow DOM. В React эквивалентный паттерн обычно достигается путём передачи JSX как props, например <Layout left={<Sidebar />} right={<Content />} />.
• spellCheck: A boolean or null. Если явно установлено в true или false, включает или отключает проверку правописания.
• tabIndex: A number. Переопределяет стандартное поведение клавиши Tab. Избегайте использования значений, отличных от -1 и 0.
• title: A string. Указывает текст всплывающей подсказки для элемента.
• translate: Either 'yes' or 'no'. Передача значения 'no' исключает содержимое элемента из перевода.

Вы также можете передавать пользовательские атрибуты как props, например mycustomprop="someValue". Это может быть полезно при интеграции с сторонними библиотеками. Имя пользовательского атрибута должно быть в нижнем регистре и не должно начинаться с on. Значение будет преобразовано в строку. Если вы передадите null или undefined, пользовательский атрибут будет удалён.

Эти события срабатывают только для элементов <form>:

• onReset: An обработчик Event function. Срабатывает, когда форма сбрасывается.
• onResetCapture: A version of onReset that fires in the фазе захвата.
• onSubmit: An обработчик Event function. Срабатывает, когда форма отправляется.
• onSubmitCapture: A version of onSubmit that fires in the фазе захвата.

Эти события срабатывают только для элементов <dialog>. В отличие от событий браузера, они распространяются в React:

• onCancel: Функция-обработчик Event. Срабатывает, когда пользователь пытается закрыть диалоговое окно.
• onCancelCapture: Версия события onCancel, срабатывающая на стадии захвата.
• onClose: Функция-обработчик Event. Срабатывает при закрытии диалогового окна.
• onCloseCapture: Версия события onClose, срабатывающая на стадии захвата.

Эти события срабатывают только для элементов <details>. В отличие от событий браузера, они распространяются в React:

• onToggle: Функция-обработчик Event. Срабатывает при переключении детали.
• onToggleCapture: Версия события onToggle, срабатывающая на стадии захвата.

Эти события срабатывают для элементов <img>, <iframe>, <object>, <embed>, <link> и SVG <image>. В отличие от событий браузера, они распространяются в React:

• onLoad: Функция-обработчик Event. Срабатывает при загрузке ресурса.
• onLoadCapture: Версия события onLoad, срабатывающая на стадии захвата.
• onError: Функция-обработчик Event. Срабатывает, если ресурс не удалось загрузить.
• onErrorCapture: Версия события onError, срабатывающая на стадии захвата.

Эти события срабатывают для ресурсов, таких как <audio> и <video>. В отличие от событий браузера, они распространяются в React:

• onAbort: Функция обработчика Event. Срабатывает, когда ресурс не загрузился полностью, но не из-за ошибки.
• onAbortCapture: Версия onAbort, которая срабатывает на стадии захвата.
• onCanPlay: Функция обработчика Event. Срабатывает, когда есть достаточно данных для начала воспроизведения, но не достаточно для воспроизведения до конца без буферизации.
• onCanPlayCapture: Версия onCanPlay, которая срабатывает на стадии захвата.
• onCanPlayThrough: Функция обработчика Event. Срабатывает, когда есть достаточно данных, чтобы, вероятно, начать воспроизведение без буферизации до конца.
• onCanPlayThroughCapture: Версия onCanPlayThrough, которая срабатывает на стадии захвата.
• onDurationChange: Функция обработчика Event. Срабатывает, когда длительность медиа обновилась.
• onDurationChangeCapture: Версия onDurationChange, которая срабатывает на стадии захвата.
• onEmptied: Функция обработчика Event. Срабатывает, когда медиа стало пустым.
• onEmptiedCapture: Версия onEmptied, которая срабатывает на стадии захвата.
• onEncrypted: Функция обработчика Event. Срабатывает, когда браузер сталкивается с зашифрованным медиаконтентом.
• onEncryptedCapture: Версия onEncrypted, которая срабатывает на стадии захвата.
• onEnded: Функция обработчика Event. Срабатывает, когда воспроизведение останавливается, потому что больше ничего не осталось для воспроизведения.
• onEndedCapture: Версия onEnded, которая срабатывает на стадии захвата.
• onError: Функция обработчика Event. Срабатывает, когда ресурс не удалось загрузить.
• onErrorCapture: Версия onError, которая срабатывает на стадии захвата.
• onLoadedData: Функция обработчика Event. Срабатывает, когда текущая кадр воспроизведения загрузился.
• onLoadedDataCapture: Версия onLoadedData, которая срабатывает на стадии захвата.
• onLoadedMetadata: Функция обработчика Event. Срабатывает, когда метаданные загрузились.
• onLoadedMetadataCapture: Версия onLoadedMetadata, которая срабатывает на стадии захвата.
• onLoadStart: Функция обработчика Event. Срабатывает, когда браузер начал загрузку ресурса.
• onLoadStartCapture: Версия onLoadStart, которая срабатывает на стадии захвата.
• onPause: Функция обработчика Event. Срабатывает, когда медиа приостановлено.
• onPauseCapture: Версия onPause, которая срабатывает на стадии захвата.
• onPlay: Функция обработчика Event. Срабатывает, когда медиа больше не приостановлено.
• onPlayCapture: Версия onPlay, которая срабатывает на стадии захвата.
• onPlaying: Функция обработчика Event. Срабатывает, когда медиа начинает или перезапускает воспроизведение.
• onPlayingCapture: Версия onPlaying, которая срабатывает на стадии захвата.
• onProgress: Функция обработчика Event. Периодически срабатывает во время загрузки ресурса.
• onProgressCapture: Версия onProgress, которая срабатывает на стадии захвата.
• onRateChange: Функция обработчика Event. Срабатывает при изменении скорости воспроизведения.
• onRateChangeCapture: Версия onRateChange, которая срабатывает на стадии захвата.
• onResize: Функция обработчика Event. Срабатывает при изменении размера видео.
• onResizeCapture: Версия onResize, которая срабатывает на стадии захвата.
• onSeeked: Функция обработчика Event. Срабатывает по завершении операции поиска.
• onSeekedCapture: Версия onSeeked, которая срабатывает на стадии захвата.
• onSeeking: Функция обработчика Event. Срабатывает при начале операции поиска.
• onSeekingCapture: Версия onSeeking, которая срабатывает на стадии захвата.
• onStalled: Функция обработчика Event. Срабатывает, когда браузер ожидает данные, но они не загружаются.
• onStalledCapture: Версия onStalled, которая срабатывает на стадии захвата.
• onSuspend: Функция обработчика Event. Срабатывает, когда загрузка ресурса приостановлена.
• onSuspendCapture: Версия onSuspend, которая срабатывает на стадии захвата.
• onTimeUpdate: Функция обработчика Event. Срабатывает, когда обновляется текущее время воспроизведения.
• onTimeUpdateCapture: Версия onTimeUpdate, которая срабатывает на стадии захвата.
• onVolumeChange: Функция обработчика Event. Срабатывает, когда изменился уровень громкости.
• onVolumeChangeCapture: Версия onVolumeChange, которая срабатывает на стадии захвата.
• onWaiting: Функция обработчика Event. Срабатывает, когда воспроизведение приостановлено из-за временного отсутствия данных.
• onWaitingCapture: Версия onWaiting, которая срабатывает на стадии захвата.

Особенности

• Вы не можете одновременно передать как children, так и dangerouslySetInnerHTML.
• Некоторые события (например, onAbort и onLoad), не распространяются в браузере, но распространяются в React.

ref функция обратного вызова

Вместо объекта ref (например, того, который возвращает useRef), вы можете передать функцию в атрибут ref.

<div ref={(node) => {
  console.log('Attached', node);

  return () => {
    console.log('Clean up', node)
  }
}}>

См. пример использования функции обратного вызова ref.

Когда узел <div> DOM-дерева добавляется на экран, React вызовет вашу функцию обратного вызова ref с узлом DOM node в качестве аргумента. При удалении узла <div> DOM-дерева React вызовет функцию очистки, возвращённую функцией обратного вызова.

React также вызовет вашу функцию обратного вызова ref всякий раз, когда вы передадите другую функцию обратного вызова ref. В приведенном выше примере (node) => { ... } — это другая функция на каждом рендере. При повторном рендере компонента React вызовет предыдущую функцию с null в качестве аргумента, а следующую — с узлом DOM.

Параметры

• node: узел DOM. React передаст вам узел DOM, когда ref будет прикреплён. Если вы не передаёте ту же ссылку на функцию для функции обратного вызова ref на каждом рендере, функция обратного вызова будет временно очищаться и пересоздаваться при каждом повторном рендере компонента.

Возвращаемое значение

• необязательно cleanup function: Когда ref отсоединяется, React вызовет функцию очистки. Если функция не возвращается функцией обратного вызова ref, React снова вызовет функцию обратного вызова null с ref в качестве аргумента при отсоединении ref. Это поведение будет удалено в будущих версиях.

Ограничения

• При включённом режиме строгости React выполнит один дополнительный цикл настройки + очистки только для разработки перед первой реальной настройкой. Это тест на прочность, который гарантирует, что ваша логика очистки «отражает» вашу логику настройки и что она останавливает или отменяет то, что делает настройка. Если это вызывает проблему, реализуйте функцию очистки.
• При передаче другой функции обратного вызова ref, React вызовет функцию очистки предыдущей функции обратного вызова, если она предоставлена. Если функция очистки не определена, функция обратного вызова ref будет вызвана с null в качестве аргумента. Следующая функция будет вызвана с узлом DOM.

Объект события React

Обработчики событий получат объект события React. Иногда он также называется «синтетическим событием».

<button onClick={e => {
  console.log(e); // React event object
}} />

Он соответствует тому же стандарту, что и базовые события DOM, но исправляет некоторые несоответствия между браузерами.

Некоторые события React не отображаются напрямую в родных событиях браузера. Например, в onMouseLeave, e.nativeEvent будет указывать на событие mouseout . Конкретное отображение не является частью публичного API и может быть изменено в будущем. Если вам по какой-либо причине нужен базовый браузерный event, прочитайте его из e.nativeEvent.

Свойства

Объекты событий React реализуют некоторые стандартные Event свойства:

• bubbles: Булево значение. Возвращает, распространяется ли событие через DOM.
• cancelable: Булево значение. Возвращает, может ли быть отменено событие.
• currentTarget: Узел DOM. Возвращает узел, к которому прикреплён текущий обработчик в дереве React.
• defaultPrevented: Булево значение. Возвращает, была ли вызвана preventDefault.
• eventPhase: Число. Возвращает фазу, в которой событие находится в данный момент.
• isTrusted: Булево значение. Возвращает, было ли событие инициировано пользователем.
• target: Узел DOM. Возвращает узел, на котором произошло событие (что может быть удалённым потомком).
• timeStamp: Число. Возвращает время наступления события.

Кроме того, объекты событий React предоставляют эти свойства:

• nativeEvent: Объект DOM Event. Исходный объект события браузера.

Методы

Объекты событий React реализуют некоторые стандартные Event методы:

• preventDefault(): Предотвращает стандартное действие браузера для события.
• stopPropagation(): Останавливает распространение события через дерево React.

Кроме того, объекты событий React предоставляют эти методы:

• isDefaultPrevented(): Возвращает булево значение, указывающее, был ли вызван preventDefault.
• isPropagationStopped(): Возвращает булево значение, указывающее, был ли вызван stopPropagation.
• persist(): Не используется с React DOM. В React Native, вызовите это, чтобы прочитать свойства события после события.
• isPersistent(): Не используется с React DOM. В React Native, возвращает, был ли вызван persist.

Ограничения

• Значения currentTarget, eventPhase, target, и type отражают значения, которые ваш код React ожидает. Под капотом React подключает обработчики событий в корне, но это не отражается в объектах событий React. Например, e.currentTarget может отличаться от базового e.nativeEvent.currentTarget . Для полифильных событий e.type (тип события React) может отличаться от e.nativeEvent.type (базовый тип).

Функция обработки события анимации

Тип обработчика событий для событий анимации CSS анимации.

<div
  onAnimationStart={e => console.log('onAnimationStart')}
  onAnimationIteration={e => console.log('onAnimationIteration')}
  onAnimationEnd={e => console.log('onAnimationEnd')}
/>

Параметры

• e: Объект события React React событие с этими дополнительными свойствами AnimationEvent:
  • animationName
  • elapsedTime
  • pseudoElement

Функция обработки событий буфера обмена

Тип обработчика событий для событий Clipboard API.

<input
  onCopy={e => console.log('onCopy')}
  onCut={e => console.log('onCut')}
  onPaste={e => console.log('onPaste')}
/>

Параметры

• e: Объект события React React событие с дополнительными свойствами ClipboardEvent:

  • clipboardData

Функция обработки событий ввода

Тип обработчика событий для событий input method editor (IME).

<input
  onCompositionStart={e => console.log('onCompositionStart')}
  onCompositionUpdate={e => console.log('onCompositionUpdate')}
  onCompositionEnd={e => console.log('onCompositionEnd')}
/>

Параметры

• e: Объект события React React событие с дополнительными свойствами CompositionEvent:
  • data

Функция обработки событий перетаскивания

Тип обработчика событий для событий HTML Drag and Drop API.

<>
  <div
    draggable={true}
    onDragStart={e => console.log('onDragStart')}
    onDragEnd={e => console.log('onDragEnd')}
  >
    Drag source
  </div>

  <div
    onDragEnter={e => console.log('onDragEnter')}
    onDragLeave={e => console.log('onDragLeave')}
    onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}
    onDrop={e => console.log('onDrop')}
  >
    Drop target
  </div>
</>

Параметры

• e: A React event object with these extra DragEvent properties:

  • dataTransfer

  It also includes the inherited MouseEvent properties:

  • altKey
  • button
  • buttons
  • ctrlKey
  • clientX
  • clientY
  • getModifierState(key)
  • metaKey
  • movementX
  • movementY
  • pageX
  • pageY
  • relatedTarget
  • screenX
  • screenY
  • shiftKey

  It also includes the inherited UIEvent properties:

  • detail
  • view

FocusEvent обработчик событий

Тип обработчика событий для событий фокуса.

<input
  onFocus={e => console.log('onFocus')}
  onBlur={e => console.log('onBlur')}
/>

См. пример.

Параметры

• e: A React event object with these extra FocusEvent properties:

  • relatedTarget

  It also includes the inherited UIEvent properties:

  • detail
  • view

Event обработчик событий

Тип обработчика событий для общих событий.

Параметры

• e: A React event object with no additional properties.

InputEvent обработчик событий

Тип обработчика событий для события onBeforeInput.

<input onBeforeInput={e => console.log('onBeforeInput')} />

Параметры

• e: A React event object with these extra InputEvent properties:
  • data

KeyboardEvent обработчик событий

Тип обработчика событий для событий клавиатуры.

<input
  onKeyDown={e => console.log('onKeyDown')}
  onKeyUp={e => console.log('onKeyUp')}
/>

См. пример.

Параметры

• e: A React event object with these extra KeyboardEvent properties:

  • altKey
  • charCode
  • code
  • ctrlKey
  • getModifierState(key)
  • key
  • keyCode
  • locale
  • metaKey
  • location
  • repeat
  • shiftKey
  • which

  It also includes the inherited UIEvent properties:

  • detail
  • view

MouseEvent обработчик событий

Тип обработчика событий для событий мыши.

<div
  onClick={e => console.log('onClick')}
  onMouseEnter={e => console.log('onMouseEnter')}
  onMouseOver={e => console.log('onMouseOver')}
  onMouseDown={e => console.log('onMouseDown')}
  onMouseUp={e => console.log('onMouseUp')}
  onMouseLeave={e => console.log('onMouseLeave')}
/>

См. пример.

Параметры

• e: A React event object with these extra MouseEvent properties:

  • altKey
  • button
  • buttons
  • ctrlKey
  • clientX
  • clientY
  • getModifierState(key)
  • metaKey
  • movementX
  • movementY
  • pageX
  • pageY
  • relatedTarget
  • screenX
  • screenY
  • shiftKey

  Также содержит унаследованные свойства UIEvent:

  • detail
  • view

PointerEvent функция-обработчик

Тип обработчика событий для событий указателя.

<div
  onPointerEnter={e => console.log('onPointerEnter')}
  onPointerMove={e => console.log('onPointerMove')}
  onPointerDown={e => console.log('onPointerDown')}
  onPointerUp={e => console.log('onPointerUp')}
  onPointerLeave={e => console.log('onPointerLeave')}
/>

См. пример.

Параметры

• e: A React event object with these extra PointerEvent properties:

  • height
  • isPrimary
  • pointerId
  • pointerType
  • pressure
  • tangentialPressure
  • tiltX
  • tiltY
  • twist
  • width

  Также содержит унаследованные свойства MouseEvent:

  • altKey
  • button
  • buttons
  • ctrlKey
  • clientX
  • clientY
  • getModifierState(key)
  • metaKey
  • movementX
  • movementY
  • pageX
  • pageY
  • relatedTarget
  • screenX
  • screenY
  • shiftKey

  Также содержит унаследованные свойства UIEvent:

  • detail
  • view

TouchEvent функция-обработчик

Тип обработчика событий для событий касания.

<div
  onTouchStart={e => console.log('onTouchStart')}
  onTouchMove={e => console.log('onTouchMove')}
  onTouchEnd={e => console.log('onTouchEnd')}
  onTouchCancel={e => console.log('onTouchCancel')}
/>

• e: A объект события React с этими дополнительными TouchEvent свойствами:

  • altKey
  • ctrlKey
  • changedTouches
  • getModifierState(key)
  • metaKey
  • shiftKey
  • touches
  • targetTouches

  Он также включает унаследованные UIEvent свойства:

  • detail
  • view

TransitionEvent обработчик функции

Тип обработчика событий для событий перехода CSS.

<div
  onTransitionEnd={e => console.log('onTransitionEnd')}
/>

Параметры

• e: Объект события React с этими дополнительными TransitionEvent свойствами:
  • elapsedTime
  • propertyName
  • pseudoElement

UIEvent обработчик функции

Тип обработчика событий для универсальных событий пользовательского интерфейса.

<div
  onScroll={e => console.log('onScroll')}
/>

Параметры

• e: A объект события React с этими дополнительными UIEvent свойствами:
  • detail
  • view

WheelEvent обработчик функции

Обработчик событий для события onWheel.

<div
  onWheel={e => console.log('onWheel')}
/>

Параметры

• e: A объект события React с этими дополнительными WheelEvent свойствами:

  • deltaMode
  • deltaX
  • deltaY
  • deltaZ

  Он также включает унаследованные MouseEvent свойства:

  • altKey
  • button
  • buttons
  • ctrlKey
  • clientX
  • clientY
  • getModifierState(key)
  • metaKey
  • movementX
  • movementY
  • pageX
  • pageY
  • relatedTarget
  • screenX
  • screenY
  • shiftKey

  Он также включает унаследованные UIEvent свойства:

  • detail
  • view

Использование

Применение стилей CSS

В React вы указываете класс CSS с помощью className. Это работает так же, как атрибут class в HTML:

<img className="avatar" />

Затем вы пишете правила CSS для него в отдельном файле CSS:

/* In your CSS */
.avatar {
  border-radius: 50%;
}

React не предписывает, как вы добавляете файлы CSS. В простейшем случае вы добавите тег <link> в свой HTML. Если вы используете инструмент сборки или фреймворк, обратитесь к документации, чтобы узнать, как добавить файл CSS в свой проект.

Иногда значения стиля зависят от данных. Используйте атрибут style для динамической передачи некоторых стилей:

<img
  className="avatar"
  style={{
    width: user.imageSize,
    height: user.imageSize
  }}
/>

В приведенном выше примере style={{}} — это не специальный синтаксис, а обычный объект {} внутри style={ } JSX фигурных скобок. Мы рекомендуем использовать атрибут style только тогда, когда ваши стили зависят от переменных JavaScript.

export default function Avatar({ user }) {
  return (
    <img
      src={user.imageUrl}
      alt={'Photo of ' + user.name}
      className="avatar"
      style={{
        width: user.imageSize,
        height: user.imageSize
      }}
    />
  );
}

import cn from 'classnames';

function Row({ isSelected }) {
  return (
    <div className={cn('row', isSelected && 'selected')}>
      ...
    </div>
  );
}

import cn from 'classnames';

function Row({ isSelected, size }) {
  return (
    <div className={cn('row', {
      selected: isSelected,
      large: size === 'large',
      small: size === 'small',
    })}>
      ...
    </div>
  );
}

Изменение узла DOM с помощью ref

Иногда вам нужно получить узел DOM браузера, связанный с тегом в JSX. Например, если вы хотите сфокусировать <input> при нажатии на кнопку, вам нужно вызвать focus() на узле DOM браузера <input>.

Чтобы получить узел DOM браузера для тега, определите ref и передайте его в качестве атрибута ref этому тегу:

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);
  // ...
  return (
    <input ref={inputRef} />
    // ...

React поместит узел DOM в inputRef.current после его отображения на экране.

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <input ref={inputRef} />
      <button onClick={handleClick}>
        Focus the input
      </button>
    </>
  );
}

Дополнительную информацию о манипулировании DOM с помощью refs и смотрите больше примеров.

Для более сложных случаев использования атрибут ref также принимает функцию обратного вызова callback function.

Опасно устанавливать inner HTML

Вы можете передать строку с исходным HTML-кодом в элемент следующим образом:

const markup = { __html: '<p>some raw html</p>' };
return <div dangerouslySetInnerHTML={markup} />;

Это опасно. Как и с базовым свойством DOM innerHTML, необходимо проявлять крайнюю осторожность! Если разметка поступает из ненадежного источника, очень легко создать уязвимость XSS таким образом.

Например, если вы используете библиотеку Markdown, которая преобразует Markdown в HTML, вы доверяете, что её парсер не содержит ошибок, и пользователь видит только свой ввод, вы можете отобразить полученный HTML следующим образом:

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // This is ONLY safe because the output HTML
  // is shown to the same user, and because you
  // trust this Markdown parser to not have bugs.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

export default function MarkdownPreview({ markdown }) {
  const markup = renderMarkdownToHTML(markdown);
  return <div dangerouslySetInnerHTML={markup} />;
}

Объект {__html} должен создаваться как можно ближе к месту генерации HTML, как в примере в функции renderMarkdownToHTML. Это гарантирует, что весь исходный HTML, используемый в вашем коде, явно помечен как таковой, и что в dangerouslySetInnerHTML передаются только переменные, которые, по вашему ожиданию, содержат HTML. Не рекомендуется создавать объект в строке, как <div dangerouslySetInnerHTML={{__html: markup}} />.

Чтобы понять, почему рендеринг произвольного HTML опасен, замените приведенный выше код следующим:

const post = {
  // Imagine this content is stored in the database.
  content: `<img src="" onerror='alert("you were hacked")'>`
};

export default function MarkdownPreview() {
  // 🔴 SECURITY HOLE: passing untrusted input to dangerouslySetInnerHTML
  const markup = { __html: post.content };
  return <div dangerouslySetInnerHTML={markup} />;
}

Код, встроенный в HTML, будет выполняться. Злоумышленник может использовать эту уязвимость, чтобы украсть информацию пользователя или совершить действия от его имени. Используйте dangerouslySetInnerHTML только с надёжными и очищенными данными.

Обработка событий мыши

Этот пример демонстрирует некоторые распространённые события мыши и время их срабатывания.

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (parent)')}
      onMouseLeave={e => console.log('onMouseLeave (parent)')}
    >
      <button
        onClick={e => console.log('onClick (first button)')}
        onMouseDown={e => console.log('onMouseDown (first button)')}
        onMouseEnter={e => console.log('onMouseEnter (first button)')}
        onMouseLeave={e => console.log('onMouseLeave (first button)')}
        onMouseOver={e => console.log('onMouseOver (first button)')}
        onMouseUp={e => console.log('onMouseUp (first button)')}
      >
        First button
      </button>
      <button
        onClick={e => console.log('onClick (second button)')}
        onMouseDown={e => console.log('onMouseDown (second button)')}
        onMouseEnter={e => console.log('onMouseEnter (second button)')}
        onMouseLeave={e => console.log('onMouseLeave (second button)')}
        onMouseOver={e => console.log('onMouseOver (second button)')}
        onMouseUp={e => console.log('onMouseUp (second button)')}
      >
        Second button
      </button>
    </div>
  );
}

Обработка событий указателя

В этом примере показаны некоторые распространённые события указателя и время их срабатывания.

export default function PointerExample() {
  return (
    <div
      onPointerEnter={e => console.log('onPointerEnter (parent)')}
      onPointerLeave={e => console.log('onPointerLeave (parent)')}
      style={{ padding: 20, backgroundColor: '#ddd' }}
    >
      <div
        onPointerDown={e => console.log('onPointerDown (first child)')}
        onPointerEnter={e => console.log('onPointerEnter (first child)')}
        onPointerLeave={e => console.log('onPointerLeave (first child)')}
        onPointerMove={e => console.log('onPointerMove (first child)')}
        onPointerUp={e => console.log('onPointerUp (first child)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        First child
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (second child)')}
        onPointerEnter={e => console.log('onPointerEnter (second child)')}
        onPointerLeave={e => console.log('onPointerLeave (second child)')}
        onPointerMove={e => console.log('onPointerMove (second child)')}
        onPointerUp={e => console.log('onPointerUp (second child)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Second child
      </div>
    </div>
  );
}

Обработка событий фокусировки

В React события фокусировки «пузырятся» вверх. Вы можете использовать currentTarget и relatedTarget для определения, произошли ли события фокусировки или размытия извне родительского элемента. Пример демонстрирует, как обнаружить фокусировку дочернего элемента, фокусировку родительского элемента и как обнаружить вхождение или выход фокуса из всего поддерева.

export default function FocusExample() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused parent');
        } else {
          console.log('focused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus entered parent');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused parent');
        } else {
          console.log('unfocused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus left parent');
        }
      }}
    >
      <label>
        First name:
        <input name="firstName" />
      </label>
      <label>
        Last name:
        <input name="lastName" />
      </label>
    </div>
  );
}

Обработка событий клавиатуры

В этом примере показаны некоторые распространённые события клавиатуры и время их срабатывания.

export default function KeyboardExample() {
  return (
    <label>
      First name:
      <input
        name="firstName"
        onKeyDown={e => console.log('onKeyDown:', e.key, e.code)}
        onKeyUp={e => console.log('onKeyUp:', e.key, e.code)}
      />
    </label>
  );
}