diff --git a/src/content/reference/react/useState.md b/src/content/reference/react/useState.md index 48d96f8ee..cab96d1f7 100644 --- a/src/content/reference/react/useState.md +++ b/src/content/reference/react/useState.md @@ -4,7 +4,7 @@ title: useState -`useState` is a React Hook that lets you add a [state variable](/learn/state-a-components-memory) to your component. +`useState` é um Hook do React que permite adicionar uma [variável de estado](/learn/state-a-components-memory) ao seu componente. ```js const [state, setState] = useState(initialState) @@ -16,140 +16,140 @@ const [state, setState] = useState(initialState) --- -## Reference {/*reference*/} +## Referência {/*reference*/} ### `useState(initialState)` {/*usestate*/} -Call `useState` at the top level of your component to declare a [state variable.](/learn/state-a-components-memory) +Chame `useState` no nível superior do seu componente para declarar uma [variável de estado.](/learn/state-a-components-memory) ```js import { useState } from 'react'; -function MyComponent() { - const [age, setAge] = useState(28); - const [name, setName] = useState('Taylor'); - const [todos, setTodos] = useState(() => createTodos()); +function MeuComponente() { + const [idade, setIdade] = useState(28); + const [nome, setNome] = useState('Taylor'); + const [tarefas, setTarefas] = useState(() => criarTarefas()); // ... ``` -The convention is to name state variables like `[something, setSomething]` using [array destructuring.](https://javascript.info/destructuring-assignment) +A convenção é nomear variáveis de estado como `[algo, setAlgo]` usando [desestruturação de array.](https://javascript.info/destructuring-assignment) -[See more examples below.](#usage) +[Veja mais exemplos abaixo.](#usage) -#### Parameters {/*parameters*/} +#### Parâmetros {/*parameters*/} -* `initialState`: The value you want the state to be initially. It can be a value of any type, but there is a special behavior for functions. This argument is ignored after the initial render. - * If you pass a function as `initialState`, it will be treated as an _initializer function_. It should be pure, should take no arguments, and should return a value of any type. React will call your initializer function when initializing the component, and store its return value as the initial state. [See an example below.](#avoiding-recreating-the-initial-state) +* `initialState`: O valor que você quer que o estado tenha inicialmente. Pode ser um valor de qualquer tipo, mas há um comportamento especial para funções. Este argumento é ignorado após a renderização inicial. + * Se você passar uma função como `initialState`, ela será tratada como uma _função inicializadora_. Ela deve ser pura, não deve receber argumentos e deve retornar um valor de qualquer tipo. O React chamará sua função inicializadora ao inicializar o componente e armazenará seu valor de retorno como o estado inicial. [Veja um exemplo abaixo.](#avoiding-recreating-the-initial-state) -#### Returns {/*returns*/} +#### Retornos {/*returns*/} -`useState` returns an array with exactly two values: +`useState` retorna um array com exatamente dois valores: -1. The current state. During the first render, it will match the `initialState` you have passed. -2. The [`set` function](#setstate) that lets you update the state to a different value and trigger a re-render. +1. O estado atual. Durante a primeira renderização, ele corresponderá ao `initialState` que você passou. +2. A [função `set`](#setstate) que permite atualizar o estado para um valor diferente e acionar uma nova renderização. -#### Caveats {/*caveats*/} +#### Ressalvas {/*caveats*/} -* `useState` is a Hook, so you can only call it **at the top level of your component** or your own Hooks. You can't call it inside loops or conditions. If you need that, extract a new component and move the state into it. -* In Strict Mode, React will **call your initializer function twice** in order to [help you find accidental impurities.](#my-initializer-or-updater-function-runs-twice) This is development-only behavior and does not affect production. If your initializer function is pure (as it should be), this should not affect the behavior. The result from one of the calls will be ignored. +* `useState` é um Hook, então você só pode chamá-lo **no nível superior do seu componente** ou em seus próprios Hooks. Você não pode chamá-lo dentro de loops ou condições. Se precisar disso, extraia um novo componente e mova o estado para ele. +* No Modo Estrito, o React chamará sua função inicializadora duas vezes para [ajudar você a encontrar impurezas acidentais.](#my-initializer-or-updater-function-runs-twice) Este é um comportamento apenas de desenvolvimento e não afeta a produção. Se sua função inicializadora for pura (como deveria ser), isso não afetará o comportamento. O resultado de uma das chamadas será ignorado. --- -### `set` functions, like `setSomething(nextState)` {/*setstate*/} +### Funções `set`, como `setAlgo(proximoEstado)` {/*setstate*/} -The `set` function returned by `useState` lets you update the state to a different value and trigger a re-render. You can pass the next state directly, or a function that calculates it from the previous state: +A função `set` retornada por `useState` permite atualizar o estado para um valor diferente e acionar uma nova renderização. Você pode passar o próximo estado diretamente ou uma função que o calcule a partir do estado anterior: ```js -const [name, setName] = useState('Edward'); +const [nome, setNome] = useState('Edward'); function handleClick() { - setName('Taylor'); - setAge(a => a + 1); + setNome('Taylor'); + setIdade(i => i + 1); // ... ``` -#### Parameters {/*setstate-parameters*/} +#### Parâmetros {/*setstate-parameters*/} -* `nextState`: The value that you want the state to be. It can be a value of any type, but there is a special behavior for functions. - * If you pass a function as `nextState`, it will be treated as an _updater function_. It must be pure, should take the pending state as its only argument, and should return the next state. React will put your updater function in a queue and re-render your component. During the next render, React will calculate the next state by applying all of the queued updaters to the previous state. [See an example below.](#updating-state-based-on-the-previous-state) +* `proximoEstado`: O valor que você quer que o estado seja. Pode ser um valor de qualquer tipo, mas há um comportamento especial para funções. + * Se você passar uma função como `proximoEstado`, ela será tratada como uma _função atualizadora_. Ela deve ser pura, deve receber o estado pendente como seu único argumento e deve retornar o próximo estado. O React colocará sua função atualizadora em uma fila e renderizará novamente seu componente. Durante a próxima renderização, o React calculará o próximo estado aplicando todas as atualizações enfileiradas ao estado anterior. [Veja um exemplo abaixo.](#updating-state-based-on-the-previous-state) -#### Returns {/*setstate-returns*/} +#### Retornos {/*setstate-returns*/} -`set` functions do not have a return value. +As funções `set` não têm valor de retorno. -#### Caveats {/*setstate-caveats*/} +#### Ressalvas {/*setstate-caveats*/} -* The `set` function **only updates the state variable for the *next* render**. If you read the state variable after calling the `set` function, [you will still get the old value](#ive-updated-the-state-but-logging-gives-me-the-old-value) that was on the screen before your call. +* A função `set` **apenas atualiza a variável de estado para a *próxima* renderização**. Se você ler a variável de estado após chamar a função `set`, [você ainda obterá o valor antigo](#ive-updated-the-state-but-logging-gives-me-the-old-value) que estava na tela antes da sua chamada. -* If the new value you provide is identical to the current `state`, as determined by an [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) comparison, React will **skip re-rendering the component and its children.** This is an optimization. Although in some cases React may still need to call your component before skipping the children, it shouldn't affect your code. +* Se o novo valor que você fornecer for idêntico ao `state` atual, determinado por uma comparação [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is), o React **ignorará a renderização do componente e seus filhos**. Esta é uma otimização. Embora em alguns casos o React ainda possa precisar chamar seu componente antes de ignorar os filhos, isso não deve afetar seu código. -* React [batches state updates.](/learn/queueing-a-series-of-state-updates) It updates the screen **after all the event handlers have run** and have called their `set` functions. This prevents multiple re-renders during a single event. In the rare case that you need to force React to update the screen earlier, for example to access the DOM, you can use [`flushSync`.](/reference/react-dom/flushSync) +* O React [agrupa atualizações de estado.](/learn/queueing-a-series-of-state-updates) Ele atualiza a tela **depois que todos os manipuladores de eventos foram executados** e chamaram suas funções `set`. Isso evita múltiplas renderizações durante um único evento. No raro caso em que você precise forçar o React a atualizar a tela mais cedo, por exemplo, para acessar o DOM, você pode usar [`flushSync`.](/reference/react-dom/flushSync) -* Calling the `set` function *during rendering* is only allowed from within the currently rendering component. React will discard its output and immediately attempt to render it again with the new state. This pattern is rarely needed, but you can use it to **store information from the previous renders**. [See an example below.](#storing-information-from-previous-renders) +* Chamar a função `set` *durante a renderização* só é permitido dentro do componente atualmente em renderização. O React descartará sua saída e tentará imediatamente renderizá-lo novamente com o novo estado. Este padrão raramente é necessário, mas você pode usá-lo para **armazenar informações das renderizações anteriores**. [Veja um exemplo abaixo.](#storing-information-from-previous-renders) -* In Strict Mode, React will **call your updater function twice** in order to [help you find accidental impurities.](#my-initializer-or-updater-function-runs-twice) This is development-only behavior and does not affect production. If your updater function is pure (as it should be), this should not affect the behavior. The result from one of the calls will be ignored. +* No Modo Estrito, o React chamará sua função atualizadora duas vezes para [ajudar você a encontrar impurezas acidentais.](#my-initializer-or-updater-function-runs-twice) Este é um comportamento apenas de desenvolvimento e não afeta a produção. Se sua função atualizadora for pura (como deveria ser), isso não afetará o comportamento. O resultado de uma das chamadas será ignorado. --- -## Usage {/*usage*/} +## Uso {/*usage*/} -### Adding state to a component {/*adding-state-to-a-component*/} +### Adicionando estado a um componente {/*adding-state-to-a-component*/} -Call `useState` at the top level of your component to declare one or more [state variables.](/learn/state-a-components-memory) +Chame `useState` no nível superior do seu componente para declarar uma ou mais [variáveis de estado.](/learn/state-a-components-memory) -```js [[1, 4, "age"], [2, 4, "setAge"], [3, 4, "42"], [1, 5, "name"], [2, 5, "setName"], [3, 5, "'Taylor'"]] +```js [[1, 4, "idade"], [2, 4, "setIdade"], [3, 4, "42"], [1, 5, "nome"], [2, 5, "setNome"], [3, 5, "'Taylor'"]] import { useState } from 'react'; -function MyComponent() { - const [age, setAge] = useState(42); - const [name, setName] = useState('Taylor'); +function MeuComponente() { + const [idade, setIdade] = useState(42); + const [nome, setNome] = useState('Taylor'); // ... ``` -The convention is to name state variables like `[something, setSomething]` using [array destructuring.](https://javascript.info/destructuring-assignment) +A convenção é nomear variáveis de estado como `[algo, setAlgo]` usando [desestruturação de array.](https://javascript.info/destructuring-assignment) -`useState` returns an array with exactly two items: +`useState` retorna um array com exatamente dois itens: -1. The current state of this state variable, initially set to the initial state you provided. -2. The `set` function that lets you change it to any other value in response to interaction. +1. O estado atual desta variável de estado, inicialmente definido como o estado inicial que você forneceu. +2. A função `set` que permite alterá-lo para qualquer outro valor em resposta à interação. -To update what’s on the screen, call the `set` function with some next state: +Para atualizar o que está na tela, chame a função `set` com algum estado seguinte: -```js [[2, 2, "setName"]] +```js [[2, 2, "setNome"]] function handleClick() { - setName('Robin'); + setNome('Robin'); } ``` -React will store the next state, render your component again with the new values, and update the UI. +O React armazenará o próximo estado, renderizará seu componente novamente com os novos valores e atualizará a UI. -Calling the `set` function [**does not** change the current state in the already executing code](#ive-updated-the-state-but-logging-gives-me-the-old-value): +Chamar a função `set` [**não** altera o estado atual no código já em execução](#ive-updated-the-state-but-logging-gives-me-the-old-value): ```js {3} function handleClick() { - setName('Robin'); - console.log(name); // Still "Taylor"! + setNome('Robin'); + console.log(nome); // Ainda "Taylor"! } ``` -It only affects what `useState` will return starting from the *next* render. +Isso apenas afeta o que `useState` retornará a partir da *próxima* renderização. - + -#### Counter (number) {/*counter-number*/} +#### Contador (número) {/*counter-number*/} -In this example, the `count` state variable holds a number. Clicking the button increments it. +Neste exemplo, a variável de estado `count` contém um número. Clicar no botão o incrementa. ```js import { useState } from 'react'; -export default function Counter() { +export default function Contador() { const [count, setCount] = useState(0); function handleClick() { @@ -158,7 +158,7 @@ export default function Counter() { return ( ); } @@ -168,17 +168,17 @@ export default function Counter() { -#### Text field (string) {/*text-field-string*/} +#### Campo de texto (string) {/*text-field-string*/} -In this example, the `text` state variable holds a string. When you type, `handleChange` reads the latest input value from the browser input DOM element, and calls `setText` to update the state. This allows you to display the current `text` below. +Neste exemplo, a variável de estado `text` contém uma string. Quando você digita, `handleChange` lê o último valor de entrada do elemento DOM de entrada do navegador e chama `setText` para atualizar o estado. Isso permite exibir o `text` atual abaixo. ```js import { useState } from 'react'; -export default function MyInput() { - const [text, setText] = useState('hello'); +export default function MeuInput() { + const [text, setText] = useState('olá'); function handleChange(e) { setText(e.target.value); @@ -187,9 +187,9 @@ export default function MyInput() { return ( <> -

You typed: {text}

- ); @@ -200,16 +200,16 @@ export default function MyInput() { -#### Checkbox (boolean) {/*checkbox-boolean*/} +#### Caixa de seleção (booleano) {/*checkbox-boolean*/} -In this example, the `liked` state variable holds a boolean. When you click the input, `setLiked` updates the `liked` state variable with whether the browser checkbox input is checked. The `liked` variable is used to render the text below the checkbox. +Neste exemplo, a variável de estado `liked` contém um booleano. Quando você clica na entrada, `setLiked` atualiza a variável de estado `liked` com base no estado da caixa de seleção do navegador. A variável `liked` é usada para renderizar o texto abaixo da caixa de seleção. ```js import { useState } from 'react'; -export default function MyCheckbox() { +export default function MinhaCaixaSelecao() { const [liked, setLiked] = useState(true); function handleChange(e) { @@ -224,9 +224,9 @@ export default function MyCheckbox() { checked={liked} onChange={handleChange} /> - I liked this + Eu gostei disso -

You {liked ? 'liked' : 'did not like'} this.

+

Você {liked ? 'gostou' : 'não gostou'} disso.

); } @@ -236,29 +236,29 @@ export default function MyCheckbox() { -#### Form (two variables) {/*form-two-variables*/} +#### Formulário (duas variáveis) {/*form-two-variables*/} -You can declare more than one state variable in the same component. Each state variable is completely independent. +Você pode declarar mais de uma variável de estado no mesmo componente. Cada variável de estado é completamente independente. ```js import { useState } from 'react'; -export default function Form() { - const [name, setName] = useState('Taylor'); - const [age, setAge] = useState(42); +export default function Formulario() { + const [nome, setNome] = useState('Taylor'); + const [idade, setIdade] = useState(42); return ( <> setName(e.target.value)} + value={nome} + onChange={e => setNome(e.target.value)} /> - -

Hello, {name}. You are {age}.

+

Olá, {nome}. Você tem {idade} anos.

); } @@ -276,86 +276,86 @@ button { display: block; margin-top: 10px; } --- -### Updating state based on the previous state {/*updating-state-based-on-the-previous-state*/} +### Atualizando o estado com base no estado anterior {/*updating-state-based-on-the-previous-state*/} -Suppose the `age` is `42`. This handler calls `setAge(age + 1)` three times: +Suponha que `idade` seja 42. Este manipulador chama `setIdade(idade + 1)` três vezes: ```js function handleClick() { - setAge(age + 1); // setAge(42 + 1) - setAge(age + 1); // setAge(42 + 1) - setAge(age + 1); // setAge(42 + 1) + setIdade(idade + 1); // setIdade(42 + 1) + setIdade(idade + 1); // setIdade(42 + 1) + setIdade(idade + 1); // setIdade(42 + 1) } ``` -However, after one click, `age` will only be `43` rather than `45`! This is because calling the `set` function [does not update](/learn/state-as-a-snapshot) the `age` state variable in the already running code. So each `setAge(age + 1)` call becomes `setAge(43)`. +No entanto, após um clique, `idade` será apenas 43 em vez de 45! Isso ocorre porque chamar a função `set` [não atualiza](/learn/state-as-a-snapshot) a variável de estado `idade` no código já em execução. Então, cada chamada `setIdade(idade + 1)` se torna `setIdade(43)`. -To solve this problem, **you may pass an *updater function*** to `setAge` instead of the next state: +Para resolver esse problema, **você pode passar uma *função atualizadora*** para `setIdade` em vez do próximo estado: ```js [[1, 2, "a", 0], [2, 2, "a + 1"], [1, 3, "a", 0], [2, 3, "a + 1"], [1, 4, "a", 0], [2, 4, "a + 1"]] function handleClick() { - setAge(a => a + 1); // setAge(42 => 43) - setAge(a => a + 1); // setAge(43 => 44) - setAge(a => a + 1); // setAge(44 => 45) + setIdade(a => a + 1); // setIdade(42 => 43) + setIdade(a => a + 1); // setIdade(43 => 44) + setIdade(a => a + 1); // setIdade(44 => 45) } ``` -Here, `a => a + 1` is your updater function. It takes the pending state and calculates the next state from it. +Aqui, `a => a + 1` é sua função atualizadora. Ela recebe o estado pendente e calcula o próximo estado a partir dele. -React puts your updater functions in a [queue.](/learn/queueing-a-series-of-state-updates) Then, during the next render, it will call them in the same order: +O React coloca suas funções atualizadoras em uma [fila.](/learn/queueing-a-series-of-state-updates) Em seguida, durante a próxima renderização, ele as chamará na mesma ordem: -1. `a => a + 1` will receive `42` as the pending state and return `43` as the next state. -1. `a => a + 1` will receive `43` as the pending state and return `44` as the next state. -1. `a => a + 1` will receive `44` as the pending state and return `45` as the next state. +1. `a => a + 1` receberá `42` como o estado pendente e retornará `43` como o próximo estado. +1. `a => a + 1` receberá `43` como o estado pendente e retornará `44` como o próximo estado. +1. `a => a + 1` receberá `44` como o estado pendente e retornará `45` como o próximo estado. -There are no other queued updates, so React will store `45` as the current state in the end. +Não há outras atualizações enfileiradas, então o React armazenará `45` como o estado atual no final. -By convention, it's common to name the pending state argument for the first letter of the state variable name, like `a` for `age`. However, you may also call it like `prevAge` or something else that you find clearer. +Por convenção, é comum nomear o argumento do estado pendente com a primeira letra do nome da variável de estado, como `a` para `idade`. No entanto, você também pode chamá-lo de `idadeAnterior` ou algo que considere mais claro. -React may [call your updaters twice](#my-initializer-or-updater-function-runs-twice) in development to verify that they are [pure.](/learn/keeping-components-pure) +O React pode [chamar suas atualizações duas vezes](#my-initializer-or-updater-function-runs-twice) no desenvolvimento para verificar se são [puras.](/learn/keeping-components-pure) -#### Is using an updater always preferred? {/*is-using-an-updater-always-preferred*/} +#### Usar sempre uma função atualizadora é preferível? {/*is-using-an-updater-always-preferred*/} -You might hear a recommendation to always write code like `setAge(a => a + 1)` if the state you're setting is calculated from the previous state. There is no harm in it, but it is also not always necessary. +Você pode ouvir uma recomendação para sempre escrever código como `setIdade(a => a + 1)` se o estado que você está definindo for calculado a partir do estado anterior. Não há problema nisso, mas nem sempre é necessário. -In most cases, there is no difference between these two approaches. React always makes sure that for intentional user actions, like clicks, the `age` state variable would be updated before the next click. This means there is no risk of a click handler seeing a "stale" `age` at the beginning of the event handler. +Na maioria dos casos, não há diferença entre essas duas abordagens. O React sempre garante que para ações intencionais do usuário, como cliques, a variável de estado `idade` seria atualizada antes do próximo clique. Isso significa que não há risco de um manipulador de cliques ver um valor "obsoleto" de `idade` no início do manipulador de eventos. -However, if you do multiple updates within the same event, updaters can be helpful. They're also helpful if accessing the state variable itself is inconvenient (you might run into this when optimizing re-renders). +No entanto, se você fizer várias atualizações dentro do mesmo evento, as funções atualizadoras podem ser úteis. Elas também são úteis se acessar a própria variável de estado for inconveniente (você pode encontrar isso ao otimizar re-renderizações). -If you prefer consistency over slightly more verbose syntax, it's reasonable to always write an updater if the state you're setting is calculated from the previous state. If it's calculated from the previous state of some *other* state variable, you might want to combine them into one object and [use a reducer.](/learn/extracting-state-logic-into-a-reducer) +Se você preferir consistência em vez de uma sintaxe um pouco mais verbosa, é razoável sempre escrever uma função atualizadora se o estado que você está definindo for calculado a partir do estado anterior. Se for calculado a partir do estado anterior de alguma *outra* variável de estado, você pode querer combiná-las em um objeto e [usar um reducer.](/learn/extracting-state-logic-into-a-reducer) - + -#### Passing the updater function {/*passing-the-updater-function*/} +#### Passando a função atualizadora {/*passing-the-updater-function*/} -This example passes the updater function, so the "+3" button works. +Este exemplo passa a função atualizadora, então o botão "+3" funciona. ```js import { useState } from 'react'; -export default function Counter() { - const [age, setAge] = useState(42); +export default function Contador() { + const [idade, setIdade] = useState(42); - function increment() { - setAge(a => a + 1); + function incrementar() { + setIdade(a => a + 1); } return ( <> -

Your age: {age}

+

Sua idade: {idade}

); @@ -371,32 +371,32 @@ h1 { display: block; margin: 10px; } -#### Passing the next state directly {/*passing-the-next-state-directly*/} +#### Passando o próximo estado diretamente {/*passing-the-next-state-directly*/} -This example **does not** pass the updater function, so the "+3" button **doesn't work as intended**. +Este exemplo **não** passa a função atualizadora, então o botão "+3" **não funciona como esperado**. ```js import { useState } from 'react'; -export default function Counter() { - const [age, setAge] = useState(42); +export default function Contador() { + const [idade, setIdade] = useState(42); - function increment() { - setAge(age + 1); + function incrementar() { + setIdade(idade + 1); } return ( <> -

Your age: {age}

+

Sua idade: {idade}

); @@ -416,32 +416,32 @@ h1 { display: block; margin: 10px; } --- -### Updating objects and arrays in state {/*updating-objects-and-arrays-in-state*/} +### Atualizando objetos e arrays no estado {/*updating-objects-and-arrays-in-state*/} -You can put objects and arrays into state. In React, state is considered read-only, so **you should *replace* it rather than *mutate* your existing objects**. For example, if you have a `form` object in state, don't mutate it: +Você pode colocar objetos e arrays no estado. No React, o estado é considerado somente leitura, então **você deve *substituí-lo* em vez de *mutar* seus objetos existentes**. Por exemplo, se você tem um objeto `form` no estado, não o mute: ```js -// 🚩 Don't mutate an object in state like this: +// 🚩 Não mute um objeto no estado desta forma: form.firstName = 'Taylor'; ``` -Instead, replace the whole object by creating a new one: +Em vez disso, substitua o objeto inteiro criando um novo: ```js -// ✅ Replace state with a new object +// ✅ Substitua o estado com um novo objeto setForm({ ...form, firstName: 'Taylor' }); ``` -Read [updating objects in state](/learn/updating-objects-in-state) and [updating arrays in state](/learn/updating-arrays-in-state) to learn more. +Leia [atualizando objetos no estado](/learn/updating-objects-in-state) e [atualizando arrays no estado](/learn/updating-arrays-in-state) para saber mais. - + -#### Form (object) {/*form-object*/} +#### Formulário (objeto) {/*form-object*/} -In this example, the `form` state variable holds an object. Each input has a change handler that calls `setForm` with the next state of the entire form. The `{ ...form }` spread syntax ensures that the state object is replaced rather than mutated. +Neste exemplo, a variável de estado `form` contém um objeto. Cada entrada tem um manipulador de alteração que chama `setForm` com o próximo estado de todo o formulário. A sintaxe de propagação `{ ...form }` garante que o objeto de estado seja substituído em vez de mutado. @@ -458,7 +458,7 @@ export default function Form() { return ( <>