Referenciando valores com Refs

Adicionando um ref ao seu componente

Você pode adicionar um ref ao seu componente importando o Hook useRef do React:

import { useRef } from 'react';

Dentro do seu componente, invoque o Hook useRef e passe o valor inicial que você quer referenciar como o único argumento. Por exemplo, aqui está um ref para o valor 0:

const ref = useRef(0);

useRef retorna um objeto assim:

{ 
  current: 0 // o valor que você passou para o useRef
}

Você pode acessar o valor atual daquele ref através da propriedade ref.current. Esse valor é intencionalmente mutável, o que significa que você pode tanto ler quanto escrever sobre ele. É como um bolso secreto do seu componente o qual o React não rastreia. (É isso que o faz uma “saída de emergência” do fluxo de data de mão-única do React—mais sobre isso abaixo!)

Aqui, um botão irá incrementar ref.current a cada clique:

O ref aponta para um número, mas, como state, você pode apontá-lo para qualquer coisa: uma string, um objeto, ou até mesmo uma função. Diferentemente do state, ref é um simples objeto Javascript com a propriedade current que você pode ler e modificar.

Note que o componente não re-renderiza com cada incremento. Assim como state, refs são retidos pelo React entre re-renderizações. Entretanto, alterar o state re-renderiza um componente. Mudar um ref não!

Exemplo: construindo um cronômetro

Você pode combinar refs e state em um único componente. Por exemplo, vamos fazer um cronômetro que o usuário possa iniciar ou parar ao pressionar um botão. Para exibir quanto tempo passou desde que o usuário pressionou “Start”, você precisará rastrear quando o botão Start foi pressionado e qual o horário atual. Essas informações são usadas para renderização, então as manteremos no state:

const [startTime, setStartTime] = useState(null);
const [now, setNow] = useState(null);

Quando o usuário pressionar “Start”, você usará setInterval para atualizar o tempo a cada 10 milissegundos:

Quando o botão “Stop” é pressionado, você precisará cancelar o intervalo existente de forma que ele pare de atualizar a variável now do state.Você pode fazer isso invocando ‘clearInterval’, mas você precisará passar o ID do intervalo que foi retornado anteriormente pela invocação do setInterval quando o usuário pressionou Start. Você precisará gravar esse ID do intervalo em algum lugar. Já que o ID do intervalo não é usado para renderização, você pode guardá-lo em um ref:

Quando uma informação é usada para renderização, mantenha-a no state. Quando uma informação é necessária somente por manipuladores de eventos (event handlers) e mudá-la não requer uma re-renderização, usar um ref pode ser mais eficiente.

Diferenças entre refs e state

Talvez você esteja pensando que refs parecem ser menos “rigorosos” que state—você pode mutá-los ao invés de sempre ter que usar uma função de definir state, por exemplo. Mas na maioria dos casos, você irá querer usar state. Refs são uma “válvula de escape” que você não precisará com frequência. Aqui uma comparação entre state e refs:

Aqui um botão contador que foi implementado com state:

Como o valor count é exibido, faz sentido usar um valor de state para ele. Quando o valor do contador é definido com setCount(), React re-renderiza o componente e a tela é atualizada para refletir o novo valor.

Se você tentasse implementar isso com um ref, React nunca re-renderizaria o componente, então você nunca veria o contador mudar! Veja como, ao clicar neste botão, seu texto não é atualizado:

É por isso que ler ref.current durante a renderização leva a um código não confiável. Se você precisar disso, dê preferência ao state.

// Dentro do React
function useRef(initialValue) {
  const [ref, unused] = useState({ current: initialValue });
  return ref;
}

Quando usar refs

Normalmente, você usará um ref quando o seu componente precisa “sair” do React e se comunicar com APIs externas, frequentemente uma API do navegador que não afetará a aparência do componente. Aqui estão algumas destas situações raras:

• Armazenando IDs de temporizadores (timeouts)
• Armazenando e manipulando elementos DOM, que são abordados na próxima página
• Armazenando outros objetos que não são necessários para calcular o JSX.

Se o seu componente precisa armazenar algum valor, mas isso não afeta a lógica de renderização, escolha refs.

Melhores práticas para refs

Seguir esses princípios tornará seus componentes mais previsíveis:

• Trate refs como uma saída de emergência. Refs são úteis quando você trabalha com sistemas externos ou APIs de navegador. Se grande parte da lógica da sua aplicação e fluxo de dados dependem de refs, talvez seja necessário repensar suaa abordagem.
• Não leia nem escreva sobre ref.current durante a renderização. Se alguma informação for necessária durante a renderização, use state. Como o React não sabe quando ref.current muda, até mesmo a leitura durante a renderização torna o comportamento do seu componente difícil de prever. (A única exceção a isso é código como if (!ref.current) ref.current = new Thing(), que define o ref apenas uma vez durante a primeira renderização.)

As limitações do state do React não se aplicam aos refs. Por exemplo, o state age como uma foto instantânea para cada renderização e não atualiza de forma síncrona. Mas quando você altera o valor atual de um ref, ele muda imediatamente:

ref.current = 5;
console.log(ref.current); // 5

Isso é porque o ref em si é um objeto JavaScript normal, e portanto se comporta como um.

Você também não precisa se preocupar em evitar a mutação quando trabalha com um ref. Desde que o objeto que você está mutando não seja usado para renderização, o React não se importa com o que você faz com o ref ou seu conteúdo.

Refs e o DOM

You can point a ref to any value. However, the most common use case for a ref is to access a DOM element. For example, this is handy if you want to focus an input programmatically. When you pass a ref to a ref attribute in JSX, like <div ref={myRef}>, React will put the corresponding DOM element into myRef.current. Once the element is removed from the DOM, React will update myRef.current to be null. You can read more about this in Manipulating the DOM with Refs.