React useFormStatus: Kompleksowy przewodnik po zarządzaniu stanem formularza

Hook useFormStatus, wprowadzony w React 18, dostarcza potężny i wydajny sposób na zarządzanie stanem wysyłania formularzy w ramach Komponentów Serwerowych React. Ten hook jest specjalnie zaprojektowany do współpracy z akcjami serwerowymi, oferując płynną integrację do obsługi przesyłania formularzy bezpośrednio na serwerze. Upraszcza proces śledzenia statusu wysyłania formularza, dostarczając cenne informacje, takie jak to, czy formularz jest w trakcie przetwarzania, czy jego wysłanie powiodło się, czy też napotkano błąd. Ten przewodnik bada możliwości useFormStatus, jego korzyści oraz praktyczne przykłady demonstrujące jego użycie w różnych scenariuszach.

Zrozumienie Akcji Serwerowych i useFormStatus

Przed zagłębieniem się w useFormStatus, kluczowe jest zrozumienie Komponentów Serwerowych React oraz Akcji Serwerowych. Akcje Serwerowe pozwalają definiować funkcje, które działają na serwerze i są bezpośrednio dostępne z komponentów React. Umożliwia to obsługę przesyłania formularzy, pobierania danych i innych operacji po stronie serwera bez potrzeby tworzenia oddzielnego punktu końcowego API.

Hook useFormStatus dostarcza wgląd w wykonanie tych Akcji Serwerowych, wywoływanych przez przesłanie formularza.

Czym jest useFormStatus?

useFormStatus to hook Reacta, który zwraca obiekt zawierający informacje o statusie ostatniego wysłania formularza. Informacje te obejmują:

• pending: Wartość logiczna (boolean) wskazująca, czy formularz jest aktualnie wysyłany.
• data: Obiekt FormData powiązany z wysłaniem.
• method: Metoda HTTP użyta do wysłania (zazwyczaj 'POST').
• action: Funkcja Akcji Serwerowej, która została wywołana.

Korzyści z używania useFormStatus

Wykorzystanie useFormStatus oferuje kilka kluczowych zalet:

• Uproszczone zarządzanie stanem: Eliminuje potrzebę ręcznego zarządzania stanem w celu śledzenia statusu wysyłania formularza. Hook automatycznie aktualizuje się w miarę postępu wysyłania.
• Lepsze doświadczenie użytkownika: Zapewnia użytkownikom informacje zwrotne w czasie rzeczywistym, takie jak wyświetlanie wskaźników ładowania podczas przetwarzania formularza lub pokazywanie komunikatów o błędach w przypadku niepowodzenia.
• Czysty kod: Promuje bardziej deklaratywny i łatwiejszy w utrzymaniu kod poprzez oddzielenie logiki wysyłania formularza od renderowania komponentu.
• Płynna integracja z Akcjami Serwerowymi: Zaprojektowany do doskonałej współpracy z Akcjami Serwerowymi, co ułatwia obsługę przesyłania formularzy bezpośrednio na serwerze.

Praktyczne przykłady użycia useFormStatus

Przyjrzyjmy się kilku praktycznym przykładom, aby zilustrować użycie useFormStatus w różnych scenariuszach.

Podstawowe wysyłanie formularza ze wskaźnikiem ładowania

Ten przykład demonstruje prosty formularz ze wskaźnikiem ładowania, który wyświetla się podczas wysyłania formularza.

Akcja Serwerowa (actions.js):

'use server'

export async function submitForm(formData) {
  // Symulacja opóźnienia w celu demonstracji stanu ładowania
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Formularz wysłany z imieniem:', name);
  return { message: `Formularz wysłany pomyślnie z imieniem: ${name}` };
}

Komponent React (FormComponent.jsx):

'use client'

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

function FormComponent() {
  const { pending } = useFormStatus()

  return (
    

      Imię:
      
      
        {pending ? 'Wysyłanie...' : 'Wyślij'}
      
    
  )
}

export default FormComponent

W tym przykładzie właściwość pending z useFormStatus jest używana do wyłączenia pola wejściowego i przycisku podczas wysyłania formularza oraz do wyświetlania komunikatu "Wysyłanie...".

Obsługa stanów sukcesu i błędu

Ten przykład demonstruje, jak obsługiwać stany sukcesu i błędu po wysłaniu formularza.

Akcja Serwerowa (actions.js):

'use server'

export async function submitForm(formData) {
  // Symulacja opóźnienia
  await new Promise(resolve => setTimeout(resolve, 2000));

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

  if (!name) {
    throw new Error('Imię jest wymagane');
  }

  console.log('Formularz wysłany z imieniem:', name);
  return { message: `Formularz wysłany pomyślnie z imieniem: ${name}` };
}

Komponent React (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await submitForm(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Imię:
      
      
        {pending ? 'Wysyłanie...' : 'Wyślij'}
      
      {pending && 
Wysyłanie...
}
      {message && 
{message}
}
      {error && 
Błąd: {error}
}
    
  )
}

export default FormComponent

W tym przykładzie w funkcji handleSubmit użyto bloku try/catch. Jeśli Akcja Serwerowa zgłosi błąd, jest on przechwytywany i wyświetlany użytkownikowi. Komunikat o sukcesie jest wyświetlany po pomyślnym wysłaniu.

Używanie FormData dla złożonych danych

useFormStatus działa płynnie z FormData, umożliwiając łatwą obsługę złożonych struktur danych. Oto przykład pokazujący, jak przesyłać pliki.

Akcja Serwerowa (actions.js):

'use server'

export async function uploadFile(formData) {
  // Symulacja przetwarzania pliku
  await new Promise(resolve => setTimeout(resolve, 2000));

  const file = formData.get('file');

  if (!file) {
    throw new Error('Nie przesłano pliku');
  }

  console.log('Plik przesłany:', file.name);
  return { message: `Plik przesłany pomyślnie: ${file.name}` };
}

Komponent React (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { uploadFile } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await uploadFile(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Prześlij plik:
      
      
        {pending ? 'Przesyłanie...' : 'Prześlij'}
      
      {pending && 
Przesyłanie...
}
      {message && 
{message}
}
      {error && 
Błąd: {error}
}
    
  )
}

export default FormComponent

Ten przykład demonstruje, jak obsługiwać przesyłanie plików za pomocą FormData. Akcja serwerowa pobiera plik z obiektu FormData i go przetwarza. Hook useFormStatus zarządza stanem ładowania podczas przesyłania pliku.

Dobre praktyki dotyczące używania useFormStatus

Aby zmaksymalizować korzyści płynące z useFormStatus, warto rozważyć następujące dobre praktyki:

• Zapewnij jasną informację zwrotną dla użytkownika: Użyj stanu pending, aby wyświetlać informacyjne wskaźniki ładowania i wyłączać elementy formularza, aby zapobiec wielokrotnym wysłaniom.
• Obsługuj błędy w sposób elegancki: Zaimplementuj obsługę błędów, aby przechwytywać wyjątki w Akcjach Serwerowych i wyświetlać przyjazne dla użytkownika komunikaty o błędach.
• Waliduj dane na serwerze: Przeprowadzaj walidację po stronie serwera, aby zapewnić integralność i bezpieczeństwo danych.
• Utrzymuj zwięzłość Akcji Serwerowych: Skup Akcje Serwerowe na konkretnych zadaniach, aby poprawić wydajność i łatwość utrzymania.
• Weź pod uwagę dostępność: Upewnij się, że formularze są dostępne, zapewniając odpowiednie etykiety, atrybuty ARIA i obsługę nawigacji za pomocą klawiatury.

Zaawansowane przypadki użycia

Oprócz podstawowych przykładów, useFormStatus można używać w bardziej złożonych scenariuszach:

• Progressive Enhancement (Stopniowe ulepszanie): Użyj Akcji Serwerowych i useFormStatus, aby stopniowo ulepszać swoje formularze, zapewniając podstawowe doświadczenie użytkownikom z wyłączonym JavaScriptem i bogatsze dla tych z włączonym.
• Optymistyczne aktualizacje: Zaimplementuj optymistyczne aktualizacje, aktualizując interfejs użytkownika natychmiast po wysłaniu formularza, zakładając, że wysłanie się powiedzie. Wycofaj aktualizację, jeśli wysłanie się nie powiedzie.
• Integracja z bibliotekami formularzy: Zintegruj useFormStatus z popularnymi bibliotekami formularzy, takimi jak Formik czy React Hook Form, aby zarządzać stanem formularza i walidacją. Chociaż te biblioteki często mają własne zarządzanie stanem, useFormStatus może być przydatny w końcowej fazie wysyłania do akcji serwerowej.

Uwagi dotyczące internacjonalizacji (i18n)

Podczas tworzenia formularzy dla globalnej publiczności, internacjonalizacja (i18n) jest kluczowa. Oto jak uwzględnić i18n podczas korzystania z useFormStatus:

• Zlokalizowane komunikaty o błędach: Upewnij się, że komunikaty o błędach wyświetlane użytkownikowi są zlokalizowane w jego preferowanym języku. Można to osiągnąć, przechowując komunikaty o błędach w plikach tłumaczeń i używając biblioteki takiej jak react-intl lub i18next do pobierania odpowiedniego tłumaczenia.
• Formatowanie dat i liczb: Obsługuj formatowanie dat i liczb zgodnie z lokalizacją użytkownika. Użyj bibliotek takich jak Intl.DateTimeFormat i Intl.NumberFormat, aby poprawnie formatować te wartości.
• Wsparcie dla języków pisanych od prawej do lewej (RTL): Jeśli Twoja aplikacja obsługuje języki pisane od prawej do lewej (np. arabski, hebrajski), upewnij się, że formularze są odpowiednio stylizowane, aby dostosować się do układów RTL.
• Walidacja formularzy: Dostosuj reguły walidacji formularzy do różnych lokalizacji. Na przykład walidacja numeru telefonu może się znacznie różnić w zależności od kraju.

Przykład zlokalizowanych komunikatów o błędach:

// translations/pl.json
{
  "form.error.nameRequired": "Proszę podać swoje imię.",
  "form.success.submission": "Dziękujemy za przesłanie formularza!"
}

// translations/fr.json
{
  "form.error.nameRequired": "Proszę podać swoje imię.",
  "form.success.submission": "Dziękujemy za przesłanie formularza!"
}

// Komponent używający react-intl
import { useIntl } from 'react-intl';

function FormComponent() {
  const intl = useIntl();
  const [error, setError] = useState(null);

  // ...

  catch (e) {
    setError(intl.formatMessage({ id: 'form.error.nameRequired' }));
  }
}

Względy dostępności (Accessibility)

Dostępność jest kluczowym aspektem tworzenia inkluzywnych aplikacji internetowych. Oto kilka kwestii związanych z dostępnością, o których należy pamiętać podczas korzystania z useFormStatus:

• Atrybuty ARIA: Użyj atrybutów ARIA, aby dostarczyć technologiom wspomagającym informacje o statusie formularza. Na przykład użyj aria-busy="true" na przycisku wysyłania, gdy formularz jest w trakcie przetwarzania.
• Etykiety: Upewnij się, że wszystkie pola formularza mają jasne i opisowe etykiety, które są powiązane z elementami wejściowymi za pomocą elementu <label>.
• Komunikaty o błędach: Wyświetlaj komunikaty o błędach w sposób łatwo zauważalny i zrozumiały dla użytkowników z niepełnosprawnościami. Użyj atrybutów ARIA, takich jak aria-live="assertive", aby ogłaszać komunikaty o błędach czytnikom ekranu.
• Nawigacja za pomocą klawiatury: Upewnij się, że użytkownicy mogą nawigować po formularzu za pomocą samej klawiatury. Użyj atrybutu tabindex, aby kontrolować kolejność, w jakiej elementy otrzymują fokus.
• Kontrast kolorów: Upewnij się, że kolory tekstu i tła używane w formularzu mają wystarczający kontrast, aby były łatwo czytelne dla użytkowników z wadami wzroku.

useFormStatus kontra tradycyjne zarządzanie stanem

Tradycyjnie deweloperzy React zarządzali stanem wysyłania formularzy za pomocą stanu komponentu (useState) lub bardziej złożonych bibliotek do zarządzania stanem (np. Redux, Zustand). Oto porównanie tych podejść z useFormStatus:

Cecha	useFormStatus	useState	Zewnętrzne zarządzanie stanem
Złożoność	Niska	Średnia	Wysoka
Integracja z Akcjami Serwerowymi	Płynna	Wymaga ręcznej integracji	Wymaga ręcznej integracji
Kod boilerplate	Minimalny	Umiarkowany	Znaczący
Odpowiednie przypadki użycia	Formularze wysyłane bezpośrednio do Akcji Serwerowych	Proste formularze z ograniczonym stanem	Złożone formularze ze stanem współdzielonym między komponentami

useFormStatus sprawdza się doskonale, gdy formularze wchodzą w interakcję bezpośrednio z Akcjami Serwerowymi React. Redukuje ilość kodu boilerplate i upraszcza proces. Jednak w przypadku bardzo złożonych formularzy ze stanem współdzielonym między wieloma komponentami, pełnoprawna biblioteka do zarządzania stanem może być nadal uzasadniona.

Rozwiązywanie typowych problemów

Oto niektóre typowe problemy, które możesz napotkać podczas korzystania z useFormStatus, oraz sposoby ich rozwiązywania:

• useFormStatus nie aktualizuje się:
  • Upewnij się, że używasz useFormStatus wewnątrz elementu <form>, którego atrybut action jest ustawiony na Akcję Serwerową.
  • Sprawdź, czy Akcja Serwerowa jest poprawnie zdefiniowana i wyeksportowana.
  • Sprawdź, czy w Akcji Serwerowej nie ma błędów, które mogłyby uniemożliwić jej pomyślne ukończenie.
• Komunikaty o błędach nie wyświetlają się:
  • Upewnij się, że poprawnie przechwytujesz błędy w swojej Akcji Serwerowej i zwracasz komunikat o błędzie.
  • Sprawdź, czy wyświetlasz komunikat o błędzie w swoim komponencie, używając stanu error.
• Wskaźnik ładowania nie pojawia się:
  • Upewnij się, że używasz stanu pending z useFormStatus, aby warunkowo wyświetlać wskaźnik ładowania.
  • Sprawdź, czy Akcja Serwerowa faktycznie zajmuje trochę czasu (np. symulując opóźnienie).

Podsumowanie

useFormStatus dostarcza czysty i wydajny sposób zarządzania stanem wysyłania formularzy w aplikacjach React wykorzystujących Komponenty Serwerowe. Dzięki wykorzystaniu tego hooka możesz uprościć swój kod, poprawić doświadczenie użytkownika i płynnie integrować się z Akcjami Serwerowymi. Ten przewodnik omówił podstawy useFormStatus, przedstawił praktyczne przykłady i omówił dobre praktyki efektywnego jego wykorzystania. Włączając useFormStatus do swoich projektów React, możesz usprawnić obsługę formularzy i budować bardziej solidne i przyjazne dla użytkownika aplikacje dla globalnej publiczności.