Skip to content

2. Primeiros passos com React

2.1. Exemplo 01: A estrutura de uma aplicação React

2.1.1. O arquivo package.json

O arquivo [package.json] na pasta de exemplos declara as bibliotecas utilizadas e os comandos do projeto:

{
  "name": "examples-react",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "vite --config vite.config.ts",
    "build": "vite build --config vite.config.ts",
    "check": "tsc --noEmit"
  },
  "dependencies": {
    "@tanstack/react-query": "^5.104.0",
    "bootstrap": "^5.3.8",
    "i18next": "^26.4.2",
    "react": "^19.3.0",
    "react-dom": "^19.3.0",
    "react-hook-form": "^7.89.0",
    "react-i18next": "^17.0.15",
    "react-router": "^8.4.0",
    "zustand": "^5.0.15"
  },
  "devDependencies": {
    "@types/react": "^19.2.18",
    "@types/react-dom": "^19.2.7",
    "@vitejs/plugin-react": "^6.1.1",
    "typescript": "~6.0.2",
    "vite": "^8.3.0"
  }
}

Vamos analisar este arquivo:

  • Linha 5: Os arquivos [JavaScript] do projeto são módulos ES ([import] / [export]), que é o padrão atual da linguagem;
  • Linhas 6–10: Os comandos do projeto, executados por [npm run <name>] (ou [npm start] para o comando [start]):
    • [npm start 05-controlled-fields] executa [vite --config vite.config.ts 05-controlled-fields]: o servidor de desenvolvimento do Exemplo 05;
    • [npm run build 05-controlled-fields] executa [vite build ...]: a versão de produção do Exemplo 05, localizada na pasta [05-controlled-fields/dist/];
    • [npm run check] executa o compilador [TypeScript] ([tsc]), que verifica os tipos de TODOS os exemplos sem produzir nada ([--noEmit]);
  • linhas 11–21: as bibliotecas de que a aplicação precisa no navegador: [react] (o núcleo: componentes, estado, hooks) e [react-dom] (exibição em uma página web), [react-router] (o roteador, exemplos 17 e 18), [react-hook-form] (exemplo 08), [zustand] (exemplo 20), [i18next] e [react-i18next] (idiomas, exemplo 21), [@tanstack/react-query] (leitura de dados do servidor, exemplo 24) e [Bootstrap] para a formatação;
  • Linhas 22–28: ferramentas de desenvolvimento: [Vite] ([vite]), seu plugin para [React] ([@vitejs/plugin-react]), o compilador [TypeScript] e as descrições de tipos do [React] para o [TypeScript] ([@types/react], [@types/react-dom]). Elas não fazem parte da aplicação entregue aos usuários.

O prefixo [^] em uma versão ([^19.3.0]) permite que o [npm] instale uma versão mais recente da mesma versão principal (19.x.y); o prefixo [~] ([~6.0.2]) permite apenas correções (6.0.x).

Em um projeto padrão, este arquivo é criado pelo comando [npm create vite@latest project-name -- --template react-ts], que gera uma aplicação [React] completa e pronta para executar. Os exemplos deste curso foram escritos à mão para que vinte e cinco deles coubessem em uma única pasta.

2.1.2. O arquivo vite.config.ts

[Vite] é a ferramenta de build recomendada para uma aplicação [React]: um servidor de desenvolvimento muito rápido e um compilador de produção. Sua configuração, comum a todos os exemplos:

// =========================================================================
// vite.config.ts - a configuração do Vite, comum a todos os exemplos
// -------------------------------------------------------------------------
// O Vite é a ferramenta de build do React: um servidor de desenvolvimento
// (npm start) e um compilador de produção (npm run build). Cada
// exemplo é uma pasta que tem sua própria página index.html; seu
// nome é passado ao Vite, que o transforma na RAIZ da aplicação:
//
//     npm start 05-controlled-fields      ->  vite --config vite.config.ts 05-controlled-fields
//     npm run build 05-controlled-fields  ->  o resultado em 05-controlled-fields/dist/
// =========================================================================

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  // o plugin do React: a sintaxe JSX e o reload "a quente" (uma
  // modificação do código atualiza a página sem perder o estado exibido)
  plugins: [react()],
  server: {
    port: 5173,
    // o PROXY: toda requisição do navegador para /api/... é repassada
    // ao servidor JSON do RdvMedecins (porta 8080). Ele só é usado a partir
    // do exemplo 22 (cf. o capítulo "Conversando com o servidor").
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },
});
  • linhas 9–10 (comentário): o nome do exemplo, fornecido ao comando, torna-se a raiz ([root]) da aplicação: o [Vite] procura ali a página [index.html] e a pasta [public/], e armazena ali o resultado do build ([dist/]);
  • linha 19: o plugin do [React]: ele compila a sintaxe JSX (veja adiante) e ativa o hot reloading: uma alteração no código de um componente é aplicada à página sem recarregá-la, preservando o estado exibido na medida do possível;
  • linha 21: a porta do servidor de desenvolvimento;
  • linhas 25–27: o proxy, que só será usado a partir do Exemplo 22: qualquer requisição do navegador a um endereço que comece por [/api] é encaminhada ao servidor JSON [RdvMedecins]. Voltaremos a isso mais adiante.

2.1.3. O arquivo tsconfig.json

A configuração do [TypeScript] comum a todos os exemplos:

{
  "compilerOptions": {
    "target": "ES2023",
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["vite/client"],
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitReturns": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["*/src", "common", "vite.config.ts"]
}
  • linhas 3–6: código [JavaScript] moderno (ES2023), definições do navegador ([DOM]) e módulos resolvidos como faz a ferramenta de build;
  • linha 7: definições específicas do [Vite] (por exemplo, importar uma folha de estilos, [import './App.css'], é permitido);
  • linha 8: a sintaxe JSX é aceita e compilada para o [React];
  • Linhas 9–13: o modo estrito do [TypeScript] (tipos verificados estritamente, incluindo [null] e [undefined]) e verificações adicionais: uma variável ou um parâmetro não utilizado é relatado como erro;
  • linha 14: uma importação que se aplica apenas a tipos é escrita como [import type { ... }] (ou [import { type X }]): isso informa à ferramenta de build que ela deixa de existir no arquivo [JavaScript] gerado;
  • linha 16: um arquivo chamado JSON pode ser importado como módulo (Exemplo 21);
  • linha 18: o [tsc] apenas verifica os tipos; quem realmente compila o código é o [Vite] (ele simplesmente remove os tipos sem verificá-los: daí o comando [npm run check]);
  • linha 20: os arquivos verificados: os de todos os exemplos.

O editor [VS Code] usa esta configuração: um erro de digitação em um componente ([{titl}] em vez de [{title}]) é sublinhado em vermelho assim que é digitado.

2.1.4. A página index.html

Cada exemplo tem sua própria página HTML. A página do Exemplo 01:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example 01 - a first application</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <!-- a aplicação React é exibida neste elemento (cf. src/main.tsx) -->
  <div id="root"></div>
  <!-- o ponto de entrada: um módulo JavaScript, compilado na hora pelo Vite -->
  <script type="module" src="/src/main.tsx"></script>
</body>
</html>

Esta é a única página que o navegador carregará. Ela é quase vazia:

  • linha 10: o elemento no qual o [React] exibirá a aplicação;
  • linha 12: o ponto de entrada da aplicação, um módulo [TypeScript]. O navegador não entende [TypeScript]: quem compila este arquivo — e os arquivos que ele importa — quando o navegador os solicita é o [Vite].

Aqui não há nenhuma tag [<link>]: as folhas de estilo são importadas pelo código (veja [main.tsx]), e o [Vite] as adiciona à página por conta própria.

2.1.5. O ponto de entrada: main.tsx

// =========================================================================
// 01-first-application/src/main.tsx - o ponto de entrada da aplicação
// -------------------------------------------------------------------------
// O index.html carrega este arquivo. Ele inicia a aplicação React:
//   1. createRoot(element): o React assume o controle do elemento
//      <div id="root"> da página;
//   2. root.render(<App />): ele exibe nele o componente RAIZ, App.
// As folhas de estilo são módulos como quaisquer outros: são importadas.
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App';

// o "!" diz ao TypeScript: este elemento existe (ele está no index.html)
createRoot(document.getElementById('root')!).render(
  // StrictMode: apenas em desenvolvimento, o React faz verificações
  // adicionais (cf. exemplo 13). Ele mesmo não exibe nada.
  <StrictMode>
    <App />
  </StrictMode>,
);

Um arquivo [.tsx] é um arquivo [TypeScript] que contém JSX.

  • Linha 12: a função do [react-dom] que inicia uma aplicação dentro de uma página web;
  • linha 13: a folha de estilos do [Bootstrap]: uma importação sem nome, usada apenas para adicioná-la à página;
  • Linha 14: o componente raiz da aplicação, a função exportada por [App.tsx];
  • linha 17: o [React] assume o controle do elemento [<div id="root">]. [document.getElementById('root')] pode retornar [null] para o [TypeScript]: o [!] afirma que ele existe;
  • linhas 20–22: [render(...)] exibe o componente [App] dentro desse elemento. [<App />] faz parte do JSX: o uso do componente [App] como uma tag. [<StrictMode>] é um componente do [React], que não exibe nada por si só, mas ativa verificações adicionais durante o desenvolvimento (exemplo 13).

2.1.6. Os componentes raiz: App.tsx e App.css

Um componente [React] é uma função:

// =========================================================================
// 01-first-application/src/App.tsx - um primeiro componente
// -------------------------------------------------------------------------
// Um componente React é uma FUNÇÃO, cujo nome começa com letra
// maiúscula, que RETORNA o que deve ser exibido, escrito em JSX: HTML
// dentro do código TypeScript. O React chama essa função para montar a
// página; ele a chama DE NOVO a cada vez que o estado do componente muda, e
// atualiza a página com o novo resultado.
// =========================================================================

import { useState } from 'react';
// uma folha de estilo, importada pelo componente que a utiliza
import './App.css';

// dados "comuns", fora do componente: eles nunca mudam
const title = 'Welcome to React';
const languages = ['TypeScript', 'HTML', 'CSS'];

export default function App() {
  // useState(0): um pedaço de ESTADO, com valor inicial 0. Obtemos seu
  // valor ATUAL (counter) e a função que o altera (setCounter).
  // Chamar setCounter pede ao React que chame App DE NOVO para atualizar
  // a página. Nunca modificamos a página nós mesmos.
  const [counter, setCounter] = useState(0);
  const [time, setTime] = useState(() => new Date().toLocaleTimeString());

  // uma função chamada pelo botão
  function increment() {
    setCounter((n) => n + 1);
    setTime(new Date().toLocaleTimeString());
  }

  // o JSX retornado: { expressão } insere o valor de uma expressão;
  // className substitui o atributo HTML class (uma palavra reservada em JavaScript)
  return (
    <div className="container py-4">
      <h1 className="h3">{title}</h1>
      <p>This page is built in the browser, by React, from index.html, main.tsx and the App component.</p>
      <p>
        It is written in {languages.join(', ')} ({languages.length} languages).
      </p>

      {/* onClick: a função a chamar ao clicar (cf. exemplo 04) */}
      <button className="btn btn-primary" onClick={increment}>
        Click me
      </button>
      <p className="mt-3 counter">
        You clicked {counter} times (last click: {time}).
      </p>
    </div>
  );
}
  • Linha 11: o hook [useState], fornecido pelo [React];
  • linha 13: a folha de estilos do componente;
  • linhas 16–17: dois dados comuns, declarados fora do componente: eles nunca mudam;
  • linha 19: o componente: uma função cujo nome começa com uma letra maiúscula (é assim que o JSX distingue um componente, [<App />], de um elemento HTML, [<div>]). [export default]: é o que o módulo exporta por padrão, importado em [main.tsx] por [import App from './App'];
  • Linha 24: [useState(0)] cria uma variável de estado com valor inicial 0. Ele retorna um array de dois elementos, que “desempacotamos”: o valor atual ([counter]) e a função que o altera ([setCounter]). O estado é armazenado pelo [React]: ele persiste de uma chamada da função para a seguinte;
  • Linha 25: Você pode passar ao [useState] uma função que calcula o valor inicial; ela é chamada apenas na primeira vez que a página é exibida;
  • Linhas 28–30: Uma função chamada pelo botão. Ela não modifica a página; ela altera o estado. [setCounter((n) => n + 1)] calcula o novo valor a partir do antigo. Cada chamada à função [setXxx] instrui o [React] a chamar [App]; o [React] compara o novo resultado com o antigo e atualiza apenas as partes da página que mudaram;
  • linhas 35–51: o JSX retornado, ou seja, o que deve ser exibido:
    • o JSX se parece com o HTML, com algumas diferenças: o atributo [class] é escrito como [className] ([class] é uma palavra reservada do [JavaScript]), cada tag deve ser fechada ([<br />], [<input />]) e toda a estrutura deve ter UM único elemento raiz;
    • Linha 37: [{ expression }] insere o valor de uma expressão [TypeScript]. Ele é escapado: se [title] contivesse [<b>], [<b>] seria exibido sem que a tag fosse interpretada;
    • linha 40: a expressão pode ser qualquer coisa: uma chamada de método, um cálculo;
    • linha 43: um comentário em JSX é escrito como [{/* ... */}];
    • linha 44: clicar no botão chama a função [increment] (veja o Exemplo 04). A própria função é fornecida sem parênteses: [onClick={increment()}] a chamaria imediatamente, durante a exibição;
    • linha 48: o valor atual do estado. Quando o estado muda, [App] é chamado novamente, e este texto muda.

O JSX não é o mesmo que HTML: é uma notação conveniente para chamadas de função. O compilador transforma [<h1 className="h3">{title}</h1>] em uma chamada da forma [jsx('h1', { className: 'h3', children: title })], que cria um objeto descrevendo o elemento. O componente retorna, portanto, uma árvore de objetos (o “DOM virtual”), que o [React] compara com a árvore anterior para determinar o que alterar na página real.

E sua folha de estilos:

1
2
3
4
5
6
/* uma folha de estilo importada por App.tsx; ATENÇÃO: ela se aplica a toda a
   inteira, e não apenas ao componente App (cf. exemplo 10) */
.counter {
  font-weight: bold;
  color: #087ea4;
}

Diferentemente do [Angular] ou do [Vue.js], o [React] não isola os estilos de um componente: uma folha de estilos importada se aplica à página inteira. O Exemplo 10 demonstrará os “módulos CSS”, que restringem uma classe a um único componente.

2.1.7. Execução

No console aberto na pasta [examples-react]:

npm start 01-first-application

O console exibe:

1
2
3
4
5
6
7
> examples-react@1.0.0 start
> vite --config vite.config.ts 01-first-application

  VITE v8.3.1  ready in 264 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Abra a URL http://localhost:5173/ e clique no botão três vezes:

Image

Dois experimentos para experimentar:

  • Altere o texto do título em [App.tsx] e salve o arquivo: a página é atualizada imediatamente, sem precisar recarregá-la, e o contador mantém seu valor. O servidor de desenvolvimento monitora os arquivos, recompila as alterações e notifica o navegador;
  • veja o código-fonte da página (Ctrl-U): você encontrará apenas a página [index.html], quase vazia. A página HTML exibida foi gerada pelo [React] dentro do navegador. Para vê-la, use o inspetor das ferramentas de desenvolvedor (F12, aba Elements) ou a extensão [React Developer Tools], que também exibe os componentes e seu estado.

2.2. Exemplo 02: Estado e valores calculados

O estado está no centro do [React]. Este exemplo calcula o preço de um item com IVA incluído:

// =========================================================================
// 02-state/src/App.tsx - estado, valores calculados, useEffect
// -------------------------------------------------------------------------
// Uma pequena calculadora de preços com IVA incluso:
//   - useState    : um valor de ESTADO; alterá-lo (setXxx) chama o
//                   componente de novo, que monta a página com o novo valor;
//   - um valor CALCULADO a partir do estado NÃO é um estado: é uma
//     simples variável, recalculada a cada chamada do componente;
//   - useMemo     : a mesma coisa, mas o cálculo só é refeito se suas
//                   dependências mudaram (útil para um cálculo custoso);
//   - useEffect   : código executado DEPOIS da exibição, quando alguns
//                   valores mudaram: um "efeito colateral" (agir sobre algo
//                   diferente da página: aqui, o título da aba).
// =========================================================================

import { useEffect, useMemo, useState } from 'react';

// um formatador de valores em euros, à maneira inglesa (€1,234.50)
const euros = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' });

export default function App() {
  const [label, setLabel] = useState('Pen');
  const [priceExclVat, setPriceExclVat] = useState(2.5);
  const [quantity, setQuantity] = useState(1);
  const [vatRate, setVatRate] = useState(20); // em %

  // Valores CALCULADOS: simples constantes, recalculadas a cada
  // chamada do componente. Estão sempre atualizadas, nada a sincronizar
  const totalExclVat = quantity * priceExclVat;
  const vatAmount = (totalExclVat * vatRate) / 100;
  // useMemo(cálculo, [dependências]): mesmo resultado, mas o React só refaz o
  // cálculo se alguma das dependências mudou desde a chamada anterior
  const totalInclVat = useMemo(() => totalExclVat + vatAmount, [totalExclVat, vatAmount]);

  // o histórico dos totais com IVA: depende dos valores SUCESSIVOS do
  // total. O total antigo é mantido no estado; se ele difere do
  // novo, o estado é ajustado DURANTE a chamada do componente (o React
  // então reinicia a chamada imediatamente, antes de exibir qualquer coisa)
  const [history, setHistory] = useState<{ id: number; text: string }[]>([]);
  const [oldTotal, setOldTotal] = useState(totalInclVat);
  if (totalInclVat !== oldTotal) {
    setOldTotal(totalInclVat);
    const text = `${euros.format(oldTotal)} -> ${euros.format(totalInclVat)}`;
    // cada linha tem um número único (id), que a identifica (cf. key, exemplo 03)
    setHistory((h) => [{ id: (h[0]?.id ?? 0) + 1, text }, ...h].slice(0, 5));
  }

  // useEffect(efeito, [dependências]): o efeito é executado DEPOIS da primeira
  // exibição, e depois a cada exibição em que totalInclVat mudou
  useEffect(() => {
    document.title = `Incl. VAT: ${euros.format(totalInclVat)}`;
  }, [totalInclVat]);

  // trocar o item reinicia a quantidade em 1: isso é feito no
  // tratador de evento, onde sabemos POR QUE o estado muda
  function changeLabel(newValue: string) {
    setLabel(newValue);
    setQuantity(1);
  }

  function reset() {
    setLabel('Pen');
    setPriceExclVat(2.5);
    setQuantity(1);
    setVatRate(20);
  }

  return (
    <div className="container py-4">
      <h1 className="h3 mb-3">Example 02 - state and computed values</h1>
      <div className="row g-4">
        <div className="col-md-6">
          <div className="card p-3">
            {/* value + onChange: o campo exibe o estado, e cada tecla digitada o altera (cf. exemplo 05) */}
            <label className="form-label" htmlFor="label">Item</label>
            <input id="label" className="form-control mb-2" value={label}
                   onChange={(e) => changeLabel(e.target.value)} />
            <label className="form-label" htmlFor="price">Unit price excl. VAT</label>
            {/* valueAsNumber: o valor do campo, como número (NaN se estiver vazio) */}
            <input id="price" type="number" step="0.1" min="0" className="form-control mb-2" value={priceExclVat}
                   onChange={(e) => setPriceExclVat(e.target.valueAsNumber || 0)} />
            <label className="form-label" htmlFor="quantity">Quantity (back to 1 if the item changes)</label>
            <input id="quantity" type="number" min="0" className="form-control mb-2" value={quantity}
                   onChange={(e) => setQuantity(e.target.valueAsNumber || 0)} />
            <label className="form-label" htmlFor="vat">VAT rate</label>
            {/* o valor de um <select> é uma STRING: Number(...) o converte */}
            <select id="vat" className="form-select mb-3" value={vatRate}
                    onChange={(e) => setVatRate(Number(e.target.value))}>
              <option value={5.5}>5.5 %</option>
              <option value={10}>10 %</option>
              <option value={20}>20 %</option>
            </select>
            <button className="btn btn-outline-secondary" onClick={reset}>Reset</button>
          </div>
        </div>
        <div className="col-md-6">
          <div className="card p-3">
            <h2 className="h5">{quantity} x {label}</h2>
            <table className="table mb-0">
              <tbody>
                <tr><td>Total excl. VAT</td><td className="text-end">{euros.format(totalExclVat)}</td></tr>
                <tr><td>VAT ({vatRate} %)</td><td className="text-end">{euros.format(vatAmount)}</td></tr>
                <tr className="fw-bold"><td>Total incl. VAT</td><td className="text-end">{euros.format(totalInclVat)}</td></tr>
              </tbody>
            </table>
          </div>
          <div className="card p-3 mt-3">
            <h2 className="h6">History of the total incl. VAT</h2>
            <ul className="mb-0">
              {history.map((line) => (
                <li key={line.id}>{line.text}</li>
              ))}
            </ul>
          </div>
        </div>
      </div>
    </div>
  );
}

O arquivo [main.tsx] deste exemplo — e da maioria dos exemplos seguintes — é igual ao do Exemplo 01, sem seus comentários. Apenas os arquivos [main.tsx] que diferirem serão mostrados.

  • Linha 16: os hooks utilizados, todos fornecidos pelo [React];
  • Linha 19: um formatador de valores monetários no estilo inglês (€1,234.50), criado de uma vez por todas fora do componente. O Exemplo 09 apresentará a API e os [Intl] arquivos;
  • Linhas 22–25: quatro valores de estado. Seu tipo é derivado do valor inicial: [useState('Pen')] é um estado do tipo [string], e [useState(2.5)] é um estado do tipo [number];
  • Linhas 29–30: dois valores calculados a partir do estado. Eles NÃO são estados: são simples constantes, recalculadas a cada chamada do componente. Estão, portanto, sempre atualizados. Esta é uma regra importante no [React]: armazene no estado apenas o que não pode ser calculado; todo o resto é calculado durante a exibição;
  • Linha 33: [useMemo(computation, [dependencies])] dá o mesmo resultado, mas o [React] armazena o valor e só o recalcula se uma das dependências tiver mudado desde a chamada anterior. Para uma adição, isso é desnecessário; usa-se para uma operação computacionalmente cara (ordenar uma lista longa...). Incluímos aqui para demonstrar sua sintaxe;
  • linhas 39–45: o histórico dos totais com IVA depende de valores sucessivos do total, o que um valor calculado não consegue expressar. Armazenamos o total antigo no estado ([oldTotal]); se, durante a exibição, ele for diferente do novo, atualizamos o estado enquanto o componente está sendo chamado. [React] permite isso: ele então descarta o resultado atual e chama imediatamente o componente de novo com o novo estado, antes de exibir qualquer coisa. Cada linha do histórico recebe um número único, [id], cujo uso será explicado no Exemplo 03;
  • Linhas 50–52: [useEffect(effect, [dependencies])]: A função [effect] é executada após a exibição: uma vez no início e, depois, sempre que uma das dependências (aqui, [totalInclVat]) muda. Usa-se para efeitos colaterais: afetar algo além do que o componente exibe (aqui, o título da aba do navegador; em outros casos, um timer, uma requisição HTTP);
  • Linhas 56–58: Alterar o item redefine a quantidade para 1. Isso é feito na função que trata a mudança do campo, onde sabemos por que o estado está mudando. Este é o método recomendado pelo [React]: em vez de um efeito que “monitora” o rótulo, a ação é realizada no tratador de evento;
  • linhas 61–65: várias mudanças de estado seguidas. O [React] as agrupa: o componente é chamado apenas uma vez, ao final do tratador.

JSX:

  • linhas 76–77: um campo controlado (veja o Exemplo 05): [value] exibe o estado; [onChange] é chamado a cada tecla digitada, por meio do evento [e]; [e.target.value] é o texto do campo. Em JSX, o atributo [for] de um label é escrito como [htmlFor];
  • linhas 80–81: para um campo numérico, [e.target.valueAsNumber] retorna o valor como número ([NaN] se o campo estiver vazio, daí o [|| 0]);
  • linhas 87–92: o valor de um [<select>] é sempre uma string: [Number(...)] a converte;
  • linha 110: [map] gera um elemento [<li>] por linha do histórico (veja o exemplo 03).

Com o servidor de desenvolvimento em execução ([npm start 02-state]), modificamos o item, o preço, a quantidade e a alíquota:

Image

Cada vez que o total com IVA muda, uma linha é adicionada ao histórico e o título da aba muda. Alterar o item redefine a quantidade para 1.

A diferença em relação ao [Angular] e ao [Vue.js] é profunda. Nesses frameworks, os dados são reativos (signals, [ref]): o framework sabe quais dados uma seção da página usa e atualiza apenas essa seção. O [React] adota uma abordagem mais simples: a cada mudança de estado, ele reexecuta toda a função do componente (e as de seus filhos) e depois compara o resultado com o anterior. O código passa então a se ler como uma função comum: os valores calculados são variáveis e as condições são o [if]. A contrapartida: é preciso seguir algumas regras (nunca modificar o estado diretamente, sempre chamar os hooks na mesma ordem) e considerar os efeitos e suas dependências.

2.3. Exemplo 03: A sintaxe JSX

JSX é HTML escrito no código [TypeScript], em que tudo o que está entre chaves é uma expressão. Este exemplo exibe uma lista de médicos, que pode ser filtrada:

// =========================================================================
// 03-jsx/src/App.tsx - a sintaxe JSX
// -------------------------------------------------------------------------
// JSX é HTML escrito DENTRO do código TypeScript. Cada tag se torna
// uma chamada de função, e tudo que está entre chaves é uma
// expressão TypeScript comum:
//   - attribute={expression}    : o valor de um atributo (src, disabled...);
//   - className={...}           : as classes CSS, uma string que calculamos;
//   - style={{ prop: value }}   : um OBJETO de propriedades CSS (camelCase);
//   - {condition && <p/>}       : um elemento que só existe se a
//                                 condição for verdadeira;
//   - {c ? <A/> : <B/>}         : um OU outro;
//   - {list.map((x) => <li key={x.id}/>)} : um elemento por elemento da
//                                 lista; key dá a IDENTIDADE de cada um.
// Nenhuma sintaxe especial para condições e laços: é TypeScript
// puro. Tudo que vem antes do return é código comum.
// =========================================================================

import { useState } from 'react';

// uma interface TypeScript descreve o formato dos objetos da lista
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
  specialty: 'general practitioner' | 'pediatrician' | 'cardiologist';
  available: boolean;
}

const DOCTORS: Doctor[] = [
  { id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner', available: true },
  { id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician', available: false },
  { id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'cardiologist', available: true },
];

// "um bloco entre vários, dependendo de um valor": um switch, em uma função
function icon(specialty: Doctor['specialty']) {
  switch (specialty) {
    case 'pediatrician':
      return <span title="children">&#x1F9F8;</span>;
    case 'cardiologist':
      return <span title="heart">&#x2764;&#xFE0F;</span>;
    default:
      return <span title="all patients">&#x1FA7A;</span>;
  }
}

export default function App() {
  const [doctors] = useState(DOCTORS);
  const [filter, setFilter] = useState(''); // texto pesquisado
  const [onlyAvailable, setOnlyAvailable] = useState(false);
  const [showHelp, setShowHelp] = useState(true);

  // a lista exibida: uma variável comum, recalculada a cada chamada
  const text = filter.trim().toLowerCase();
  const displayed = doctors.filter(
    (m) => (!onlyAvailable || m.available) && `${m.firstName} ${m.lastName} ${m.specialty}`.toLowerCase().includes(text),
  );

  // "um dos três blocos": é calculado ANTES do return, com ifs
  let content;
  if (doctors.length === 0) {
    content = <p className="text-muted">No doctor.</p>;
  } else if (displayed.length === 0) {
    content = <p className="text-warning">No doctor matches "{filter}".</p>;
  } else {
    content = (
      <table className="table">
        <thead>
          <tr><th>#</th><th>Doctor</th><th>Specialty</th><th>Status</th></tr>
        </thead>
        <tbody>
          {/* uma linha por médico; key: a identidade de cada linha, para que
              React saiba qual linha adicionar, mover ou remover */}
          {displayed.map((m, i) => (
            <tr key={m.id} className={m.available ? '' : 'opacity-50'}>
              <td>{i + 1}</td>
              <td>{m.title} {m.firstName} {m.lastName}</td>
              <td>{icon(m.specialty)} {m.specialty}</td>
              <td>
                {/* uma string de classes calculada por uma template string */}
                <span className={`badge ${m.available ? 'text-bg-success' : 'text-bg-secondary'}`}>
                  {m.available ? 'available' : 'unavailable'}
                </span>
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    );
  }

  return (
    // <> ... </>: um "fragmento", para retornar vários elementos sem
    // envolvê-los em um elemento HTML adicional
    <>
      <div className="container py-4">
        <h1 className="h3 mb-3">
          {/* a imagem está na pasta public/ do exemplo: servida como está */}
          <img src="/doctor.svg" alt="logo" width={32} height={32} /> Example 03 - the JSX syntax
        </h1>

        <div className="d-flex flex-wrap gap-3 align-items-center mb-3">
          <input className="form-control w-auto" placeholder="search..." value={filter}
                 onChange={(e) => setFilter(e.target.value)} />
          <label className="form-check-label">
            <input type="checkbox" className="form-check-input" checked={onlyAvailable}
                   onChange={(e) => setOnlyAvailable(e.target.checked)} /> available only
          </label>
          <button className="btn btn-sm btn-outline-secondary" onClick={() => setShowHelp((a) => !a)}>
            {showHelp ? 'Hide help' : 'Show help'}
          </button>
        </div>

        {/* &&: o parágrafo só EXISTE se showHelp for verdadeiro */}
        {showHelp && (
          <p className="alert alert-info">Type a name or a specialty. Unavailable doctors are greyed out.</p>
        )}

        {content}

        {/* style: um objeto; um número sozinho é entendido como pixels */}
        <p style={{ fontSize: 12 + displayed.length * 2 }}>
          {displayed.length} doctor(s) displayed - the size of this text depends on it.
        </p>
      </div>
    </>
  );
}
  • linhas 22–27: uma interface [TypeScript] descreve o formato dos objetos da lista; [specialty] só pode assumir três valores;
  • linhas 38–47: “um bloco entre vários, dependendo de um valor.” O JSX não tem uma sintaxe para isso: trata-se de uma função comum, com um [switch], que retorna JSX. [Doctor['specialty']] é o tipo da propriedade [specialty]. [&#x1F9F8;] é uma entidade HTML (um emoji), permitida em JSX;
  • linhas 50–53: o estado da página. Apenas o valor de [useState(DOCTORS)] é mantido; ele nunca é modificado aqui;
  • linhas 56–59: a lista exibida: uma variável, recalculada a cada chamada do componente;
  • linhas 62–68: um entre três conteúdos possíveis, selecionado com [if] antes do [return]. Um trecho de JSX é um valor como qualquer outro: pode ser armazenado em uma variável;
  • linhas 76–88: a lista: [map] converte cada médico em uma linha de [<tr>]. [i] é a posição do médico na lista;
  • linha 77: o atributo [key] identifica cada linha. Quando a lista muda, o [React] usa isso para determinar qual linha adicionar, mover ou excluir, em vez de reconstruir a lista inteira. A chave deve ser única entre os elementos da lista e estável (a mesma de uma exibição para outra): um identificador, não a posição. O [React] indica no console que a lista não tem chaves;
  • linha 77: as classes CSS são uma string calculada, neste caso com o operador [? :];
  • linha 80: o JSX retornado pela função [icon];
  • linha 83: uma template string ([badge ${...}]) monta a lista de classes: [badge] e uma classe calculada.

O [return]:

  • linha 97: um fragmento, [<>...</>], permite retornar vários elementos sem envolvê-los em um elemento HTML adicional (aqui, há apenas um — é só para o exemplo);
  • linha 101: a imagem está na pasta [public/] do exemplo: o [Vite] a serve como está, na raiz do site. [width={32}]: um valor numérico, entre chaves;
  • linhas 105–106: o campo de busca, que é controlado; para uma caixa de seleção, [checked] é lido e escrito;
  • linha 111: uma função “arrow” escrita diretamente no atributo: ela alterna o estado;
  • Linhas 117–119: [condition && <p>...</p>]: o parágrafo existe apenas se a condição for verdadeira (se for falsa, o [React] não exibe nada para [false], [null], ou [undefined]). Cuidado com esta armadilha: [{list.length && <p/>}] exibiria “0” para uma lista vazia; em vez disso, escreva [list.length > 0 && ...];
  • linha 121: o conteúdo selecionado acima;
  • linha 124: o atributo [style] recebe um objeto (daí as chaves duplas: a expressão e, depois, o objeto), cujas propriedades CSS são escritas em “camelCase” ([fontSize] para [font-size]). Um número sozinho é interpretado como pixels.

Image

Digite “gen” e marque “available only”, depois digite “zzz”:

Image

2.4. Exemplo 04: Eventos

// =========================================================================
// 04-events/src/App.tsx - reagindo às ações do usuário
// -------------------------------------------------------------------------
// onEvent={function}: a função é chamada quando o elemento emite
// este evento:
//   - onClick={f}                    chama f(event);
//   - onClick={() => remove(t)}      uma arrow function, para passar os
//                                    próprios argumentos;
//   - o evento recebido é um "evento sintético" do React, que tem a
//     mesma interface do evento do navegador (preventDefault(),
//     target, key...); event.nativeEvent fornece o evento original;
//   - useRef: uma REFERÊNCIA a um elemento HTML (ref={field}), para ler ou
//     agir sobre o próprio elemento (field.current.value, .focus()...).
// Aqui, sem estado para o campo de entrada: nós mesmos o lemos.
// =========================================================================

import { useRef, useState, type FormEvent, type KeyboardEvent, type MouseEvent } from 'react';

interface Task {
  id: number;
  label: string;
  done: boolean;
}

// o estilo da área clicável: um objeto, como para o atributo style
const areaStyle = { background: '#e7f5ff', height: 80, cursor: 'crosshair' };

export default function App() {
  const [tasks, setTasks] = useState<Task[]>([
    { id: 1, label: 'Install Node.js', done: true },
    { id: 2, label: 'Read the chapter on events', done: false },
  ]);
  const [log, setLog] = useState<string[]>([]);
  // uma referência ao <input> da nova tarefa (null enquanto ele não for exibido)
  const field = useRef<HTMLInputElement>(null);
  // uma referência também pode guardar um valor que NÃO é exibido: modificá-la
  // não chama o componente de novo
  const nextId = useRef(3);

  function trace(message: string) {
    setLog((j) => [`${new Date().toLocaleTimeString()} ${message}`, ...j]);
  }

  // onSubmit: Enter no campo OU clique no botão. preventDefault()
  // impede o navegador de enviar o formulário (e recarregar a página)
  function add(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const input = field.current!;
    const label = input.value.trim();
    if (label === '') {
      return;
    }
    // um estado que contém um array: ele é SUBSTITUÍDO por um novo array
    // (o antigo nunca é modificado: o React não perceberia a mudança)
    setTasks((t) => [...t, { id: nextId.current++, label, done: false }]);
    trace(`added "${label}"`);
    input.value = '';
    input.focus();
  }

  // uma tecla: event.key fornece seu nome
  function onKeyDown(event: KeyboardEvent<HTMLInputElement>) {
    if (event.key === 'Escape') {
      event.currentTarget.value = '';
    }
  }

  function toggle(task: Task, done: boolean) {
    setTasks((t) => t.map((x) => (x.id === task.id ? { ...x, done } : x)));
    trace(`"${task.label}": ${done ? 'done' : 'to do'}`);
  }

  function remove(task: Task) {
    setTasks((t) => t.filter((x) => x.id !== task.id));
    trace(`removed "${task.label}"`);
  }

  // o evento original (nativeEvent) tem as coordenadas relativas à área
  function position(event: MouseEvent<HTMLDivElement>) {
    trace(`click at (${event.nativeEvent.offsetX}, ${event.nativeEvent.offsetY})`);
  }

  return (
    <div className="container py-4">
      <h1 className="h3 mb-3">Example 04 - events</h1>

      <form className="d-flex gap-2 mb-3" onSubmit={add}>
        <input ref={field} className="form-control" placeholder="new task (Esc to clear)" onKeyDown={onKeyDown} />
        <button type="submit" className="btn btn-primary">Add</button>
      </form>

      <ul className="list-group mb-3">
        {tasks.map((t) => (
          <li key={t.id} className="list-group-item d-flex align-items-center gap-2">
            {/* e.target: a caixa de seleção DESTA linha; checked: seu estado */}
            <input type="checkbox" className="form-check-input" checked={t.done}
                   onChange={(e) => toggle(t, e.target.checked)} />
            <span className={`flex-grow-1 ${t.done ? 'text-decoration-line-through text-muted' : ''}`}>{t.label}</span>
            {/* uma arrow function: a tarefa DESTA linha como argumento */}
            <button className="btn btn-sm btn-outline-danger" onClick={() => remove(t)}>Delete</button>
          </li>
        ))}
      </ul>

      <div className="p-3 mb-3 rounded" style={areaStyle} onClick={position}>Click in this area</div>

      <h2 className="h6">Log</h2>
      <ul className="small">
        {log.map((line, i) => (
          // key: a posição da linha contada a partir da PRIMEIRA adicionada (que
          // sempre tem a key 1): cada linha mantém a mesma key quando outras
          // chegam ao topo da lista
          <li key={log.length - i}>{line}</li>
        ))}
      </ul>
    </div>
  );
}
  • Linha 17: [FormEvent], [KeyboardEvent], [MouseEvent] são tipos de evento do [React] (daí o termo [type]);
  • Linha 26: o estilo da área clicável, um objeto;
  • linha 35: [useRef] cria uma referência: um objeto [{ current: ... }] que o [React] mantém de uma exibição para a seguinte. Atribuída ao atributo [ref] de um elemento (linha 88), ela se refere ao próprio elemento HTML, depois de exibido: [field.current.value], [field.current.focus()]...;
  • linha 38: uma referência também pode guardar qualquer valor que não seja exibido. Modificá-la ([nextId.current++]) não reexecuta o componente, ao contrário de um estado;
  • linhas 46–59: chamada pelo evento [onSubmit] do formulário, disparado quando você pressiona Enter no campo OU clica no botão [submit]:
    • linha 47: impede que o navegador envie o formulário ao servidor, o que recarregaria a página;
    • linha 48: o elemento [<input>]; o operador [!] confirma que ele existe (está exibido);
    • linha 55: um estado contendo um array: ele é substituído por um novo array ([[...t, newTask]]: os elementos de [t], seguidos da nova tarefa). NUNCA modificamos o próprio estado ([t.push(...)]): o [React] compara os valores antigo e novo; se forem o mesmo array, conclui que nada mudou e não exibe nada;
    • linhas 57–58: o campo é limpo e o foco volta a ele, diretamente no elemento HTML;
  • linhas 62–66: [event.key] retorna o nome da tecla. [currentTarget] é o elemento que possui o tratador (neste caso, o campo);
  • linha 69: modificar um elemento do array: um novo array, em que o elemento em questão é substituído por uma cópia modificada ([{ ...x, done }]);
  • linha 74: excluir um elemento: um novo array, sem esse elemento;
  • linhas 79–81: o evento do [React] é um evento “sintético”, que tem a mesma interface do evento do navegador; [nativeEvent] fornece o evento original, aqui com as coordenadas do clique relativas à área ([offsetX]).

JSX:

  • linha 87: o tratador do formulário;
  • linha 88: a referência e um tratador de tecla. Este campo não é controlado (sem [value]): o navegador gerencia seu valor, que é lido quando necessário;
  • Linhas 96–97: um tratador escrito na hora: uma função arrow que chama [toggle] com a tarefa DESTA linha;
  • Linha 100: mesmo princípio: [onClick={remove(t)}] chamaria [remove] imediatamente, durante a exibição;
  • Linha 113: a chave das linhas do log.

Adicione uma tarefa, marque a segunda, exclua a primeira e depois clique no campo:

Image

2.5. Exemplo 05: Campos controlados

Um formulário com todos os tipos de campos, vinculados ao estado:

// =========================================================================
// 05-controlled-fields/src/App.tsx - todos os tipos de campo, "controlados"
// -------------------------------------------------------------------------
// Um campo CONTROLADO exibe um valor do estado (value={...}) e notifica
// o componente de cada mudança (onChange={...}), que atualiza o
// estado. O estado é a única fonte de verdade: digitar no campo modifica
// o estado, e modificar o estado (por código) modifica o campo.
// É o binding "bidirecional", escrito à mão. O que se lê
// no evento depende do campo:
//   - text input, textarea           -> e.target.value (string)
//   - input type="number"            -> e.target.valueAsNumber (NaN se vazio)
//   - checkbox                       -> e.target.checked (booleano)
//   - radio buttons                  -> e.target.value do botão escolhido
//   - select                         -> e.target.value
//   - select multiple                -> e.target.selectedOptions (vários)
//   - input type="date"              -> e.target.value, "yyyy-MM-dd"
// Mesmo formulário do exemplo 18 do curso de NestJS; mas aqui, sem
// servidor: tudo acontece no navegador.
// =========================================================================

import { useState, type FormEvent } from 'react';

const TITLES = ['Mr', 'Mme', 'Melle'];
const HOBBIES = ['sport', 'music', 'reading', 'cinema'];
const COUNTRIES = [
  { code: 'fr', label: 'France' },
  { code: 'be', label: 'Belgium' },
  { code: 'ch', label: 'Switzerland' },
];

export default function App() {
  // um estado por campo do formulário
  const [title, setTitle] = useState('Mme');
  const [name, setName] = useState('');
  const [age, setAge] = useState<number | null>(30);
  const [presentation, setPresentation] = useState('');
  const [newsletter, setNewsletter] = useState(false);
  const [hobbies, setHobbies] = useState<string[]>(['reading']);
  const [country, setCountry] = useState('fr');
  const [languages, setLanguages] = useState<string[]>([]);
  const [birthDate, setBirthDate] = useState('');
  const [sent, setSent] = useState<string | null>(null);

  // todos os valores, reunidos em um objeto (o que seria enviado a um servidor)
  const model = { title, name: name.trim(), age, presentation, newsletter, hobbies, country, languages, birthDate };

  // várias caixas para UM array: o valor é adicionado ou removido
  function toggleHobby(hobby: string, checked: boolean) {
    setHobbies((l) => (checked ? [...l, hobby] : l.filter((x) => x !== hobby)));
  }

  function send(event: FormEvent<HTMLFormElement>) {
    event.preventDefault(); // sem envio ao servidor, sem recarregamento
    setSent(JSON.stringify(model));
  }

  return (
    <div className="container py-4">
      <h1 className="h3 mb-3">Example 05 - controlled fields</h1>
      <div className="row g-4">
        <form className="col-md-7" onSubmit={send}>
          <div className="mb-3">
            <span className="form-label d-block">Title</span>
            {/* botões de opção: o mesmo estado; checked indica qual está marcado */}
            {TITLES.map((t) => (
              <div key={t} className="form-check form-check-inline">
                <input type="radio" className="form-check-input" name="title" id={`title-${t}`} value={t}
                       checked={title === t} onChange={(e) => setTitle(e.target.value)} />
                <label className="form-check-label" htmlFor={`title-${t}`}>{t}</label>
              </div>
            ))}
          </div>
          <div className="row g-3 mb-3">
            <div className="col-8">
              <label className="form-label" htmlFor="name">Name</label>
              <input id="name" className="form-control" value={name} onChange={(e) => setName(e.target.value)} />
            </div>
            <div className="col-4">
              <label className="form-label" htmlFor="age">Age</label>
              {/* um campo vazio dá NaN: null é guardado no estado, '' no campo */}
              <input id="age" type="number" className="form-control" value={age ?? ''}
                     onChange={(e) => setAge(Number.isNaN(e.target.valueAsNumber) ? null : e.target.valueAsNumber)} />
            </div>
          </div>
          <div className="mb-3">
            <label className="form-label" htmlFor="presentation">About you (updated when leaving the field)</label>
            {/* um campo NÃO controlado: defaultValue é seu valor inicial, depois
                o navegador o gerencia sozinho; onBlur só notifica ao sair */}
            <textarea id="presentation" rows={2} className="form-control" defaultValue={presentation}
                      onBlur={(e) => setPresentation(e.target.value)} />
          </div>
          <div className="mb-3 form-check">
            {/* uma única caixa: true / false */}
            <input id="newsletter" type="checkbox" className="form-check-input" checked={newsletter}
                   onChange={(e) => setNewsletter(e.target.checked)} />
            <label htmlFor="newsletter" className="form-check-label">Receive the newsletter</label>
          </div>
          <div className="mb-3">
            <span className="form-label d-block">Hobbies</span>
            {HOBBIES.map((l) => (
              <div key={l} className="form-check form-check-inline">
                <input type="checkbox" className="form-check-input" id={`hobby-${l}`} checked={hobbies.includes(l)}
                       onChange={(e) => toggleHobby(l, e.target.checked)} />
                <label className="form-check-label" htmlFor={`hobby-${l}`}>{l}</label>
              </div>
            ))}
          </div>
          <div className="row g-3 mb-3">
            <div className="col-6">
              <label className="form-label" htmlFor="country">Country</label>
              {/* value no <select> (e não selected nas <option>) */}
              <select id="country" className="form-select" value={country} onChange={(e) => setCountry(e.target.value)}>
                {COUNTRIES.map((p) => (
                  <option key={p.code} value={p.code}>{p.label}</option>
                ))}
              </select>
            </div>
            <div className="col-6">
              <label className="form-label" htmlFor="languages">Spoken languages</label>
              {/* multiple: value é um ARRAY; selectedOptions, as opções escolhidas */}
              <select id="languages" multiple size={3} className="form-select" value={languages}
                      onChange={(e) => setLanguages([...e.target.selectedOptions].map((o) => o.value))}>
                <option value="fr">French</option>
                <option value="en">English</option>
                <option value="es">Spanish</option>
              </select>
            </div>
          </div>
          <div className="mb-3">
            <label className="form-label" htmlFor="birthDate">Date of birth</label>
            <input id="birthDate" type="date" className="form-control w-auto" value={birthDate}
                   onChange={(e) => setBirthDate(e.target.value)} />
          </div>
          <button type="submit" className="btn btn-primary">Send</button>
        </form>

        <div className="col-md-5">
          <h2 className="h6">The model, live</h2>
          {/* JSON.stringify(object, null, 2): o JSON, indentado com 2 espaços */}
          <pre className="bg-light p-2 rounded small">{JSON.stringify(model, null, 2)}</pre>
          {sent !== null && (
            <>
              <h2 className="h6">Last sending</h2>
              <pre className="bg-success-subtle p-2 rounded small text-wrap">{sent}</pre>
            </>
          )}
        </div>
      </div>
    </div>
  );
}

O princípio (linhas 4–6): um campo controlado exibe um valor do estado ([value={...}]) e notifica o componente de qualquer mudança ([onChange={...}]), que então atualiza o estado. O estado é a única fonte de verdade: o campo simplesmente exibe o que o estado diz. Se o tratador de [onChange] não atualizasse o estado, o campo não aceitaria a entrada do usuário.

  • Linhas 33–41: um estado por campo;
  • linha 45: todos os valores reunidos em um único objeto — o que seria enviado a um servidor. É um valor calculado; [name.trim()] remove os espaços no início e no fim;
  • Linhas 48–50: várias caixas de seleção para UM array: o valor é adicionado ou removido;
  • linhas 52–55: envia o formulário sem recarregar a página.

JSX, campo por campo:

  • linhas 65–68: botões de opção (radio): eles compartilham o mesmo estado; [checked] indica qual está selecionado. [key={t}]: a chave de cada botão;
  • linha 76: um campo de texto;
  • linhas 81–82: um campo numérico: um campo vazio resulta em [NaN]; armazenamos então [null] no estado e exibimos [''] ([age ?? '']: [''] se [age] for igual a [null] ou [undefined]);
  • linhas 89–90: um campo não controlado: [defaultValue] é seu valor inicial, depois do qual o navegador cuida dele por conta própria; [onBlur] notifica o componente quando o campo é abandonado. O estado só é atualizado, portanto, ao sair do campo;
  • linha 94: uma única caixa de seleção: [checked] e [e.target.checked];
  • linhas 100–103: as caixas de seleção de hobbies;
  • linha 112: uma lista: [value] no [<select>], e não [selected] no [<option>];
  • linhas 121–122: uma lista de múltipla escolha: [value] é um array; [e.target.selectedOptions] fornece as opções selecionadas, que são convertidas em um array de valores ([[...list]] converte uma coleção em um array);
  • linha 131: uma data, na forma de uma string [yyyy-MM-dd];
  • linha 140: o modelo, no formato JSON, indentado com 2 espaços.

Image

Escrever [value] e [onChange] em cada campo é repetitivo: esta é a contrapartida da simplicidade do [React], que não tem equivalente ao [v-model] do [Vue.js] nem ao [[(ngModel)]] do [Angular]. Os exemplos seguintes mostram como reduzir essa repetição: um único objeto de estado (Exemplo 06), uma função que gera os atributos de um campo (Exemplos 06 e 07) e uma biblioteca (Exemplo 08).

2.6. Exemplo 06: Um formulário, um objeto, um reducer

// =========================================================================
// 06-use-reducer/src/App.tsx - um formulário, um objeto, um reducer
// -------------------------------------------------------------------------
// O exemplo 05 tinha um useState por campo. Para um formulário real,
// preferimos UM objeto que contém todos os valores, o MODELO, e
// descrevemos suas mudanças em uma única função, o REDUCER:
//
//     reducer(estadoAtual, action) -> novoEstado
//
// useReducer(reducer, initialState) retorna o estado e uma função
// dispatch(action): o componente não modifica mais o estado, ele DESCREVE o que
// aconteceu ({ type: 'edit', field: 'lastName', value: 'Dupont' }) e o
// reducer deduz dela o novo estado. Toda a lógica fica em um só lugar,
// e é uma função PURA (mesma entrada, mesma saída, sem efeito
// colateral), fácil de testar.
//
// O estado também guarda, para cada campo, se ele foi "tocado" (deixado ao
// menos uma vez); a partir disso deduzimos se ele está "modificado" (seu valor difere do
// valor inicial) e se está desabilitado.
// =========================================================================

import { useReducer, type ChangeEvent } from 'react';

// o formato dos dados do formulário
interface Profile {
  title: string;
  firstName: string;
  lastName: string;
  age: number;
  newsletter: boolean;
  email: string;
  country: string;
  birthDate: string;
  presentation: string;
}

const INITIAL: Profile = {
  title: 'Mme',
  firstName: 'Marie',
  lastName: 'PELISSIER',
  age: 30,
  newsletter: false,
  email: '',
  country: 'fr',
  birthDate: '',
  presentation: '',
};

type Field = keyof Profile; // 'title' | 'firstName' | ...: o nome de um campo

interface State {
  values: Profile;
  touched: Partial<Record<Field, boolean>>; // os campos já deixados
}

// as ações possíveis: uma "união discriminada" pela propriedade type
type Action =
  | { type: 'edit'; field: Field; value: Profile[Field] }
  | { type: 'leave'; field: Field }
  | { type: 'uppercase' }
  | { type: 'reset' };

// o reducer: ele NUNCA modifica o estado recebido, retorna um novo
function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'edit':
      return { ...state, values: { ...state.values, [action.field]: action.value } };
    case 'leave':
      return { ...state, touched: { ...state.touched, [action.field]: true } };
    case 'uppercase': {
      const { firstName, lastName } = state.values;
      return { ...state, values: { ...state.values, firstName: firstName.toUpperCase(), lastName: lastName.toUpperCase() } };
    }
    case 'reset':
      return { values: { ...INITIAL }, touched: {} };
  }
}

const TITLES = ['Mr', 'Mme', 'Melle'];
const TRACKED_FIELDS: Field[] = ['firstName', 'lastName', 'age', 'email'];

export default function App() {
  const [state, dispatch] = useReducer(reducer, { values: { ...INITIAL }, touched: {} });
  const v = state.values;

  // valores DEDUZIDOS do estado
  const modified = (c: Field) => v[c] !== INITIAL[c];
  const disabled = (c: Field) => c === 'email' && !v.newsletter; // o e-mail exige a newsletter
  const formModified = (Object.keys(INITIAL) as Field[]).some(modified);

  // os atributos comuns a um campo de texto: uma função que os monta
  // (id, value, onChange, onBlur, disabled), para "espalhar" no elemento: {...bind('lastName')}
  function bind(field: 'firstName' | 'lastName' | 'email' | 'birthDate' | 'presentation' | 'country') {
    return {
      id: field,
      value: v[field],
      disabled: disabled(field),
      onChange: (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) =>
        dispatch({ type: 'edit', field, value: e.target.value }),
      onBlur: () => dispatch({ type: 'leave', field }),
    };
  }

  return (
    <div className="container py-4">
      <h1 className="h3 mb-3">Example 06 - a form, an object, a reducer</h1>
      <div className="row g-4">
        <form className="col-md-7" onSubmit={(e) => e.preventDefault()}>
          <div className="mb-3">
            <span className="form-label d-block">Title</span>
            {TITLES.map((t) => (
              <div key={t} className="form-check form-check-inline">
                <input type="radio" className="form-check-input" id={`title-${t}`} name="title" value={t}
                       checked={v.title === t} onChange={() => dispatch({ type: 'edit', field: 'title', value: t })} />
                <label className="form-check-label" htmlFor={`title-${t}`}>{t}</label>
              </div>
            ))}
          </div>
          <div className="row g-3 mb-3">
            <div className="col-5">
              <label className="form-label" htmlFor="firstName">First name</label>
              {/* {...object}: cada propriedade do objeto se torna um atributo */}
              <input className="form-control" {...bind('firstName')} />
            </div>
            <div className="col-5">
              <label className="form-label" htmlFor="lastName">Last name</label>
              <input className="form-control" {...bind('lastName')} />
            </div>
            <div className="col-2">
              <label className="form-label" htmlFor="age">Age</label>
              <input id="age" type="number" className="form-control" value={v.age}
                     onChange={(e) => dispatch({ type: 'edit', field: 'age', value: e.target.valueAsNumber || 0 })}
                     onBlur={() => dispatch({ type: 'leave', field: 'age' })} />
            </div>
          </div>
          <div className="row g-3 mb-3 align-items-end">
            <div className="col-5">
              <div className="form-check">
                <input id="newsletter" type="checkbox" className="form-check-input" checked={v.newsletter}
                       onChange={(e) => dispatch({ type: 'edit', field: 'newsletter', value: e.target.checked })} />
                <label htmlFor="newsletter" className="form-check-label">Receive the newsletter</label>
              </div>
            </div>
            <div className="col-7">
              <label className="form-label" htmlFor="email">E-mail (if newsletter)</label>
              <input type="email" className="form-control" {...bind('email')} />
            </div>
          </div>
          <div className="row g-3 mb-3">
            <div className="col-6">
              <label className="form-label" htmlFor="country">Country</label>
              <select className="form-select" {...bind('country')}>
                <option value="fr">France</option>
                <option value="be">Belgium</option>
                <option value="ch">Switzerland</option>
              </select>
            </div>
            <div className="col-6">
              <label className="form-label" htmlFor="birthDate">Date of birth</label>
              <input type="date" className="form-control" {...bind('birthDate')} />
            </div>
          </div>
          <div className="mb-3">
            <label className="form-label" htmlFor="presentation">About you</label>
            <textarea rows={2} className="form-control" {...bind('presentation')} />
          </div>
          <div className="d-flex gap-2">
            <button type="button" className="btn btn-outline-primary" onClick={() => dispatch({ type: 'uppercase' })}>
              Name in uppercase
            </button>
            <button type="button" className="btn btn-outline-secondary" onClick={() => dispatch({ type: 'reset' })}>
              Reset
            </button>
          </div>
        </form>

        <div className="col-md-5">
          <h2 className="h6">The model, live</h2>
          <pre className="bg-light p-2 rounded small">{JSON.stringify(v, null, 2)}</pre>
          <h2 className="h6">The state of the fields</h2>
          <table className="table table-sm small">
            <thead><tr><th>field</th><th>touched</th><th>modified</th><th>disabled</th></tr></thead>
            <tbody>
              {TRACKED_FIELDS.map((c) => (
                <tr key={c}>
                  <td>{c}</td>
                  <td>{String(state.touched[c] ?? false)}</td>
                  <td>{String(modified(c))}</td>
                  <td>{String(disabled(c))}</td>
                </tr>
              ))}
            </tbody>
          </table>
          <p className="small mb-0">form modified: <strong>{String(formModified)}</strong></p>
        </div>
      </div>
    </div>
  );
}
  • linhas 25–35: a estrutura de dados do formulário; [INITIAL] (linhas 37–47), seus valores iniciais;
  • Linha 49: [keyof Profile] é o tipo dos nomes das propriedades de [Profile]: ['title' | 'firstName' | ...];
  • Linhas 51–54: o estado completo: os valores e os campos que já foram “visitados” (abandonados ao menos uma vez). [Partial<Record<Field, boolean>>]: um objeto cujas chaves são nomes de campos, todas opcionais;
  • linhas 57–61: as ações possíveis, na forma de uma “união discriminada”: cada ação tem uma propriedade [type], que especifica qual é a ação, e seus próprios dados;
  • linhas 64–77: o reducer: uma função que recebe o estado atual e uma ação e retorna o NOVO estado. Ele nunca modifica o estado recebido (cria uma cópia modificada, [{ ...state, ... }]) e não faz nada além disso: é uma função pura, fácil de entender e de testar. [[action.field]: action.value]: uma propriedade cujo nome é calculado;
  • linha 83: [useReducer(reducer, initialState)] retorna o estado e uma função [dispatch(action)]: o componente não modifica mais o estado; ele descreve o que aconteceu ([dispatch({ type: 'leave', field: 'lastName' })]), e o [React] chama o reducer para deduzir o novo estado;
  • linhas 87–89: valores derivados do estado: um campo é “modificado” se seu valor difere do valor inicial; o e-mail fica desabilitado enquanto a caixa “newsletter” não estiver marcada;
  • linhas 93–102: uma função que gera os atributos comuns a um campo: [id], [value], [disabled], [onChange], [onBlur]. Eles são “aplicados” ao elemento com a sintaxe [{...object}] (linha 123): cada propriedade do objeto se torna um atributo. Uma única linha basta, então, para vincular um campo ao formulário.

No JSX, campos específicos (botões de opção, idade, caixa de seleção) chamam [dispatch] diretamente; os botões “Name in uppercase” e “Reset” disparam as ações correspondentes. À direita, o modelo ao vivo e o estado dos campos.

Digite um nome, digite um sobrenome, marque a caixa da newsletter, digite um endereço de e-mail e depois clique em “Name in uppercase”:

Image

[useState] é adequado para dados independentes; [useReducer] serve para um estado composto, em que as mudanças seguem regras: toda a lógica fica em um só lugar, fora do componente. É o mesmo conceito dos “stores” do [Redux] ou do [Vuex], mas no nível do componente.

2.7. Exemplo 07: Validação de formulário

// =========================================================================
// 07-validation/src/App.tsx - validando um formulário no navegador
// -------------------------------------------------------------------------
// O React não tem sistema de validação: é código comum. Uma função
// PURA, validate(account), retorna os erros dos campos; ela é
// chamada a cada exibição, então os erros estão sempre atualizados.
// Eles não são mostrados de imediato (um formulário vazio coberto de vermelho
// é desagradável): só para um campo já deixado ("touched"). Enviar
// marca todos os campos como touched, e só age se o formulário
// for válido.
//
// Mesmas regras do servidor RdvMedecins (formulário "Criar uma conta").
// ATENÇÃO: esta validação é apenas uma COMODIDADE para o usuário (uma
// resposta imediata, sem ida e volta ao servidor). Ela não protege
// nada: qualquer um pode enviar ao servidor uma requisição montada
// à mão (curl...). O servidor, portanto, SEMPRE revalida tudo (cf. exemplo 25).
// =========================================================================

import { useState, type FormEvent } from 'react';

interface Account {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  password: string;
  confirmation: string;
}

type Field = keyof Account;
// no máximo uma mensagem de erro por campo
type Errors = Partial<Record<Field, string>>;

const TITLES = ['Mr', 'Mme', 'Melle'];
const LOGIN_FORMAT = /^[a-z0-9._-]{1,30}$/;
const PASSWORD_MIN = 6;

// as regras: uma função pura, que só depende de seus argumentos
function validate(c: Account): Errors {
  const errors: Errors = {};
  if (!TITLES.includes(c.title)) errors.title = 'Choose a title from the list.';
  if (c.firstName.trim() === '') errors.firstName = 'The first name is required.';
  else if (c.firstName.length > 20) errors.firstName = 'The first name must not exceed 20 characters.';
  if (c.lastName.trim() === '') errors.lastName = 'The last name is required.';
  else if (c.lastName.length > 20) errors.lastName = 'The last name must not exceed 20 characters.';
  if (c.login === '') errors.login = 'The login is required.';
  else if (!LOGIN_FORMAT.test(c.login)) errors.login = 'Unaccented lower-case letters, digits, dot, hyphen, underscore.';
  if (c.password === '') errors.password = 'The password is required.';
  else if (c.password.length < PASSWORD_MIN) errors.password = `At least ${PASSWORD_MIN} characters.`;
  // uma regra que compara DOIS campos
  if (c.confirmation !== c.password) errors.confirmation = 'The confirmation does not match the password.';
  return errors;
}

const EMPTY: Account = { title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '' };
const ALL: Record<Field, boolean> = { title: true, firstName: true, lastName: true, login: true, password: true, confirmation: true };

export default function App() {
  const [account, setAccount] = useState<Account>(EMPTY);
  const [touched, setTouched] = useState<Partial<Record<Field, boolean>>>({});
  const [submitAttempted, setSubmitAttempted] = useState(false);
  const [success, setSuccess] = useState(false);

  // os erros: recalculados a cada exibição, nunca guardados no estado
  const errors = validate(account);
  const errorCount = Object.keys(errors).length;

  // a classe Bootstrap de um campo: vermelho (is-invalid) ou verde (is-valid),
  // somente depois de ele ter sido tocado
  function cssClass(field: Field, base = 'form-control'): string {
    if (!touched[field]) return base;
    return `${base} ${errors[field] ? 'is-invalid' : 'is-valid'}`;
  }

  // os atributos comuns a todos os campos
  function bind(field: Field) {
    return {
      id: field,
      value: account[field],
      onChange: (e: { target: { value: string } }) => {
        setAccount((c) => ({ ...c, [field]: e.target.value }));
        setSuccess(false);
      },
      onBlur: () => setTouched((t) => ({ ...t, [field]: true })),
    };
  }

  function send(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setSubmitAttempted(true);
    setTouched(ALL); // todos os erros aparecem
    // aqui, a conta seria enviada ao servidor (cf. exemplo 25)
    setSuccess(errorCount === 0);
  }

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 07 - the validation of a form</h1>
      {/* noValidate: a validação própria do navegador é desativada, para
          exibir NOSSAS mensagens, em NOSSO estilo */}
      <form className="card p-4" noValidate onSubmit={send}>
        <div className="mb-3">
          <label className="form-label" htmlFor="title">Title</label>
          <select className={cssClass('title', 'form-select')} {...bind('title')}>
            {TITLES.map((t) => <option key={t}>{t}</option>)}
          </select>
          <div className="invalid-feedback">{errors.title}</div>
        </div>
        <div className="row g-3 mb-3">
          <div className="col-sm-6">
            <label className="form-label" htmlFor="firstName">First name</label>
            {/* is-invalid emoldura o campo em vermelho E mostra o
                .invalid-feedback que o segue: o erro do campo é escrito ali */}
            <input className={cssClass('firstName')} {...bind('firstName')} />
            <div className="invalid-feedback">{errors.firstName}</div>
          </div>
          <div className="col-sm-6">
            <label className="form-label" htmlFor="lastName">Last name</label>
            <input className={cssClass('lastName')} {...bind('lastName')} />
            <div className="invalid-feedback">{errors.lastName}</div>
          </div>
        </div>
        <div className="mb-3">
          <label className="form-label" htmlFor="login">Login</label>
          <input className={cssClass('login')} autoComplete="username" {...bind('login')} />
          <div className="invalid-feedback">{errors.login}</div>
        </div>
        <div className="row g-3 mb-4">
          <div className="col-sm-6">
            <label className="form-label" htmlFor="password">Password</label>
            <input type="password" className={cssClass('password')} autoComplete="new-password" {...bind('password')} />
            <div className="invalid-feedback">{errors.password}</div>
          </div>
          <div className="col-sm-6">
            <label className="form-label" htmlFor="confirmation">Confirmation</label>
            <input type="password" className={cssClass('confirmation')} autoComplete="new-password" {...bind('confirmation')} />
            <div className="invalid-feedback">{errors.confirmation}</div>
          </div>
        </div>
        <button type="submit" className="btn btn-primary">Create the account</button>
        {submitAttempted && errorCount > 0 && (
          <div className="alert alert-danger mt-3 mb-0">The form contains {errorCount} error(s).</div>
        )}
        {success && <div className="alert alert-success mt-3 mb-0">Valid form: it could be sent to the server.</div>}
      </form>
    </div>
  );
}

[React] não tem sistema de validação: é apenas código comum.

  • Linhas 30–32: no máximo uma mensagem de erro por campo;
  • linhas 39–53: as regras: uma função pura que retorna os erros dos campos; são as mesmas regras do servidor [RdvMedecins] para a criação de uma conta. A última regra compara dois campos;
  • Linha 65: os erros são recalculados a cada exibição da página e nunca são guardados em cache; estão, portanto, sempre atualizados;
  • linhas 70–73: a classe [Bootstrap] de um campo — [is-invalid] (caixa vermelha) ou [is-valid] (caixa verde) — somente depois que o campo foi selecionado: um formulário vazio todo coberto de vermelho seria desagradável;
  • linhas 76–86: como no Exemplo 06, os atributos comuns dos campos; abandonar um campo o marca como selecionado;
  • linhas 88–94: enviar o formulário marca os campos como preenchidos (seus erros aparecem), e o envio só tem sucesso se o formulário for válido.

JSX:

  • linha 101: a validação própria do navegador é desativada para exibir NOSSAS mensagens no NOSSO estilo;
  • linhas 114–115: a classe [is-invalid] contorna o campo em vermelho E exibe o [.invalid-feedback] seguinte, onde o erro do campo é escrito.

Digite um nome, digite um sobrenome, digite um login inválido:

Image

Clique em “Create the account”:

Image

Depois que tudo estiver corrigido:

Image

AVISO: esta validação serve apenas para a conveniência do usuário (uma resposta imediata, sem ida e volta ao servidor). Ela não oferece nenhuma proteção: qualquer pessoa pode enviar ao servidor uma requisição montada manualmente ([curl]...). O servidor, portanto, SEMPRE revalida tudo (veja o Exemplo 25).

2.8. Exemplo 08: React Hook Form

O formulário do Exemplo 07, escrito com o [React Hook Form], a biblioteca de formulários mais usada com o [React]:

// =========================================================================
// 08-react-hook-form/src/App.tsx - uma biblioteca de formulários
// -------------------------------------------------------------------------
// O formulário do exemplo 07, escrito com React Hook Form, a biblioteca de
// formulários mais usada com React. Ela é encontrada na maioria das
// aplicações existentes.
//   - useForm<T>() retorna as ferramentas para um formulário do tipo T;
//   - register('lastName', rules) liga um campo HTML ao campo "lastName" do
//     formulário: retorna os atributos a espalhar no elemento (name,
//     ref, onChange, onBlur). Os campos NÃO são controlados: é a
//     biblioteca que lê seu valor na página, sem chamar o
//     componente de novo a cada tecla digitada;
//   - as regras: required, maxLength, minLength, pattern, validate (uma
//     regra "caseira"), cada uma com sua mensagem;
//   - formState.errors: os erros de cada campo;
//   - handleSubmit(action): valida tudo; só chama a action se o
//     formulário for válido.
// =========================================================================

import { useState } from 'react';
import { useForm } from 'react-hook-form';

interface Account {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  password: string;
  confirmation: string;
}

const TITLES = ['Mr', 'Mme', 'Melle'];

export default function App() {
  const {
    register,
    handleSubmit,
    getValues,
    formState: { errors, isSubmitted },
  } = useForm<Account>({
    // os valores iniciais
    defaultValues: { title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '' },
    // quando validar: ao sair de um campo, depois a cada tecla digitada
    mode: 'onTouched',
  });
  const [sent, setSent] = useState('');

  // um campo é marcado com erro se tiver um (errors.lastName existe)
  const cssClass = (field: keyof Account) => `form-control${errors[field] ? ' is-invalid' : ''}`;

  // chamada por handleSubmit, SOMENTE se o formulário for válido;
  // ela recebe os valores, tipados
  function create(account: Account) {
    setSent(JSON.stringify(account));
  }

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 08 - React Hook Form</h1>
      <form className="card p-4" noValidate onSubmit={handleSubmit(create, () => setSent(''))}>
        <div className="mb-3">
          <label className="form-label" htmlFor="title">Title</label>
          <select id="title" className="form-select" {...register('title', { required: true })}>
            {TITLES.map((t) => <option key={t}>{t}</option>)}
          </select>
        </div>
        <div className="row g-3 mb-3">
          <div className="col-sm-6">
            <label className="form-label" htmlFor="firstName">First name</label>
            <input id="firstName" className={cssClass('firstName')}
                   {...register('firstName', {
                     required: 'The first name is required.',
                     maxLength: { value: 20, message: '20 characters at most.' },
                   })} />
            {/* errors.firstName?.message: a mensagem da regra que falhou */}
            <div className="invalid-feedback">{errors.firstName?.message}</div>
          </div>
          <div className="col-sm-6">
            <label className="form-label" htmlFor="lastName">Last name</label>
            <input id="lastName" className={cssClass('lastName')}
                   {...register('lastName', {
                     required: 'The last name is required.',
                     maxLength: { value: 20, message: '20 characters at most.' },
                   })} />
            <div className="invalid-feedback">{errors.lastName?.message}</div>
          </div>
        </div>
        <div className="mb-3">
          <label className="form-label" htmlFor="login">Login</label>
          <input id="login" className={cssClass('login')}
                 {...register('login', {
                   required: 'The login is required.',
                   pattern: { value: /^[a-z0-9._-]{1,30}$/, message: 'Unaccented lower-case letters, digits, dot, hyphen, underscore.' },
                 })} />
          <div className="invalid-feedback">{errors.login?.message}</div>
        </div>
        <div className="row g-3 mb-4">
          <div className="col-sm-6">
            <label className="form-label" htmlFor="password">Password</label>
            <input id="password" type="password" className={cssClass('password')}
                   {...register('password', {
                     required: 'The password is required.',
                     minLength: { value: 6, message: 'At least 6 characters.' },
                     // deps: quando a senha muda, revalide TAMBÉM a confirmação
                     deps: ['confirmation'],
                   })} />
            <div className="invalid-feedback">{errors.password?.message}</div>
          </div>
          <div className="col-sm-6">
            <label className="form-label" htmlFor="confirmation">Confirmation</label>
            {/* validate: uma regra "caseira"; getValues lê OUTRO campo */}
            <input id="confirmation" type="password" className={cssClass('confirmation')}
                   {...register('confirmation', {
                     validate: (value) => value === getValues('password') || 'The confirmation does not match the password.',
                   })} />
            <div className="invalid-feedback">{errors.confirmation?.message}</div>
          </div>
        </div>
        <button type="submit" className="btn btn-primary">Create the account</button>
        {isSubmitted && (
          <div className={`alert mt-3 mb-0 ${sent ? 'alert-success' : 'alert-danger'}`}>
            {sent ? <>Valid form: <code>{sent}</code></> : 'Invalid form.'}
          </div>
        )}
      </form>
    </div>
  );
}
  • linha 21: o hook principal da biblioteca;
  • linhas 35–40: [useForm<Account>(options)] retorna os componentes de um formulário do tipo [Account], que são desempacotados: [register], [handleSubmit], [getValues] e [formState], o estado do formulário (incluindo [errors], os erros dos campos, e [isSubmitted], que é verdadeiro após o primeiro envio);
  • linha 42: os valores iniciais;
  • linha 44: quando validar: ao sair de um campo e, depois, a cada tecla digitada;
  • linha 49: um campo é sinalizado como tendo erro se contiver um;
  • linhas 53–55: a ação de envio, chamada por [handleSubmit] somente se o formulário for válido; ela recebe os valores digitados;
  • linha 60: [handleSubmit(onValid, onInvalid)] cria o tratador de envio: ele valida todos os campos e depois chama uma função ou a outra;
  • linhas 71–74: [register('firstName', rules)] vincula o campo HTML ao campo [firstName] do formulário, com suas regras: [required], [maxLength], [minLength], [pattern] e [validate] (uma regra “personalizada”), cada uma com sua própria mensagem. [register] retorna os atributos a serem aplicados ao elemento ([name], [ref], [onChange], [onBlur]). Os campos NÃO são controlados: a biblioteca lê seus valores da página por meio da referência; assim, o componente não é reexecutado a cada tecla digitada, o que é importante em formulários grandes;
  • linha 76: a mensagem de uma regra de validação que falhou ([?.]: [undefined] se o campo não tiver erros);
  • linha 105: quando a senha muda, revalide também a confirmação;
  • linha 114: uma regra personalizada que compara dois campos: [getValues('password')] lê o valor de outro campo. Ela retorna [true] (válido) ou a mensagem de erro.

Image

Para o [React], cada necessidade tem várias bibliotecas concorrentes. Para formulários, também encontramos [Formik], [TanStack Form] e, para descrever as regras, [Zod] ou [Yup] (“schemas” de validação que podem ser compartilhados com um servidor [Node.js] ). No estudo de caso, em que toda a validação é feita pelo servidor, não usaremos uma biblioteca: campos controlados e um hook personalizado bastarão.

2.9. Exemplo 09: Formatação de valores

[Angular] tem seus próprios “pipes” para formatar um valor em um template. [React] não tem um mecanismo próprio: em JSX, chamamos funções armazenadas em um módulo. Para datas, números e valores monetários, o navegador fornece a API [Intl], que entende as convenções de cada idioma.

2.9.1. Funções de formatação

// =========================================================================
// 09-formatting/src/formatting.ts - funções de formatação "caseiras"
// -------------------------------------------------------------------------
// O React não tem mecanismo próprio de formatação (o Angular tem seus
// "pipes", o Vue.js suas funções): no JSX, chamamos
// FUNÇÕES comuns, guardadas em um módulo e testáveis isoladamente:
//     {timeRange(slot)}           -> "8:00 - 8:20"
//     {timeRange(slot, 'start')}  -> "8:00"
// Para datas, números e valores monetários, o navegador fornece a API
// Intl, que conhece as convenções de cada idioma.
// =========================================================================

export interface Slot {
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
}

// "8:05" em vez de "8:5"
function time(h: number, m: number): string {
  return `${h}:${String(m).padStart(2, '0')}`;
}

export function timeRange(c: Slot, part: 'all' | 'start' | 'end' = 'all'): string {
  switch (part) {
    case 'start':
      return time(c.startHour, c.startMinute);
    case 'end':
      return time(c.endHour, c.endMinute);
    default:
      return `${time(c.startHour, c.startMinute)} - ${time(c.endHour, c.endMinute)}`;
  }
}

// "marie pelissier" -> "Marie Pelissier"
export function capitalize(text: string): string {
  return text.replace(/\p{L}+/gu, (word) => word[0].toUpperCase() + word.slice(1).toLowerCase());
}

// "Marie PELISSIER" -> "MP"
export function initials(fullName: string): string {
  return fullName
    .split(/\s+/)
    .filter((word) => word !== '')
    .map((word) => word[0].toUpperCase())
    .join('');
}

// "2026-10-05" (o formato da API RdvMedecins) -> uma Date, à meia-noite UTC
export function toDate(day: string): Date {
  return new Date(`${day}T00:00:00Z`);
}
  • linhas 13–18: um intervalo de horário, conforme enviado pelo servidor [RdvMedecins] (horas e minutos de início e de fim);
  • linhas 21–23: [padStart(2, '0')] preenche a string à esquerda: “5” vira “05”;
  • linhas 25–34: “8:00 – 8:20”, ou apenas o início ou o fim, dependendo do parâmetro [part], que é opcional (valor padrão ['all']);
  • linhas 37–39: [\p{L}+] designa uma sequência de letras, incluindo caracteres acentuados (opção [u]): a primeira letra é posta em maiúscula;
  • linhas 51–53: uma data no formato da API (["2026-10-05"]) torna-se um objeto [Date] à meia-noite UTC.

2.9.2. A página

// =========================================================================
// 09-formatting/src/App.tsx - formatando valores no JSX
// -------------------------------------------------------------------------
// Cada linha da tabela mostra um trecho de código e o que ele exibe.
// Os formatadores Intl são criados uma vez por todas, fora do componente:
// construí-los custa mais do que usá-los.
// =========================================================================

import { useState } from 'react';
import { timeRange, initials, capitalize, toDate, type Slot } from './formatting';

// datas: dateStyle / timeStyle, ou o detalhe das partes a exibir
const shortDate = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' });
const fullDate = new Intl.DateTimeFormat('en-US', { dateStyle: 'full' });
const timeOnly = new Intl.DateTimeFormat('en-US', { timeStyle: 'medium' });
const longDay = new Intl.DateTimeFormat('en-US', { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' });
const frenchDay = new Intl.DateTimeFormat('fr-FR', { dateStyle: 'long', timeZone: 'UTC' });
// números e valores monetários
const euros = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' });
const integer = new Intl.NumberFormat('en-US', { maximumFractionDigits: 0 });
const percent = new Intl.NumberFormat('en-US', { style: 'percent', minimumFractionDigits: 1 });

const day = '2026-10-05'; // uma data no formato da API RdvMedecins
const price = 1234.5;
const rate = 0.055;
const name = 'marie pelissier';
const doctor = { title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER' };
const languages = ['TypeScript', 'HTML', 'CSS', 'JavaScript', 'SQL'];
const slots: Slot[] = [
  { startHour: 8, startMinute: 0, endHour: 8, endMinute: 20 },
  { startHour: 8, startMinute: 20, endHour: 8, endMinute: 40 },
  { startHour: 14, startMinute: 5, endHour: 14, endMinute: 25 },
];

export default function App() {
  const [now, setNow] = useState(() => new Date());

  // [código exibido, valor]: uma linha da tabela
  const rows: [string, string][] = [
    ['shortDate.format(now)', shortDate.format(now)],
    ['fullDate.format(now)', fullDate.format(now)],
    ['timeOnly.format(now)', timeOnly.format(now)],
    ['longDay.format(toDate(day))', longDay.format(toDate(day))],
    ['frenchDay.format(toDate(day))', frenchDay.format(toDate(day))],
    ['now.toLocaleDateString()', now.toLocaleDateString()],
    ['euros.format(price)', euros.format(price)],
    ['integer.format(price)', integer.format(price)],
    ['percent.format(rate)', percent.format(rate)],
    ['name.toUpperCase()', name.toUpperCase()],
    ['capitalize(name)', capitalize(name)],
    ["'RDV'.toLowerCase()", 'RDV'.toLowerCase()],
    ["languages.slice(0, 3).join(', ')", languages.slice(0, 3).join(', ')],
    ['JSON.stringify(doctor)', JSON.stringify(doctor)],
    // duas funções em sequência: o resultado da primeira vai para a segunda
    ['initials(capitalize(name))', initials(capitalize(name))],
  ];

  return (
    <div className="container py-4" style={{ maxWidth: 820 }}>
      <h1 className="h3 mb-3">Example 09 - the formatting of values</h1>
      <table className="table table-sm align-middle">
        <thead><tr><th>In the code</th><th>Displayed</th></tr></thead>
        <tbody>
          {rows.map(([code, value]) => (
            <tr key={code}><td><code>{`{${code}}`}</code></td><td>{value}</td></tr>
          ))}
        </tbody>
      </table>

      <h2 className="h6">Object.entries: going through the properties of an object</h2>
      <ul>
        {Object.entries(doctor).map(([key, value]) => (
          <li key={key}>{key} = {value}</li>
        ))}
      </ul>

      <h2 className="h6">A home-made function: timeRange</h2>
      <ul>
        {slots.map((c) => (
          <li key={timeRange(c)}>{timeRange(c)} (start: {timeRange(c, 'start')})</li>
        ))}
      </ul>
      <button className="btn btn-sm btn-outline-primary" onClick={() => setNow(new Date())}>Refresh the time</button>
    </div>
  );
}
  • linhas 13–17: formatadores de data, [Intl.DateTimeFormat(language, options)]: [dateStyle] e [timeStyle] oferecem formatos predefinidos ([full], [long], [medium], [short]); também é possível especificar quais partes exibir ([weekday], [day], [month], [year]). [timeZone: 'UTC']: a data [2026-10-05T00:00:00Z] deve continuar sendo 5 de outubro, qualquer que seja o fuso horário do navegador;
  • Linhas 19–21: formatadores de número: um valor em euros, um número sem casas decimais, uma porcentagem;
  • linhas 39–56: linhas da tabela: o código e seu valor. A última encadeia duas funções;
  • linha 65: o código entre chaves;
  • linhas 72–74: [Object.entries(object)] retorna os pares [chave, valor] de um objeto, que são percorridos com [map];
  • linhas 79–81: a função personalizada [timeRange].

Image

Os geradores [Intl] são criados de uma vez por todas, fora do componente: criá-los custa mais do que usá-los. O idioma é fixado ali no código ([en-US], e [fr-FR] para a linha em francês); o Exemplo 21 mostrará como seguir o idioma escolhido pelo usuário.