M

MLOG

Português

Um guia completo sobre o hook useFormStatus do React, capacitando desenvolvedores a criar experiências de submissão de formulários envolventes e informativas para usuários globais.

React useFormStatus: Dominando o Estado de Submissão de Formulários

Formulários são a espinha dorsal de inúmeras aplicações web, servindo como o principal meio para os usuários interagirem e fornecerem dados aos servidores. Garantir um processo de submissão de formulário suave e informativo é crucial para criar experiências de usuário positivas. O React 18 introduziu um poderoso hook chamado useFormStatus, projetado para simplificar o gerenciamento do estado de submissão de formulários. Este guia oferece uma visão abrangente do useFormStatus, explorando suas funcionalidades, casos de uso e melhores práticas para construir formulários acessíveis e envolventes para uma audiência global.

O que é o React useFormStatus?

useFormStatus é um Hook do React que fornece informações sobre o status de submissão de um formulário. Ele foi projetado para funcionar perfeitamente com server actions, um recurso que permite executar lógica do lado do servidor diretamente de seus componentes React. O hook retorna um objeto contendo informações sobre o estado pendente do formulário, dados e quaisquer erros que ocorreram durante a submissão. Essas informações permitem que você forneça feedback em tempo real aos usuários, como exibir indicadores de carregamento, desabilitar elementos do formulário e mostrar mensagens de erro.

Entendendo as Server Actions

Antes de mergulhar no useFormStatus, é essencial entender as server actions. Server actions são funções assíncronas que rodam no servidor e podem ser invocadas diretamente de componentes React. Elas são definidas usando a diretiva 'use server' no topo do arquivo. Server actions são comumente usadas para tarefas como:

Aqui está um exemplo simples de uma server action:

// actions.js
'use server';

export async function submitForm(formData) {
  // Simula um atraso para imitar uma requisição ao servidor
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  const email = formData.get('email');

  if (!name || !email) {
    return { message: 'Por favor, preencha todos os campos.' };
  }

  // Simula uma submissão bem-sucedida
  return { message: `Formulário enviado com sucesso para ${name}!` };
}

Esta action recebe dados do formulário como entrada, simula um atraso e, em seguida, retorna uma mensagem de sucesso ou erro. A diretiva 'use server' informa ao React que esta função deve ser executada no servidor.

Como o useFormStatus Funciona

O hook useFormStatus é usado dentro de um componente que renderiza um formulário. Ele precisa ser usado dentro de um elemento <form> que usa a prop `action` com a Server Action importada. O hook retorna um objeto com as seguintes propriedades:

Aqui está um exemplo de como usar useFormStatus em um componente React:

'use client'
import { useFormStatus } from 'react-dom';
import { submitForm } from './actions';

function MyForm() {
  const { pending, data, error, action } = useFormStatus();

  return (
    <form action={submitForm}>
      <label htmlFor="name">Nome:</label>
      <input type="text" id="name" name="name" disabled={pending} />
      <label htmlFor="email">Email:</label>
      <input type="email" id="email" name="email" disabled={pending} />
      <button type="submit" disabled={pending}>
        {pending ? 'Enviando...' : 'Enviar'}
      </button>
      {error && <p style={{ color: 'red' }}>Erro: {error.message}</p>}
      {data && data.message && <p style={{ color: 'green' }}>{data.message}</p>}
    </form>
  );
}

export default MyForm;

Neste exemplo:

Benefícios de Usar o useFormStatus

useFormStatus oferece várias vantagens para gerenciar o estado de submissão de formulários:

Melhores Práticas para Usar o useFormStatus

Para maximizar os benefícios do useFormStatus, considere as seguintes melhores práticas:

Casos de Uso para o useFormStatus

useFormStatus é aplicável em uma ampla gama de cenários:

Abordando a Internacionalização (i18n)

Ao construir formulários para uma audiência global, a internacionalização (i18n) é crucial. Veja como abordar a i18n ao usar useFormStatus:

Exemplo com i18next:

// i18n.js
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

import en from './locales/en.json';
import fr from './locales/fr.json';

i18n
  .use(initReactI18next)
  .init({
    resources: {
      en: { translation: en },
      fr: { translation: fr },
    },
    lng: 'en',
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false, // react already safes from xss
    },
  });

export default i18n;

// MyForm.js

import { useTranslation } from 'react-i18next';

function MyForm() {
  const { t } = useTranslation();
  const { pending, data, error, action } = useFormStatus();

  return (
    <form action={submitForm}>
      <label htmlFor="name">{t('name')}:</label>
      <input type="text" id="name" name="name" disabled={pending} />
      <label htmlFor="email">{t('email')}:</label>
      <input type="email" id="email" name="email" disabled={pending} />
      <button type="submit" disabled={pending}>
        {pending ? t('submitting') : t('submit')}
      </button>
      {error && <p style={{ color: 'red' }}>{t('error')}: {t(error.message)}</p>}
      {data && data.message && <p style={{ color: 'green' }}>{t(data.message)}</p>}
    </form>
  );
}

export default MyForm;

Considerações de Acessibilidade

Garantir a acessibilidade é primordial ao construir formulários. Veja como tornar seus formulários mais acessíveis ao usar useFormStatus:

Exemplo com atributos ARIA:

function MyForm() {
  const { pending, data, error, action } = useFormStatus();

  return (
    <form action={submitForm}>
      <label htmlFor="name">Nome:</label>
      <input
        type="text"
        id="name"
        name="name"
        disabled={pending}
        aria-invalid={!!error} // Indica se há um erro
        aria-describedby={error ? 'name-error' : null} // Associa a mensagem de erro
      />
      {error && (
        <p id="name-error" style={{ color: 'red' }} aria-live="polite">{error.message}</p>
      )}
      <label htmlFor="email">Email:</label>
      <input type="email" id="email" name="email" disabled={pending} />
      <button type="submit" disabled={pending}>
        {pending ? 'Enviando...' : 'Enviar'}
      </button>
      {data && data.message && <p style={{ color: 'green' }}>{data.message}</p>}
    </form>
  );
}

Além do Uso Básico: Técnicas Avançadas

Embora o uso básico do useFormStatus seja direto, várias técnicas avançadas podem aprimorar ainda mais sua experiência de submissão de formulário:

Solucionando Problemas Comuns

Ao usar useFormStatus, você pode encontrar alguns problemas comuns. Veja como solucioná-los:

Alternativas ao useFormStatus

Embora useFormStatus seja uma ferramenta poderosa, existem abordagens alternativas para gerenciar o estado de submissão de formulários, especialmente em versões mais antigas do React ou ao lidar com lógicas de formulário complexas:

A escolha da abordagem depende da complexidade do seu formulário e de seus requisitos específicos. Para formulários simples, useFormStatus é frequentemente a solução mais direta e eficiente. Para formulários mais complexos, uma biblioteca de formulário ou uma solução de gerenciamento de estado global pode ser mais apropriada.

Conclusão

useFormStatus é uma adição valiosa ao ecossistema React, simplificando o gerenciamento do estado de submissão de formulários e permitindo que os desenvolvedores criem experiências de usuário mais envolventes e informativas. Ao entender suas funcionalidades, melhores práticas e casos de uso, você pode aproveitar o useFormStatus para construir formulários acessíveis, internacionalizados e performáticos para uma audiência global. Adotar o useFormStatus agiliza o desenvolvimento, aprimora a interação do usuário e, em última análise, contribui para aplicações web mais robustas e amigáveis.

Lembre-se de priorizar a acessibilidade, a internacionalização e o desempenho ao construir formulários para uma audiência global. Seguindo as melhores práticas descritas neste guia, você pode criar formulários que são utilizáveis por todos, independentemente de sua localização ou habilidades. Essa abordagem contribui para uma web mais inclusiva e acessível para todos os usuários.