React experimental_useFormState: Komplexní průvodce pro vylepšené zpracování formulářů

Neustále se vyvíjející ekosystém Reactu průběžně zavádí inovativní nástroje pro zlepšení vývojářského zážitku a výkonu aplikací. Jedním z takových pokroků je Hook experimental_useFormState. Tento hook, v současné době v experimentálním stádiu, poskytuje výkonný a zjednodušený přístup ke správě stavu formuláře a zpracování asynchronních akcí, zejména v kombinaci s React Server Components a Actions. Tento průvodce se ponoří do složitostí experimental_useFormState, prozkoumá jeho výhody, případy použití a implementační strategie.

Co je experimental_useFormState?

Hook experimental_useFormState je navržen tak, aby zjednodušil správu formulářů v React aplikacích. Nabízí deklarativní způsob, jak spravovat stav formuláře, chyby a asynchronní odesílání. Na rozdíl od tradičních metod, které často zahrnují manuální aktualizace stavu a komplexní zpracování událostí, experimental_useFormState tento proces zjednodušuje poskytnutím jediného hooku pro správu celého životního cyklu formuláře.

Ve svém jádru experimental_useFormState umožňuje asociovat stavovou hodnotu s funkcí, která provádí logiku odeslání formuláře. Tato funkce, typicky serverová akce v kontextu React Server Components, je zodpovědná za validaci dat a provádění nezbytných mutací. Hook poté spravuje stav provádění této funkce a poskytuje uživateli zpětnou vazbu o stavu formuláře (např. načítání, úspěch, chyba).

Výhody použití experimental_useFormState

• Zjednodušená logika formuláře: Snižuje množství opakujícího se kódu centralizací správy stavu formuláře v rámci jediného hooku.
• Vylepšený výkon: Optimalizuje vykreslování minimalizací zbytečných aktualizací a využitím serverových datových mutací.
• Deklarativní přístup: Podporuje čitelnější a udržitelnější kódovou základnu prostřednictvím deklarativního programovacího stylu.
• Bezproblémová integrace se serverovými akcemi: Navrženo pro bezproblémovou spolupráci s React Server Components a Actions, což umožňuje efektivní načítání dat a mutace.
• Vylepšená uživatelská zkušenost: Poskytuje uživateli jasnou a stručnou zpětnou vazbu ohledně stavu formuláře, čímž zlepšuje celkovou uživatelskou zkušenost.

Případy použití pro experimental_useFormState

Hook experimental_useFormState je obzvláště vhodný pro scénáře zahrnující složité formuláře, které vyžadují serverovou validaci a datové mutace. Zde jsou některé běžné případy použití:

• Autentizační formuláře: Zpracování registrace uživatelů, přihlášení a formulářů pro resetování hesla.
• E-commerce formuláře: Zpracování formulářů pro pokladnu, aktualizaci uživatelských profilů a správu seznamů produktů.
• Systémy pro správu obsahu (CMS): Vytváření a úprava článků, správa uživatelských rolí a konfigurace nastavení webu.
• Platformy sociálních médií: Zveřejňování aktualizací, odesílání komentářů a správa uživatelských profilů.
• Formuláře pro zadávání dat: Zachytávání a validace dat z různých zdrojů, jako jsou průzkumy, formuláře zpětné vazby a informace o zákaznících.

Příklad implementace: Jednoduchý kontaktní formulář

Ilustrujme použití experimental_useFormState praktickým příkladem: jednoduchým kontaktním formulářem. Tento formulář shromáždí jméno, e-mail a zprávu uživatele a poté odešle data serverové akci ke zpracování.

1. Definujte serverovou akci

Nejprve musíme definovat serverovou akci, která zpracovává odeslání formuláře. Tato akce ověří data a odešle e-mailové oznámení.

            // app/actions.js
'use server';

import { revalidatePath } from 'next/cache';
import { sendEmail } from './utils/email'; // Example email sending function

export async function submitContactForm(prevState, formData) {
  const name = formData.get('name');
  const email = formData.get('email');
  const message = formData.get('message');

  // Basic validation
  if (!name || !email || !message) {
    return 'Please fill in all fields.';
  }

  try {
    await sendEmail({
      to: 'admin@example.com', // Replace with your admin email
      subject: 'New Contact Form Submission',
      text: `Name: ${name}\nEmail: ${email}\nMessage: ${message}`,
    });

    revalidatePath('/'); // Revalidate the homepage or relevant path
    return 'Thank you for your message!';
  } catch (error) {
    console.error('Error sending email:', error);
    return 'An error occurred. Please try again later.';
  }
}

            

              
                Copy
              
            
          

Vysvětlení:

• Direktiva 'use server' indikuje, že tato funkce by měla být spuštěna na serveru.
• Funkce přijímá předchozí stav (prevState) a data formuláře (formData) jako argumenty.
• Extrahuje jméno, e-mail a zprávu z dat formuláře.
• Provádí základní validaci, aby se zajistilo, že všechna požadovaná pole jsou vyplněna.
• Používá asynchronní funkci sendEmail (kterou budete muset implementovat samostatně) k odeslání e-mailového oznámení. To by mohlo používat službu jako SendGrid, Mailgun nebo AWS SES.
• revalidatePath('/') nutí Next.js znovu načíst data pro domovskou stránku, čímž zajišťuje, že se okamžitě projeví všechny relevantní změny.
• Vrací zprávu o úspěchu nebo chybě pro aktualizaci stavu formuláře.

2. Implementujte komponentu React

Nyní vytvoříme React komponentu, která používá experimental_useFormState ke správě stavu formuláře a zpracování odeslání.

            'use client';

import { experimental_useFormState as useFormState } from 'react';
import { submitContactForm } from './actions';

function ContactForm() {
  const [state, formAction] = useFormState(submitContactForm, null);

  return (
    <form action={formAction}>
      <div>
        <label htmlFor="name">Name:</label>
        <input type="text" id="name" name="name" required />
      </div>
      <div>
        <label htmlFor="email">Email:</label>
        <input type="email" id="email" name="email" required />
      </div>
      <div>
        <label htmlFor="message">Message:</label>
        <textarea id="message" name="message" rows="4" required />
      </div>
      <button type="submit">Submit</button>
      {state && <p>{state}</p>}
    </form>
  );
}

export default ContactForm;

            

              
                Copy
              
            
          

Vysvětlení:

• Direktiva 'use client' indikuje, že tato komponenta je klientská komponenta.
• Importujeme experimental_useFormState jako useFormState pro stručnost a akci submitContactForm.
• Voláme useFormState, předáváme akci submitContactForm a počáteční stav null.
• Hook vrací aktuální stav (state) a funkci (formAction), která spouští odeslání formuláře.
• Připojíme funkci formAction k propu action elementu form. To je klíčové pro správné zpracování odeslání formuláře Reactem.
• Formulář obsahuje vstupní pole pro jméno, e-mail a zprávu, stejně jako tlačítko pro odeslání.
• Řádek {state && <p>{state}</p>} zobrazuje uživateli aktuální stav (zprávu o úspěchu nebo chybě).

3. Nastavení vaší služby pro odesílání e-mailů (příklad sendEmail)

Budete muset implementovat funkci sendEmail. Zde je příklad použití Nodemailer s účtem Gmail (Poznámka: Přímé používání Gmailu v produkci se obecně nedoporučuje. Pro produkční prostředí používejte specializovanou e-mailovou službu, jako je SendGrid, Mailgun nebo AWS SES):

            // app/utils/email.js
import nodemailer from 'nodemailer';

export async function sendEmail({ to, subject, text }) {
  // Create a transporter object using Gmail SMTP
  const transporter = nodemailer.createTransport({
    service: 'gmail',
    auth: {
      user: 'your_gmail_address@gmail.com', // Replace with your Gmail address
      pass: 'your_gmail_password',       // Replace with your Gmail password or App Password
    },
  });

  // Define the email options
  const mailOptions = {
    from: 'your_gmail_address@gmail.com',
    to: to,
    subject: subject,
    text: text,
  };

  // Send the email
  try {
    await transporter.sendMail(mailOptions);
    console.log('Email sent successfully');
  } catch (error) {
    console.error('Error sending email:', error);
    throw error; // Re-throw the error to be caught in the server action
  }
}

            

              
                Copy
              
            
          

Důležitá bezpečnostní poznámka: Nikdy nekomitujte své skutečné heslo k Gmailu přímo do svého kódu! Používejte proměnné prostředí k ukládání citlivých informací. Pro produkční použití vygenerujte heslo aplikace speciálně pro Nodemailer a vyhněte se používání hlavního hesla k Gmailu. Specializované služby pro odesílání e-mailů nabízejí lepší doručitelnost a zabezpečení ve srovnání s přímým používáním Gmailu.

4. Spuštění příkladu

Ujistěte se, že máte nainstalované potřebné závislosti:

            npm install nodemailer

            

              
                Copy
              
            
          

nebo

            yarn add nodemailer

            

              
                Copy
              
            
          

Poté spusťte svůj vývojový server Next.js:

            npm run dev

            

              
                Copy
              
            
          

nebo

            yarn dev

            

              
                Copy
              
            
          

Otevřete svůj prohlížeč a přejděte na stránku obsahující komponentu ContactForm. Vyplňte formulář a odešlete jej. Měli byste vidět buď zprávu o úspěchu, nebo chybovou zprávu zobrazenou pod formulářem. Zkontrolujte svou e-mailovou schránku, abyste ověřili, že e-mail byl úspěšně odeslán.

Pokročilé použití a úvahy

1. Zpracování stavů načítání

Pro zajištění lepší uživatelské zkušenosti je důležité indikovat, kdy se formulář odesílá. Zatímco experimental_useFormState přímo neexponuje stav načítání, můžete to spravovat ručně pomocí hooku useTransition v Reactu ve spojení s formAction.

            'use client';

import { experimental_useFormState as useFormState, useTransition } from 'react';
import { submitContactForm } from './actions';

function ContactForm() {
  const [state, formAction] = useFormState(submitContactForm, null);
  const [isPending, startTransition] = useTransition();

  const handleSubmit = async (formData) => {
    startTransition(() => {
      formAction(formData);
    });
  };

  return (
    <form action={handleSubmit}>
      <div>
        <label htmlFor="name">Name:</label>
        <input type="text" id="name" name="name" required />
      </div>
      <div>
        <label htmlFor="email">Email:</label>
        <input type="email" id="email" name="email" required />
      </div>
      <div>
        <label htmlFor="message">Message:</label>
        <textarea id="message" name="message" rows="4" required />
      </div>
      <button type="submit" disabled={isPending}>
        {isPending ? 'Submitting...' : 'Submit'}
      </button>
      {state && <p>{state}</p>}
    </form>
  );
}

export default ContactForm;

            

              
                Copy
              
            
          

V tomto příkladu:

• Importujeme useTransition z 'react'.
• Voláme useTransition, abychom získali stav isPending a funkci startTransition.
• Volání formAction obalíme do startTransition. Tím Reactu říkáme, aby odeslání formuláře považoval za přechod, což umožňuje jeho přerušení v případě potřeby.
• Zakážeme tlačítko pro odeslání, když je isPending true, a změníme text tlačítka na "Odesílání...".

2. Zpracování chyb a validace

Robustní zpracování chyb je klíčové pro zajištění dobré uživatelské zkušenosti. Serverová akce by měla provést důkladnou validaci a vrátit klientovi informativní chybové zprávy. Komponenta klienta pak může tyto zprávy zobrazit uživateli.

Validace na straně serveru: Vždy validujte data na serveru, abyste zabránili škodlivému vstupu a zajistili integritu dat. Použijte knihovny jako Zod nebo Yup pro validaci schématu.

Validace na straně klienta (volitelné): Zatímco validace na straně serveru je nezbytná, validace na straně klienta může uživateli poskytnout okamžitou zpětnou vazbu a zlepšit uživatelskou zkušenost. Na validaci na straně klienta by se však nikdy nemělo spoléhat jako na jediný zdroj pravdy.

3. Optimistické aktualizace

Optimistické aktualizace mohou způsobit, že se vaše aplikace bude cítit citlivější tím, že okamžitě aktualizuje UI, jako by odeslání formuláře bylo úspěšné, ještě předtím, než to server potvrdí. Buďte však připraveni zpracovat chyby a vrátit změny zpět, pokud odeslání selže.

S experimental_useFormState můžete implementovat optimistické aktualizace aktualizací lokálního stavu na základě dat formuláře před voláním formAction. Pokud serverová akce selže, můžete změny vrátit zpět na základě chybové zprávy vrácené hookem.

4. Revalidace a cachování

React Server Components a Actions využívají cachování ke zlepšení výkonu. Když odeslání formuláře upraví data, je důležité revalidovat cache, aby se zajistilo, že UI odráží nejnovější změny.

Funkce revalidatePath a revalidateTag z next/cache lze použít k invalidaci konkrétních částí cache. V příkladu submitContactForm se revalidatePath('/') používá k revalidaci domovské stránky po úspěšném odeslání formuláře.

5. Internacionalizace (i18n)

Při budování aplikací pro globální publikum je internacionalizace (i18n) klíčová. To zahrnuje přizpůsobení vaší aplikace různým jazykům, regionům a kulturním preferencím.

Pro formuláře to znamená poskytování lokalizovaných popisků, chybových zpráv a validačních pravidel. Použijte i18n knihovny jako next-intl nebo react-i18next ke správě překladů a formátování dat podle lokále uživatele.

Příklad použití next-intl:

            // i18n.js (example)
import { createTranslator } from 'next-intl';

const messages = {
  en: {
    ContactForm: {
      NameLabel: 'Name',
      EmailLabel: 'Email',
      MessageLabel: 'Message',
      SubmitButton: 'Submit',
      SuccessMessage: 'Thank you for your message!',
      ErrorMessage: 'An error occurred. Please try again later.',
      NameRequired: 'Name is required',
      EmailRequired: 'Email is required',
      MessageRequired: 'Message is required',
    },
  },
  es: {
    ContactForm: {
      NameLabel: 'Nombre',
      EmailLabel: 'Correo electrónico',
      MessageLabel: 'Mensaje',
      SubmitButton: 'Enviar',
      SuccessMessage: '¡Gracias por tu mensaje!',
      ErrorMessage: 'Ocurrió un error. Inténtalo de nuevo más tarde.',
      NameRequired: 'El nombre es obligatorio',
      EmailRequired: 'El correo electrónico es obligatorio',
      MessageRequired: 'El mensaje es obligatorio',
    },
  },
  // Add more languages as needed
};

export async function getTranslations(locale) {
  return createTranslator({ locale, messages });
}

            

              
                Copy
              
            
          

            // ContactForm.js
'use client';

import { experimental_useFormState as useFormState, useTransition } from 'react';
import { submitContactForm } from './actions';
import { useLocale, useTranslations } from 'next-intl';

function ContactForm() {
  const [state, formAction] = useFormState(submitContactForm, null);
  const [isPending, startTransition] = useTransition();
  const t = useTranslations('ContactForm');

  const handleSubmit = async (formData) => {
    startTransition(() => {
      formAction(formData);
    });
  };

  return (
    <form action={handleSubmit}>
      <div>
        <label htmlFor="name">{t('NameLabel')}:</label>
        <input type="text" id="name" name="name" required />
      </div>
      <div>
        <label htmlFor="email">{t('EmailLabel')}:</label>
        <input type="email" id="email" name="email" required />
      </div>
      <div>
        <label htmlFor="message">{t('MessageLabel')}:</label>
        <textarea id="message" name="message" rows="4" required />
      </div>
      <button type="submit" disabled={isPending}>
        {isPending ? 'Submitting...' : t('SubmitButton')}
      </button>
      {state && <p>{state === 'Thank you for your message!' ? t('SuccessMessage') : t('ErrorMessage')}</p>}
    </form>
  );
}

export default ContactForm;

            

              
                Copy
              
            
          

6. Přístupnost (a11y)

Přístupnost je klíčová pro zajištění, aby vaše aplikace byla použitelná pro každého, včetně lidí s postižením. Při vytváření formulářů zvažte následující pokyny pro přístupnost:

• Používejte sémantické HTML: Používejte vhodné HTML elementy, jako jsou <label>, <input> a <textarea>, k poskytnutí struktury a významu vašemu formuláři.
• Poskytněte popisky pro všechna pole formuláře: Asociujte popisky s poli formuláře pomocí atributu for na elementu <label> a atributu id na poli formuláře.
• Používejte atributy ARIA: Používejte atributy ARIA k poskytnutí dalších informací o struktuře a chování formuláře asistenčním technologiím.
• Zajistěte dostatečný barevný kontrast: Používejte dostatečný barevný kontrast mezi textem a barvami pozadí, abyste zajistili čitelnost pro lidi se zrakovým postižením.
• Zajistěte navigaci pomocí klávesnice: Zajistěte, aby uživatelé mohli navigovat formulářem pouze pomocí klávesnice.
• Testujte s asistenčními technologiemi: Testujte svůj formulář s asistenčními technologiemi, jako jsou čtečky obrazovky, abyste zajistili, že je přístupný pro lidi s postižením.

Globální úvahy a osvědčené postupy

1. Časová pásma

Při práci s daty a časy ve formulářích je důležité zvážit časová pásma. Ukládejte data a časy ve formátu UTC na serveru a převádějte je na lokální časové pásmo uživatele na klientovi.

2. Měny

Při práci s peněžními hodnotami ve formulářích je důležité správně zacházet s měnami. Použijte knihovnu pro formátování měn k formátování hodnot podle lokále uživatele a zobrazení příslušného symbolu měny.

3. Adresy

Formáty adres se značně liší napříč různými zeměmi. Použijte knihovnu, která podporuje mezinárodní formáty adres, abyste zajistili, že uživatelé mohou správně zadávat své adresy.

4. Telefonní čísla

Formáty telefonních čísel se také liší napříč různými zeměmi. Použijte knihovnu pro formátování telefonních čísel k formátování telefonních čísel podle lokále uživatele a ověřte, že se jedná o platná telefonní čísla.

5. Ochrana osobních údajů a dodržování předpisů

Buďte si vědomi předpisů o ochraně osobních údajů, jako jsou GDPR a CCPA, při shromažďování a zpracování dat formuláře. Získejte souhlas uživatelů před shromažďováním jejich dat a poskytněte jim možnost přístupu, úpravy a odstranění jejich dat.

Závěr

Hook experimental_useFormState nabízí slibný přístup ke zjednodušení správy formulářů v React aplikacích. Využitím serverových akcí a přijetím deklarativního stylu mohou vývojáři vytvářet efektivnější, udržitelnější a uživatelsky přívětivější formuláře. Ačkoliv je stále v experimentálním stádiu, experimental_useFormState má značný potenciál pro zefektivnění pracovních toků formulářů a vylepšení celkového vývojářského zážitku v Reactu. Dodržováním osvědčených postupů uvedených v tomto průvodci můžete efektivně využít sílu experimental_useFormState k vytváření robustních a škálovatelných řešení formulářů pro vaše aplikace.

Nezapomeňte vždy sledovat nejnovější dokumentaci Reactu a komunitní diskuze, jak se API vyvíjí z experimentálního na stabilní.