Componentes comuns (por exemplo, <div>)
Todos os componentes nativos do navegador, como <div>
, suportam algumas props e eventos comuns.
- Referência
- Componentes comuns (por exemplo,
<div>
) - Função de callback
ref
- Objeto de evento React
- Função do manipulador
AnimationEvent
- Função do manipulador
ClipboardEvent
- Função do manipulador
CompositionEvent
- Função do manipulador
DragEvent
- Função do manipulador
FocusEvent
- Função do manipulador
Event
- Função do manipulador
InputEvent
- Função do manipulador
KeyboardEvent
- Função do manipulador
MouseEvent
- Função do manipulador
PointerEvent
- Função manipuladora de eventos
TouchEvent
- Função manipuladora do evento
TransitionEvent
- Função manipuladora de eventos
UIEvent
- Função manipuladora de eventos
WheelEvent
- Componentes comuns (por exemplo,
- Uso
Referência
Componentes comuns (por exemplo, <div>
)
<div className="wrapper">Algum conteúdo</div>
Props
Estas props especiais do React são suportadas para todos os componentes nativos:
-
children
: Um nó React (um elemento, uma string, um número, um portal, um nó vazio comonull
,undefined
e booleanos, ou um array de outros nós React). Especifica o conteúdo dentro do componente. Quando você usa JSX, você geralmente especificará a propchildren
implicitamente ao aninhar tags como<div><span /></div>
. -
dangerouslySetInnerHTML
: Um objeto do formulário{ __html: '<p>some html</p>' }
com uma string HTML bruta dentro. Substitui a propriedadeinnerHTML
do nó DOM e exibe o HTML passado dentro. Isso deve ser usado com extrema cautela! Se o HTML dentro não for confiável (por exemplo, se for baseado em dados do usuário), você corre o risco de introduzir uma vulnerabilidade XSS. Leia mais sobre o uso dedangerouslySetInnerHTML
. -
ref
: Um objeto ref deuseRef
oucreateRef
, ou umaref
função callback, ou uma string para refs legados. Seu ref será preenchido com o elemento DOM para este nó. Leia mais sobre como manipular o DOM com refs. -
suppressContentEditableWarning
: Um booleano. Setrue
, suprime o aviso que o React mostra para elementos que têmchildren
econtentEditable={true}
(que normalmente não funcionam juntos). Use isso se você estiver construindo uma biblioteca de entrada de texto que gerencia o conteúdocontentEditable
manualmente. -
suppressHydrationWarning
: Um booleano. Se você usar renderização no servidor, normalmente há um aviso quando o servidor e o cliente renderizam conteúdo diferente. Em alguns casos raros (como timestamps), é muito difícil ou impossível garantir uma correspondência exata. Se você definirsuppressHydrationWarning
comotrue
, o React não o avisará sobre incompatibilidades nos atributos e no conteúdo desse elemento. Ele só funciona em um nível de profundidade e é projetado para ser usado como uma porta de saída. Não use em excesso. Leia sobre como suprimir erros de hidratação. -
style
: Um objeto com estilos CSS, por exemplo,{ fontWeight: 'bold', margin: 20 }
. Semelhante à propriedadestyle
, os nomes das propriedades CSS precisam ser escritos comocamelCase
, por exemplo,fontWeight
em vez defont-weight
. Você pode passar strings ou números como valores. Se você passar um número, comowidth: 100
, o React anexará automaticamentepx
(“pixels”) ao valor, a menos que seja uma propriedade sem unidade. Recomendamos que você usestyle
apenas para estilos dinâmicos nos quais você não conhece os valores do estilo com antecedência. Em outros casos, aplicar classes CSS simples comclassName
é mais eficiente. Leia mais sobreclassName
estyle
.
Essas props DOM padrão também são suportadas para todos os componentes nativos:
accessKey
: Uma string. Especifica um atalho de teclado para o elemento. Geralmente não recomendado.aria-*
: Atributos ARIA permitem que você especifique as informações da árvore de acessibilidade para este elemento. Veja Atributos ARIA para uma referência completa. Em React, todos os nomes de atributos ARIA são exatamente os mesmos no HTML.autoCapitalize
: Uma string. Especifica se e como a entrada do usuário deve ser capitalizada.className
: Uma string. Especifica o nome da classe CSS do elemento. Leia mais sobre como aplicar estilos CSS.contentEditable
: Um booleano. Setrue
, o navegador permite que o usuário edite o elemento renderizado diretamente. Ele é usado para implementar bibliotecas de entrada de texto avançadas como Lexical. React avisa se você tentar passar os filhos React para um elemento comcontentEditable={true}
porque o React não poderá atualizar o conteúdo depois das edições do usuário.data-*
: Atributos de dados permitem que você anexe alguns dados de string ao elemento, por exemplo,data-fruit="banana"
. Em React, eles não são comumente usados porque você geralmente leria dados de props ou state em vez disso.dir
:'ltr'
ou'rtl'
. Especifica a direção do texto do elemento.draggable
: Um booleano. Especifica se o elemento é arrastável. Parte da API HTML Drag and Drop.enterKeyHint
: Uma string. Especifica qual ação apresentar para a tecla Enter em teclados virtuais.htmlFor
: Uma string. Para<label>
e<output>
, permite que você associe o rótulo com algum controle. Mesma coisa que o atributo HTMLfor
. React usa os nomes de propriedade DOM padrão (htmlFor
) em vez de nomes de atributo HTML.hidden
: Um booleano ou uma string. Especifica se o elemento deve ser ocultado.id
: Uma string. Especifica um identificador exclusivo para este elemento, que pode ser usado para encontrá-lo mais tarde ou conectá-lo com outros elementos. Gere-o comuseId
para evitar conflitos entre várias instâncias do mesmo componente.is
: Uma string. Se especificado, o componente se comportará como um elemento personalizado.inputMode
: Uma string. Especifica que tipo de teclado exibir (por exemplo, texto, número ou telefone).itemProp
: Uma string. Especifica qual propriedade o elemento representa para rastreadores de dados estruturados.lang
: Uma string. Especifica o idioma do elemento.onAnimationEnd
: Uma função deAnimationEvent
handler. Dispara quando uma animação CSS é concluída.onAnimationEndCapture
: Uma versão deonAnimationEnd
que dispara na fase de captura.onAnimationIteration
: Uma função deAnimationEvent
handler. Dispara quando uma iteração de uma animação CSS termina, e outra começa.onAnimationIterationCapture
: Uma versão deonAnimationIteration
que dispara na fase de captura.onAnimationStart
: Uma função deAnimationEvent
handler. Dispara quando uma animação CSS começa.onAnimationStartCapture
:onAnimationStart
, mas dispara na fase de captura.onAuxClick
: Uma função deMouseEvent
handler. Dispara quando um botão de ponteiro não primário foi clicado.onAuxClickCapture
: Uma versão deonAuxClick
que dispara na fase de captura.onBeforeInput
: Uma função deInputEvent
handler. Dispara antes que o valor de um elemento editável seja modificado. React não usa ainda o evento nativobeforeinput
, e em vez disso tenta polyfill usando outros eventos.onBeforeInputCapture
: Uma versão deonBeforeInput
que dispara na fase de captura.onBlur
: Uma função deFocusEvent
handler. Dispara quando um elemento perde o foco. Diferente do eventoblur
embutido no navegador, em React o eventoonBlur
propaga.onBlurCapture
: Uma versão deonBlur
que dispara na fase de captura.onClick
: Uma função deMouseEvent
handler. Dispara quando o botão primário foi clicado no dispositivo apontador.onClickCapture
: Uma versão deonClick
que dispara na fase de captura.onCompositionStart
: Uma função deCompositionEvent
handler. Dispara quando um input method editor inicia uma nova sessão de composição.onCompositionStartCapture
: Uma versão deonCompositionStart
que dispara na fase de captura.onCompositionEnd
: Uma função deCompositionEvent
handler. Dispara quando um input method editor conclui ou cancela uma sessão de composição.onCompositionEndCapture
: Uma versão deonCompositionEnd
que dispara na fase de captura.onCompositionUpdate
: Uma função deCompositionEvent
handler. Dispara quando um input method editor recebe um novo caractere.onCompositionUpdateCapture
: Uma versão deonCompositionUpdate
que dispara na fase de captura.onContextMenu
: Uma função deMouseEvent
handler. Dispara quando o usuário tenta abrir um menu de contexto.onContextMenuCapture
: Uma versão deonContextMenu
que dispara na fase de captura.onCopy
: Uma função deClipboardEvent
handler. Dispara quando o usuário tenta copiar algo na área de transferência.onCopyCapture
: Uma versão deonCopy
que dispara na fase de captura.onCut
: Uma função deClipboardEvent
handler. Dispara quando o usuário tenta cortar algo na área de transferência.onCutCapture
: Uma versão deonCut
que dispara na fase de captura.onDoubleClick
: Uma função deMouseEvent
handler. Dispara quando o usuário clica duas vezes. Corresponde ao eventodblclick
do navegador.onDoubleClickCapture
: Uma versão deonDoubleClick
que dispara na fase de captura.onDrag
: Uma função deDragEvent
handler. Dispara enquanto o usuário está arrastando algo.onDragCapture
: Uma versão deonDrag
que dispara na fase de captura.onDragEnd
: Uma função deDragEvent
handler. Dispara quando o usuário para de arrastar algo.onDragEndCapture
: Uma versão deonDragEnd
que dispara na fase de captura.onDragEnter
: Uma função deDragEvent
handler. Dispara quando o conteúdo arrastado entra em um destino válido.onDragEnterCapture
: Uma versão deonDragEnter
que dispara na fase de captura.onDragOver
: Uma função deDragEvent
handler. Dispara em um destino válido enquanto o conteúdo arrastado é arrastado sobre ele. Você deve chamare.preventDefault()
aqui para permitir soltar.onDragOverCapture
: Uma versão deonDragOver
que dispara na fase de captura.onDragStart
: Uma função deDragEvent
handler. Dispara quando o usuário começa a arrastar um elemento.onDragStartCapture
: Uma versão deonDragStart
que dispara na fase de captura.onDrop
: Uma função deDragEvent
handler. Dispara quando algo é solto em um destino válido.onDropCapture
: Uma versão deonDrop
que dispara na fase de captura.onFocus
: Uma função deFocusEvent
handler. Dispara quando um elemento recebe foco. Diferente do eventofocus
embutido no navegador, em React o eventoonFocus
propaga.onFocusCapture
: Uma versão deonFocus
que dispara na fase de captura.onGotPointerCapture
: Uma função dePointerEvent
handler. Dispara quando um elemento captura programaticamente um ponteiro.onGotPointerCaptureCapture
: Uma versão deonGotPointerCapture
que dispara na fase de captura.onKeyDown
: Uma função deKeyboardEvent
handler. Dispara quando uma tecla é pressionada.onKeyDownCapture
: Uma versão deonKeyDown
que dispara na fase de captura.onKeyPress
: Uma função deKeyboardEvent
handler. Obsoleto. UseonKeyDown
ouonBeforeInput
em vez disso.onKeyPressCapture
: Uma versão deonKeyPress
que dispara na fase de captura.onKeyUp
: Uma função deKeyboardEvent
handler. Dispara quando uma tecla é solta.onKeyUpCapture
: Uma versão deonKeyUp
que dispara na fase de captura.onLostPointerCapture
: Uma função dePointerEvent
handler. Dispara quando um elemento para de capturar um ponteiro.onLostPointerCaptureCapture
: Uma versão deonLostPointerCapture
que dispara na fase de captura.onMouseDown
: Uma função deMouseEvent
handler. Dispara quando o ponteiro é pressionado.onMouseDownCapture
: Uma versão deonMouseDown
que dispara na fase de captura.onMouseEnter
: Uma função deMouseEvent
handler. Dispara quando o ponteiro se move para dentro de um elemento. Não possui uma fase de captura. Em vez disso,onMouseLeave
eonMouseEnter
propagam do elemento que está saindo para aquele que está entrando.onMouseLeave
: Uma função deMouseEvent
handler. Dispara quando o ponteiro se move para fora de um elemento. Não possui uma fase de captura. Em vez disso,onMouseLeave
eonMouseEnter
propagam do elemento que está saindo para aquele que está entrando.onMouseMove
: Uma função deMouseEvent
handler. Dispara quando o ponteiro muda de coordenadas.onMouseMoveCapture
: Uma versão deonMouseMove
que dispara na fase de captura.onMouseOut
: Uma função deMouseEvent
handler. Dispara quando o ponteiro se move para fora de um elemento, ou se ele se move para um elemento filho.onMouseOutCapture
: Uma versão deonMouseOut
que dispara na fase de captura.onMouseUp
: Uma função deMouseEvent
handler. Dispara quando o ponteiro é solto.onMouseUpCapture
: Uma versão deonMouseUp
que dispara na fase de captura.onPointerCancel
: Uma função dePointerEvent
handler. Dispara quando o navegador cancela uma interação de ponteiro.onPointerCancelCapture
: Uma versão deonPointerCancel
que dispara na fase de captura.onPointerDown
: Uma função dePointerEvent
handler. Dispara quando um ponteiro se torna ativo.onPointerDownCapture
: Uma versão deonPointerDown
que dispara na fase de captura.onPointerEnter
: Uma função dePointerEvent
handler. Dispara quando um ponteiro se move para dentro de um elemento. Não possui uma fase de captura. Em vez disso,onPointerLeave
eonPointerEnter
propagam do elemento que está saindo para aquele que está entrando.onPointerLeave
: Uma função dePointerEvent
handler. Dispara quando um ponteiro se move para fora de um elemento. Não possui uma fase de captura. Em vez disso,onPointerLeave
eonPointerEnter
propagam do elemento que está saindo para aquele que está entrando.onPointerMove
: Uma função dePointerEvent
handler. Dispara quando um ponteiro muda de coordenadas.onPointerMoveCapture
: Uma versão deonPointerMove
que dispara na fase de captura.onPointerOut
: Uma função dePointerEvent
handler. Dispara quando um ponteiro se move para fora de um elemento, se a interação do ponteiro for cancelada e alguns outros motivos.onPointerOutCapture
: Uma versão deonPointerOut
que dispara na fase de captura.onPointerUp
: Uma função dePointerEvent
handler. Dispara quando um ponteiro não está mais ativo.onPointerUpCapture
: Uma versão deonPointerUp
que dispara na fase de captura.onPaste
: Uma função deClipboardEvent
handler. Dispara quando o usuário tenta colar algo da área de transferência.onPasteCapture
: Uma versão deonPaste
que dispara na fase de captura.onScroll
: Uma função deEvent
handler. Dispara quando um elemento foi rolado. Este evento não propaga.onScrollCapture
: Uma versão deonScroll
que dispara na fase de captura.onSelect
: Uma função deEvent
handler. Dispara após a seleção dentro de um elemento editável, como uma alteração de entrada. React estende o eventoonSelect
para funcionar também para elementos comcontentEditable={true}
. Além disso, React o estende para disparar para seleção vazia e em edições (o que pode afetar a seleção).onSelectCapture
: Uma versão deonSelect
que dispara na fase de captura.onTouchCancel
: Uma função deTouchEvent
handler. Dispara quando o navegador cancela uma interação touch.onTouchCancelCapture
: Uma versão deonTouchCancel
que dispara na fase de captura.onTouchEnd
: Uma função deTouchEvent
handler. Dispara quando um ou mais pontos de toque são removidos.onTouchEndCapture
: Uma versão deonTouchEnd
que dispara na fase de captura.onTouchMove
: Uma função deTouchEvent
handler. Dispara quando um ou mais pontos de toque são movidos.onTouchMoveCapture
: Uma versão deonTouchMove
que dispara na fase de captura.onTouchStart
: Uma função deTouchEvent
handler. Dispara quando um ou mais pontos de toque são colocados.onTouchStartCapture
: Uma versão deonTouchStart
que dispara na fase de captura.onTransitionEnd
: Uma função deTransitionEvent
handler. Dispara quando uma transição CSS é concluída.onTransitionEndCapture
: Uma versão deonTransitionEnd
que dispara na fase de captura.onWheel
: Uma função deWheelEvent
handler. Dispara quando o usuário gira um botão da roda.onWheelCapture
: Uma versão deonWheel
que dispara na fase de captura.role
: Uma string. Especifica a função do elemento explicitamente para tecnologias assistivas.slot
: Uma string. Especifica o nome do slot ao usar shadow DOM. Em React, um padrão equivalente é normalmente alcançado passando JSX como props, por exemplo,<Layout left={<Sidebar />} right={<Content />} />
.spellCheck
: Um booleano ou nulo. Se definido explicitamente comotrue
oufalse
, habilita ou desabilita a verificação ortográfica.tabIndex
: Um número. Substitui o comportamento padrão do botão Tab. Evite usar valores diferentes de-1
e0
.title
: Uma string. Especifica o texto da dica de ferramenta para o elemento.translate
:'yes'
ou'no'
. Passar'no'
exclui o conteúdo do elemento de ser traduzido. Você também pode passar atributos customizados como props, por exemplomycustomprop = "someValue"
. Isso pode ser útil ao integrar com bibliotecas de terceiros. O nome do atributo customizado deve estar em caixa baixa e não deve começar comon
. O valor será convertido em uma string. Se você passarnull
ouundefined
, o atributo customizado será removido.
Esses eventos disparam apenas para os elementos <form>
:
onReset
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando um formulário é resetado.onResetCapture
: Uma versão doonReset
que dispara na fase de captura.onSubmit
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando um formulário é submetido.onSubmitCapture
: Uma versão doonSubmit
que dispara na fase de captura.
Esses eventos disparam apenas para os elementos <dialog>
. Diferente dos eventos do navegador, eles propagam no React:
onCancel
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o usuário tenta descartar o diálogo.onCancelCapture
: Uma versão doonCancel
que dispara na fase de captura.onClose
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando um diálogo foi fechado.onCloseCapture
: Uma versão doonClose
que dispara na fase de captura.
Esses eventos disparam apenas para os elementos <details>
. Diferente dos eventos do navegador, eles propagam no React:
onToggle
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o usuário alterna os detalhes.onToggleCapture
: Uma versão doonToggle
que dispara na fase de captura.
Esses eventos disparam para elementos <img>
, <iframe>
, <object>
, <embed>
, <link>
e SVG <image>
. Diferente dos eventos do navegador, eles propagam no React:
onLoad
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o recurso foi carregado.onLoadCapture
: Uma versão doonLoad
que dispara na fase de captura.onError
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o recurso não pôde ser carregado.onErrorCapture
: Uma versão doonError
que dispara na fase de captura.
Esses eventos disparam para recursos como <audio>
e <video>
. Diferente dos eventos do navegador, eles propagam no React:
onAbort
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o recurso não foi totalmente carregado, mas não devido a um erro.onAbortCapture
: Uma versão doonAbort
que dispara na fase de captura.onCanPlay
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando há dados suficientes para começar a reproduzir, mas não o suficiente para reproduzir até o fim sem buffering.onCanPlayCapture
: Uma versão doonCanPlay
que dispara na fase de captura.onCanPlayThrough
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando há dados suficientes que é provável que seja possível começar a reproduzir sem buffering até o fim.onCanPlayThroughCapture
: Uma versão doonCanPlayThrough
que dispara na fase de captura.onDurationChange
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando a duração da mídia foi atualizada.onDurationChangeCapture
: Uma versão doonDurationChange
que dispara na fase de captura.onEmptied
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando a mídia se tornou vazia.onEmptiedCapture
: Uma versão doonEmptied
que dispara na fase de captura.onEncrypted
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o navegador encontra mídia criptografada.onEncryptedCapture
: Uma versão doonEncrypted
que dispara na fase de captura.onEnded
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando a reprodução para porque não há mais nada para reproduzir.onEndedCapture
: Uma versão doonEnded
que dispara na fase de captura.onError
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o recurso não pôde ser carregado.onErrorCapture
: Uma versão doonError
que dispara na fase de captura.onLoadedData
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o frame de reprodução atual foi carregado.onLoadedDataCapture
: Uma versão doonLoadedData
que dispara na fase de captura.onLoadedMetadata
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando os metadados foram carregados.onLoadedMetadataCapture
: Uma versão doonLoadedMetadata
que dispara na fase de captura.onLoadStart
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o navegador começou a carregar o recurso.onLoadStartCapture
: Uma versão doonLoadStart
que dispara na fase de captura.onPause
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando a mídia foi pausada.onPauseCapture
: Uma versão doonPause
que dispara na fase de captura.onPlay
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando a mídia não está mais pausada.onPlayCapture
: Uma versão doonPlay
que dispara na fase de captura.onPlaying
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando a mídia começa ou reinicia a reprodução.onPlayingCapture
: Uma versão doonPlaying
que dispara na fase de captura.onProgress
: Uma funçãomanipulador de eventos (event handler)
. Dispara periodicamente enquanto o recurso está carregando.onProgressCapture
: Uma versão doonProgress
que dispara na fase de captura.onRateChange
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando a taxa de reprodução muda.onRateChangeCapture
: Uma versão doonRateChange
que dispara na fase de captura.onResize
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o vídeo muda de tamanho.onResizeCapture
: Uma versão doonResize
que dispara na fase de captura.onSeeked
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando uma operação de busca é concluída.onSeekedCapture
: Uma versão doonSeeked
que dispara na fase de captura.onSeeking
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando uma operação de busca começa.onSeekingCapture
: Uma versão doonSeeking
que dispara na fase de captura.onStalled
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o navegador está esperando por dados, mas continua sem carregar.onStalledCapture
: Uma versão doonStalled
que dispara na fase de captura.onSuspend
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o carregamento do recurso foi suspenso.onSuspendCapture
: Uma versão doonSuspend
que dispara na fase de captura.onTimeUpdate
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o tempo de reprodução atual é atualizado.onTimeUpdateCapture
: Uma versão doonTimeUpdate
que dispara na fase de captura.onVolumeChange
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando o volume foi alterado.onVolumeChangeCapture
: Uma versão doonVolumeChange
que dispara na fase de captura.onWaiting
: Uma funçãomanipulador de eventos (event handler)
. Dispara quando a reprodução parou devido à falta temporária de dados.onWaitingCapture
: Uma versão doonWaiting
que dispara na fase de captura.
Ressalvas
- Você não pode passar
children
edangerouslySetInnerHTML
ao mesmo tempo. - Alguns eventos (como
onAbort
eonLoad
) não propagam no navegador, mas propagam no React.
Função de callback ref
Em vez de um objeto ref (como o que é retornado por useRef
), você pode passar uma função para o atributo ref
.
<div ref={(node) => {
console.log('Attached', node);
return () => {
console.log('Clean up', node)
}
}}>
Veja um exemplo de como usar o callback ref
.
Quando o nó DOM <div>
é adicionado à tela, React chamará seu callback ref
com o node
DOM como argumento. Quando esse nó DOM <div>
for removido, React chamará sua função de limpeza retornada do callback.
React também chamará seu callback ref
sempre que você passar um callback ref
diferente. No exemplo acima, (node) => { ... }
é uma função diferente a cada renderização. Quando seu componente renderizar novamente, a função anterior será chamada com null
como argumento, e a função seguinte será chamada com o nó DOM.
Parâmetros
node
: Um nó DOM. React passará o nó DOM quando a ref for anexada. A menos que você passe a mesma referência de função para o callbackref
em cada renderização, o callback será temporariamente limpo e recriado durante cada nova renderização do componente.
Retorna
- opcional
função de limpeza
: Quando aref
é desanexada, React chamará a função de limpeza. Se uma função não for retornada pelo callbackref
, React chamará o callback novamente comnull
como argumento quando aref
for desanexada. Esse comportamento será removido em uma versão futura.
Ressalvas
- Quando o Modo Strict está ativado, React irá executar um ciclo extra de configuração + limpeza apenas para desenvolvimento antes da primeira configuração real. Este é um teste de estresse que garante que sua lógica de limpeza “espelhe” sua lógica de configuração e que ele pare ou desfaça o que a configuração está fazendo. Se isso causar um problema, implemente a função de limpeza.
- Quando você passa um callback
ref
diferente, React chamará a função de limpeza do callback anterior, se fornecida. Se nenhuma função de limpeza for definida, o callbackref
será chamado comnull
como argumento. A função seguinte será chamada com o nó DOM.
Objeto de evento React
Seus manipuladores de eventos receberão um objeto de evento React. Ele também é às vezes conhecido como um “evento sintético”.
<button onClick={e => {
console.log(e); // Objeto de evento React
}} />
Ele está em conformidade com o mesmo padrão dos eventos DOM subjacentes, mas corrige algumas inconsistências do navegador.
Alguns eventos React não se mapeiam diretamente para os eventos nativos do navegador. Por exemplo, em onMouseLeave
, e.nativeEvent
apontará para um evento mouseout
. O mapeamento específico não faz parte da API pública e pode mudar no futuro. Se você precisar do evento do navegador subjacente por algum motivo, leia-o de e.nativeEvent
.
Propriedades
Os objetos de evento React implementam algumas das propriedades Event
padrão:
bubbles
: Um booleano. Retorna se o evento se propaga pelo DOM.cancelable
: Um booleano. Retorna se o evento pode ser cancelado.currentTarget
: Um nó DOM. Retorna o nó ao qual o manipulador atual está anexado na árvore React.defaultPrevented
: Um booleano. Retorna sepreventDefault
foi chamado.eventPhase
: Um número. Retorna em qual fase o evento está no momento.isTrusted
: Um booleano. Retorna se o evento foi iniciado pelo usuário.target
: Um nó DOM. Retorna o nó em que o evento ocorreu (que pode ser um filho distante).timeStamp
: Um número. Retorna o tempo em que o evento ocorreu.
Além disso, os objetos de evento React fornecem essas propriedades:
nativeEvent
: UmEvent
DOM. O objeto de evento original do navegador.
Métodos
Os objetos de evento React implementam alguns dos métodos Event
padrão:
preventDefault()
: Impede a ação padrão do navegador para o evento.stopPropagation()
: Interrompe a propagação do evento pela árvore React.
Além disso, os objetos de evento React fornecem esses métodos:
isDefaultPrevented()
: Retorna um valor booleano indicando sepreventDefault
foi chamado.isPropagationStopped()
: Retorna um valor booleano indicando sestopPropagation
foi chamado.persist()
: Não usado com React DOM. Com React Native, chame isso para ler as propriedades do evento após o evento.isPersistent()
: Não usado com React DOM. Com React Native, retorna sepersist
foi chamado.
Ressalvas
- Os valores de
currentTarget
,eventPhase
,target
etype
refletem os valores que seu código React espera. Por baixo dos panos, React anexa manipuladores de eventos na raiz, mas isso não é refletido em objetos de evento React. Por exemplo,e.currentTarget
pode não ser o mesmo que oe.nativeEvent.currentTarget
subjacente. Para eventos polyfilled,e.type
(tipo de evento React) pode diferir dee.nativeEvent.type
(tipo subjacente).
Função do manipulador AnimationEvent
Um tipo de manipulador de eventos para os eventos animação CSS.
<div
onAnimationStart={e => console.log('onAnimationStart')}
onAnimationIteration={e => console.log('onAnimationIteration')}
onAnimationEnd={e => console.log('onAnimationEnd')}
/>
Parâmetros
e
: Um objeto de evento React com estas propriedades extrasAnimationEvent
:
Função do manipulador ClipboardEvent
Um tipo de manipulador de eventos para os eventos da API Clipboard.
<input
onCopy={e => console.log('onCopy')}
onCut={e => console.log('onCut')}
onPaste={e => console.log('onPaste')}
/>
Parâmetros
e
: Um objeto de evento React com estas propriedades extrasClipboardEvent
:
Função do manipulador CompositionEvent
Um tipo de manipulador de eventos para os eventos do editor de método de entrada (IME).
<input
onCompositionStart={e => console.log('onCompositionStart')}
onCompositionUpdate={e => console.log('onCompositionUpdate')}
onCompositionEnd={e => console.log('onCompositionEnd')}
/>
Parâmetros
e
: Um objeto de evento React com estas propriedades extrasCompositionEvent
:
Função do manipulador DragEvent
Um tipo de manipulador de eventos para os eventos da API HTML Drag and Drop.
<>
<div
draggable={true}
onDragStart={e => console.log('onDragStart')}
onDragEnd={e => console.log('onDragEnd')}
>
Origem da arrastada
</div>
<div
onDragEnter={e => console.log('onDragEnter')}
onDragLeave={e => console.log('onDragLeave')}
onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}
onDrop={e => console.log('onDrop')}
>
Alvo da soltura
</div>
</>
Parâmetros
-
e
: Um objeto de evento React com estas propriedades extrasDragEvent
:-
Ele também inclui as propriedades
MouseEvent
herdadas:
Ele também inclui as propriedades
UIEvent
herdadas: -
Função do manipulador FocusEvent
Um tipo de manipulador de eventos para os eventos de foco.
<input
onFocus={e => console.log('onFocus')}
onBlur={e => console.log('onBlur')}
/>
Parâmetros
-
e
: Um objeto de evento React com estas propriedades extrasFocusEvent
:Ele também inclui as propriedades
UIEvent
herdadas:
Função do manipulador Event
Um tipo de manipulador de eventos para eventos genéricos.
Parâmetros
e
: Um objeto de evento React sem propriedades adicionais.
Função do manipulador InputEvent
Um tipo de manipulador de eventos para o evento onBeforeInput
.
<input onBeforeInput={e => console.log('onBeforeInput')} />
Parâmetros
e
: Um objeto de evento React com estas propriedades extrasInputEvent
:
Função do manipulador KeyboardEvent
Um tipo de manipulador de eventos para eventos de teclado.
<input
onKeyDown={e => console.log('onKeyDown')}
onKeyUp={e => console.log('onKeyUp')}
/>
Parâmetros
-
e
: Um objeto de evento React com estas propriedades extrasKeyboardEvent
:altKey
charCode
code
ctrlKey
getModifierState(key)
key
keyCode
locale
metaKey
location
repeat
shiftKey
which
Ele também inclui as propriedades
UIEvent
herdadas:
Função do manipulador MouseEvent
Um tipo de manipulador de eventos para eventos de mouse.
<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')}
/>
Parâmetros
-
e
: Um objeto de evento React com estas propriedades extrasMouseEvent
:altKey
button
buttons
ctrlKey
clientX
clientY
getModifierState(key)
metaKey
movementX
movementY
pageX
pageY
relatedTarget
screenX
screenY
shiftKey
Ele também inclui as propriedades
UIEvent
herdadas:
Função do manipulador PointerEvent
Um tipo de manipulador de eventos para eventos de ponteiro.
<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')}
/>
Parâmetros
-
e
: Um objeto de evento React com estas propriedades extrasPointerEvent
:Ele também inclui as propriedades
MouseEvent
herdadas:altKey
button
buttons
ctrlKey
clientX
clientY
getModifierState(key)
metaKey
movementX
movementY
pageX
pageY
relatedTarget
screenX
screenY
shiftKey
Ele também inclui as propriedades herdadas do
UIEvent
:
Função manipuladora de eventos TouchEvent
Um tipo de manipulador de eventos para eventos de toque.
<div
onTouchStart={e => console.log('onTouchStart')}
onTouchMove={e => console.log('onTouchMove')}
onTouchEnd={e => console.log('onTouchEnd')}
onTouchCancel={e => console.log('onTouchCancel')}
/>
Parâmetros
-
e
: Um objeto de evento React com estas propriedades extras doTouchEvent
:Ele também inclui as propriedades herdadas do
UIEvent
:
Função manipuladora do evento TransitionEvent
Um tipo de manipulador de eventos para os eventos de transição CSS.
<div
onTransitionEnd={e => console.log('onTransitionEnd')}
/>
Parâmetros
e
: Um objeto de evento React com estas propriedades extras doTransitionEvent
:
Função manipuladora de eventos UIEvent
Um tipo de manipulador de eventos para eventos de UI genéricos.
<div
onScroll={e => console.log('onScroll')}
/>
Parâmetros
e
: Um objeto de evento React com estas propriedades extras doUIEvent
:
Função manipuladora de eventos WheelEvent
Um tipo de manipulador de eventos para o evento onWheel
.
<div
onWheel={e => console.log('onWheel')}
/>
Parâmetros
-
e
: Um objeto de evento React com estas propriedades extras doWheelEvent
:Ele também inclui as propriedades herdadas do
MouseEvent
:altKey
button
buttons
ctrlKey
clientX
clientY
getModifierState(key)
metaKey
movementX
movementY
pageX
pageY
relatedTarget
screenX
screenY
shiftKey
Ele também inclui as propriedades herdadas do
UIEvent
:
Uso
Aplicando estilos CSS
No React, você especifica uma classe CSS com className
. Ele funciona como o atributo class
em HTML:
<img className="avatar" />
Então você escreve as regras CSS correspondentes em um arquivo CSS separado:
/* No seu CSS */
.avatar {
border-radius: 50%;
}
O React não prescreve como você adiciona arquivos CSS. No caso mais simples, você adicionará uma tag <link>
ao seu HTML. Se você usar uma ferramenta de build ou um framework, consulte sua documentação para aprender como adicionar um arquivo CSS ao seu projeto.
Às vezes, os valores de estilo dependem de dados. Use o atributo style
para passar alguns estilos dinamicamente:
<img
className="avatar"
style={{
width: user.imageSize,
height: user.imageSize
}}
/>
No exemplo acima, style={{}}
não é uma sintaxe especial, mas um objeto {}
regular dentro da style={ }
chaves JSX. Recomendamos usar o atributo style
apenas quando seus estilos dependem de variáveis 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 }} /> ); }
Deep Dive
Para aplicar classes CSS condicionalmente, você precisa produzir a string className
você mesmo usando JavaScript.
Por exemplo, className={'row ' + (isSelected ? 'selected': '')}
produzirá className="row"
ou className="row selected"
dependendo se isSelected
é true
.
Para tornar isso mais legível, você pode usar uma pequena biblioteca auxiliar como classnames
:
import cn from 'classnames';
function Row({ isSelected }) {
return (
<div className={cn('row', isSelected && 'selected')}>
...
</div>
);
}
É especialmente conveniente se você tiver várias classes condicionais:
import cn from 'classnames';
function Row({ isSelected, size }) {
return (
<div className={cn('row', {
selected: isSelected,
large: size === 'large',
small: size === 'small',
})}>
...
</div>
);
}
Manipulando um nó DOM com uma ref
Às vezes, você precisará obter o nó DOM do navegador associado a uma tag em JSX. Por exemplo, se você deseja focar em um <input>
quando um botão é clicado, você precisa chamar focus()
no nó DOM <input>
do navegador.
Para obter o nó DOM do navegador para uma tag, declare uma ref e passe-a como o atributo ref
para essa tag:
import { useRef } from 'react';
export default function Form() {
const inputRef = useRef(null);
// ...
return (
<input ref={inputRef} />
// ...
O React colocará o nó DOM em inputRef.current
depois que ele for renderizado na tela.
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> </> ); }
Leia mais sobre manipulação de DOM com refs e verifique mais exemplos.
Para casos de uso mais avançados, o atributo ref
também aceita uma função callback.
Definindo perigosamente o HTML interno
Você pode passar uma string HTML bruta para um elemento da seguinte forma:
const markup = { __html: '<p>some raw html</p>' };
return <div dangerouslySetInnerHTML={markup} />;
Isto é perigoso. Como acontece com a propriedade innerHTML
DOM subjacente, você deve ter extrema cautela! A menos que a marcação seja proveniente de uma fonte totalmente confiável, é trivial introduzir uma vulnerabilidade XSS dessa maneira.
Por exemplo, se você usar uma biblioteca Markdown que converte Markdown em HTML, você confia que seu analisador não contenha bugs, e o usuário só vê sua própria entrada, você pode exibir o HTML resultante assim:
import { Remarkable } from 'remarkable'; const md = new Remarkable(); function renderMarkdownToHTML(markdown) { // Isto é SOMENTE seguro porque o HTML de saída // é mostrado para o mesmo usuário e porque você // confia que este analisador Markdown não tem bugs. const renderedHTML = md.render(markdown); return {__html: renderedHTML}; } export default function MarkdownPreview({ markdown }) { const markup = renderMarkdownToHTML(markdown); return <div dangerouslySetInnerHTML={markup} />; }
O objeto {__html}
deve ser criado o mais próximo possível de onde o HTML é gerado, como o exemplo acima faz na função renderMarkdownToHTML
. Isso garante que todo o HTML bruto que está sendo usado em seu código seja explicitamente marcado como tal e que apenas as variáveis que você espera que contenham HTML sejam passadas para dangerouslySetInnerHTML
. Não é recomendado criar o objeto inline como <div dangerouslySetInnerHTML={{__html: markup}} />
.
Para ver por que renderizar HTML arbitrário é perigoso, substitua o código acima por isto:
const post = {
// Imagine que este conteúdo está armazenado no banco de dados.
content: `<img src="" onerror='alert("você foi hackeado")'>`
};
export default function MarkdownPreview() {
// 🔴 FURO DE SEGURANÇA: passando uma entrada não confiável para dangerouslySetInnerHTML
const markup = { __html: post.content };
return <div dangerouslySetInnerHTML={markup} />;
}
O código incorporado no HTML será executado. Um hacker poderia usar este furo de segurança para roubar informações do usuário ou realizar ações em seu nome. Use dangerouslySetInnerHTML
apenas com dados confiáveis e sanitizados.
Manipulando eventos de mouse
Este exemplo mostra alguns eventos de mouse comuns e quando eles são disparados.
export default function MouseExample() { return ( <div onMouseEnter={e => console.log('onMouseEnter (pai)')} onMouseLeave={e => console.log('onMouseLeave (pai)')} > <button onClick={e => console.log('onClick (primeiro botão)')} onMouseDown={e => console.log('onMouseDown (primeiro botão)')} onMouseEnter={e => console.log('onMouseEnter (primeiro botão)')} onMouseLeave={e => console.log('onMouseLeave (primeiro botão)')} onMouseOver={e => console.log('onMouseOver (primeiro botão)')} onMouseUp={e => console.log('onMouseUp (primeiro botão)')} > Primeiro botão </button> <button onClick={e => console.log('onClick (segundo botão)')} onMouseDown={e => console.log('onMouseDown (segundo botão)')} onMouseEnter={e => console.log('onMouseEnter (segundo botão)')} onMouseLeave={e => console.log('onMouseLeave (segundo botão)')} onMouseOver={e => console.log('onMouseOver (segundo botão)')} onMouseUp={e => console.log('onMouseUp (segundo botão)')} > Segundo botão </button> </div> ); }
Manipulando eventos de ponteiro
Este exemplo mostra alguns eventos de ponteiro comuns e quando eles são disparados.
export default function PointerExample() { return ( <div onPointerEnter={e => console.log('onPointerEnter (pai)')} onPointerLeave={e => console.log('onPointerLeave (pai)')} style={{ padding: 20, backgroundColor: '#ddd' }} > <div onPointerDown={e => console.log('onPointerDown (primeiro filho)')} onPointerEnter={e => console.log('onPointerEnter (primeiro filho)')} onPointerLeave={e => console.log('onPointerLeave (primeiro filho)')} onPointerMove={e => console.log('onPointerMove (primeiro filho)')} onPointerUp={e => console.log('onPointerUp (primeiro filho)')} style={{ padding: 20, backgroundColor: 'lightyellow' }} > Primeiro filho </div> <div onPointerDown={e => console.log('onPointerDown (segundo filho)')} onPointerEnter={e => console.log('onPointerEnter (segundo filho)')} onPointerLeave={e => console.log('onPointerLeave (segundo filho)')} onPointerMove={e => console.log('onPointerMove (segundo filho)')} onPointerUp={e => console.log('onPointerUp (segundo filho)')} style={{ padding: 20, backgroundColor: 'lightblue' }} > Segundo filho </div> </div> ); }
Manipulando eventos de foco
No React, eventos de foco propagam. Você pode usar o currentTarget
e relatedTarget
para diferenciar se os eventos de foco ou desfoque se originaram de fora do elemento pai. O exemplo mostra como detectar o foco de um filho, o foco do elemento pai e como detectar a entrada ou saída do foco de toda a subárvore.
export default function FocusExample() { return ( <div tabIndex={1} onFocus={(e) => { if (e.currentTarget === e.target) { console.log('foco no pai'); } else { console.log('foco no filho', e.target.name); } if (!e.currentTarget.contains(e.relatedTarget)) { // Não é acionado ao trocar o foco entre os filhos console.log('foco entrou no pai'); } }} onBlur={(e) => { if (e.currentTarget === e.target) { console.log('pai sem foco'); } else { console.log('filho sem foco', e.target.name); } if (!e.currentTarget.contains(e.relatedTarget)) { // Não é acionado ao trocar o foco entre os filhos console.log('foco deixou o pai'); } }} > <label> Primeiro nome: <input name="firstName" /> </label> <label> Sobrenome: <input name="lastName" /> </label> </div> ); }
Manipulando eventos de teclado
Este exemplo mostra alguns eventos de teclado comuns e quando eles são disparados.
export default function KeyboardExample() { return ( <label> Primeiro nome: <input name="firstName" onKeyDown={e => console.log('onKeyDown:', e.key, e.code)} onKeyUp={e => console.log('onKeyUp:', e.key, e.code)} /> </label> ); }