React useFormStatus: Išsamus formos būsenos valdymo vadovas

useFormStatus kabliukas, pristatytas React 18 versijoje, suteikia galingą ir efektyvų būdą valdyti formų pateikimo būseną React serverio komponentuose (React Server Components). Šis kabliukas yra specialiai sukurtas veikti su serverio veiksmais (server actions), siūlydamas sklandžią integraciją formų pateikimui tvarkyti tiesiogiai serveryje. Jis supaprastina formos pateikimo būsenos stebėjimo procesą, teikdamas vertingą informaciją, pavyzdžiui, ar forma yra laukimo būsenoje (pending), ar sėkmingai pateikta, ar įvyko klaida. Šiame vadove nagrinėjamos useFormStatus galimybės, jo privalumai ir praktiniai pavyzdžiai, demonstruojantys jo naudojimą įvairiuose scenarijuose.

Serverio veiksmų ir useFormStatus supratimas

Prieš gilinantis į useFormStatus, labai svarbu suprasti React serverio komponentus ir serverio veiksmus. Serverio veiksmai leidžia apibrėžti funkcijas, kurios veikia serveryje ir yra tiesiogiai pasiekiamos iš jūsų React komponentų. Tai leidžia tvarkyti formų pateikimą, duomenų gavimą ir kitas serverio operacijas be atskiro API galinio taško (endpoint).

Tada useFormStatus kabliukas suteikia įžvalgų apie šių serverio veiksmų, kuriuos sukelia formų pateikimas, vykdymą.

Kas yra useFormStatus?

useFormStatus yra React kabliukas, kuris grąžina objektą su informacija apie naujausio formos pateikimo būseną. Ši informacija apima:

• pending: loginė reikšmė (boolean), nurodanti, ar forma šiuo metu yra pateikiama.
• data: FormData objektas, susijęs su pateikimu.
• method: HTTP metodas, naudojamas pateikimui (paprastai 'POST').
• action: serverio veiksmo funkcija, kuri buvo paleista.

useFormStatus naudojimo privalumai

useFormStatus panaudojimas suteikia keletą esminių privalumų:

• Supaprastintas būsenos valdymas: Pašalina poreikį rankiniu būdu valdyti būseną, kad būtų galima sekti formos pateikimo statusą. Kabliukas automatiškai atsinaujina pateikimo eigoje.
• Geresnė vartotojo patirtis: Suteikia vartotojams grįžtamąjį ryšį realiu laiku, pavyzdžiui, rodo įkėlimo indikatorius, kol forma apdorojama, arba klaidų pranešimus gedimo atveju.
• Švarus kodas: Skatina deklaratyvesnį ir lengviau prižiūrimą kodą, atskiriant formos pateikimo logiką nuo komponento atvaizdavimo.
• Sklandi integracija su serverio veiksmais: Sukurtas puikiai veikti su serverio veiksmais, todėl lengva tvarkyti formų pateikimą tiesiogiai serveryje.

Praktiniai useFormStatus pavyzdžiai

Panagrinėkime keletą praktinių pavyzdžių, iliustruojančių useFormStatus naudojimą skirtinguose scenarijuose.

Paprastas formos pateikimas su įkėlimo indikatoriumi

Šis pavyzdys demonstruoja paprastą formą su įkėlimo indikatoriumi, kuris rodomas, kol forma pateikiama.

Serverio veiksmas (actions.js):

'use server'

export async function submitForm(formData) {
  // Imituojamas delsimas, siekiant pademonstruoti įkėlimo būseną
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Forma pateikta su vardu:', name);
  return { message: `Forma sėkmingai pateikta su vardu: ${name}` };
}

React komponentas (FormComponent.jsx):

'use client'

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

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

  return (
    

      Vardas:
      
      
        {pending ? 'Pateikiama...' : 'Pateikti'}
      
    
  )
}

export default FormComponent

Šiame pavyzdyje pending savybė iš useFormStatus naudojama išjungti įvesties lauką ir mygtuką, kol forma pateikiama, ir rodyti pranešimą „Pateikiama...“.

Sėkmės ir klaidų būsenų tvarkymas

Šis pavyzdys demonstruoja, kaip tvarkyti sėkmės ir klaidų būsenas po formos pateikimo.

Serverio veiksmas (actions.js):

'use server'

export async function submitForm(formData) {
  // Imituojamas delsimas
  await new Promise(resolve => setTimeout(resolve, 2000));

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

  if (!name) {
    throw new Error('Vardas yra privalomas');
  }

  console.log('Forma pateikta su vardu:', name);
  return { message: `Forma sėkmingai pateikta su vardu: ${name}` };
}

React komponentas (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 (
    

      Vardas:
      
      
        {pending ? 'Pateikiama...' : 'Pateikti'}
      
      {pending && 
Pateikiama...
}
      {message && 
{message}
}
      {error && 
Klaida: {error}
}
    
  )
}

export default FormComponent

Šiame pavyzdyje handleSubmit funkcijoje naudojamas try/catch blokas. Jei serverio veiksmas sukelia klaidą, ji pagaunama ir rodoma vartotojui. Sėkmingai pateikus, rodomas sėkmės pranešimas.

FormData naudojimas sudėtingiems duomenims

useFormStatus sklandžiai veikia su FormData, leisdamas lengvai tvarkyti sudėtingas duomenų struktūras. Štai pavyzdys, rodantis, kaip įkelti failus.

Serverio veiksmas (actions.js):

'use server'

export async function uploadFile(formData) {
  // Imituojamas failo apdorojimas
  await new Promise(resolve => setTimeout(resolve, 2000));

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

  if (!file) {
    throw new Error('Failas neįkeltas');
  }

  console.log('Failas įkeltas:', file.name);
  return { message: `Failas sėkmingai įkeltas: ${file.name}` };
}

React komponentas (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 (
    

      Įkelti failą:
      
      
        {pending ? 'Įkeliama...' : 'Įkelti'}
      
      {pending && 
Įkeliama...
}
      {message && 
{message}
}
      {error && 
Klaida: {error}
}
    
  )
}

export default FormComponent

Šis pavyzdys demonstruoja, kaip tvarkyti failų įkėlimą naudojant FormData. Serverio veiksmas gauna failą iš FormData objekto ir jį apdoroja. useFormStatus kabliukas valdo įkėlimo būseną, kol failas yra įkeliamas.

Geriausios useFormStatus naudojimo praktikos

Norėdami maksimaliai išnaudoti useFormStatus privalumus, apsvarstykite šias geriausias praktikas:

• Teikite aiškų grįžtamąjį ryšį vartotojui: Naudokite pending būseną, kad parodytumėte informatyvius įkėlimo indikatorius ir išjungtumėte formos elementus, kad išvengtumėte kelių pateikimų.
• Klaidų tvarkymas: Įdiekite klaidų tvarkymą, kad pagautumėte išimtis savo serverio veiksmuose ir rodytumėte vartotojui draugiškus klaidų pranešimus.
• Duomenų tikrinimas serveryje: Atlikite duomenų tikrinimą serveryje, kad užtikrintumėte duomenų vientisumą ir saugumą.
• Išlaikykite serverio veiksmus glaustus: Sutelkite serverio veiksmus į konkrečias užduotis, kad pagerintumėte našumą ir priežiūrą.
• Atsižvelkite į prieinamumą: Užtikrinkite, kad jūsų formos būtų prieinamos, pateikdami tinkamas etiketes, ARIA atributus ir palaikydami navigaciją klaviatūra.

Pažangesni naudojimo atvejai

Be pagrindinių pavyzdžių, useFormStatus gali būti naudojamas sudėtingesniuose scenarijuose:

• Progresyvus tobulinimas: Naudokite serverio veiksmus ir useFormStatus, kad palaipsniui tobulintumėte savo formas, suteikdami pagrindinę patirtį vartotojams su išjungtu JavaScript ir turtingesnę patirtį tiems, kuriems JavaScript įjungtas.
• Optimistiniai atnaujinimai: Įdiekite optimistinius atnaujinimus, nedelsdami atnaujindami vartotojo sąsają po formos pateikimo, darant prielaidą, kad pateikimas bus sėkmingas. Atšaukite atnaujinimą, jei pateikimas nepavyksta.
• Integracija su formų bibliotekomis: Integruokite useFormStatus su populiariomis formų bibliotekomis, tokiomis kaip Formik ar React Hook Form, kad valdytumėte formos būseną ir tikrinimą. Nors šios bibliotekos dažnai turi savo būsenos valdymą, useFormStatus gali būti naudingas galutiniam pateikimo etapui į serverio veiksmą.

Svarstymai dėl internacionalizacijos (i18n)

Kuriant formas pasaulinei auditorijai, internacionalizacija (i18n) yra labai svarbi. Štai kaip atsižvelgti į i18n naudojant useFormStatus:

• Lokalizuoti klaidų pranešimai: Užtikrinkite, kad vartotojui rodomi klaidų pranešimai būtų lokalizuoti į jo pageidaujamą kalbą. Tai galima pasiekti saugant klaidų pranešimus vertimų failuose ir naudojant biblioteką, pvz., react-intl ar i18next, norint gauti atitinkamą vertimą.
• Datos ir skaičių formatavimas: Tvarkykite datos ir skaičių formatavimą pagal vartotojo lokalę. Naudokite bibliotekas, tokias kaip Intl.DateTimeFormat ir Intl.NumberFormat, kad teisingai suformatuotumėte šias reikšmes.
• Iš dešinės į kairę (RTL) palaikymas: Jei jūsų programa palaiko kalbas, kurios rašomos iš dešinės į kairę (pvz., arabų, hebrajų), užtikrinkite, kad jūsų formos būtų tinkamai stilizuotos, kad atitiktų RTL išdėstymą.
• Formos tikrinimas: Pritaikykite formos tikrinimo taisykles skirtingoms lokalėms. Pavyzdžiui, telefono numerio tikrinimas gali labai skirtis įvairiose šalyse.

Lokalizuotų klaidų pranešimų pavyzdys:

// translations/en.json
{
  "form.error.nameRequired": "Please enter your name.",
  "form.success.submission": "Thank you for your submission!"
}

// translations/lt.json
{
  "form.error.nameRequired": "Prašome įvesti savo vardą.",
  "form.success.submission": "Dėkojame už jūsų pateikimą!"
}

// Komponentas, naudojantis 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' }));
  }
}

Prieinamumo aspektai

Prieinamumas yra pagrindinis aspektas kuriant įtraukias žiniatinklio programas. Štai keletas prieinamumo aspektų, kuriuos reikia turėti omenyje naudojant useFormStatus:

• ARIA atributai: Naudokite ARIA atributus, kad pagalbinių technologijų priemonėms suteiktumėte informaciją apie formos būseną. Pavyzdžiui, naudokite aria-busy="true" ant pateikimo mygtuko, kol forma yra laukimo būsenoje.
• Etiketės: Užtikrinkite, kad visi formos laukai turėtų aiškias ir aprašančias etiketes, susietas su įvesties elementais naudojant <label> elementą.
• Klaidų pranešimai: Rodykite klaidų pranešimus taip, kad jie būtų lengvai pastebimi ir suprantami vartotojams su negalia. Naudokite ARIA atributus, pvz., aria-live="assertive", kad ekrano skaitytuvai praneštų apie klaidų pranešimus.
• Navigacija klaviatūra: Užtikrinkite, kad vartotojai galėtų naršyti formą naudodami tik klaviatūrą. Naudokite tabindex atributą, kad kontroliuotumėte elementų fokusavimo tvarką.
• Spalvų kontrastas: Užtikrinkite, kad formoje naudojamų teksto ir fono spalvų kontrastas būtų pakankamas, kad vartotojai su regėjimo sutrikimais galėtų lengvai skaityti.

useFormStatus palyginimas su tradiciniu būsenos valdymu

Tradiciškai React kūrėjai valdė formos pateikimo būseną naudodami komponento būseną (useState) arba sudėtingesnes būsenos valdymo bibliotekas (pvz., Redux, Zustand). Štai šių metodų palyginimas su useFormStatus:

Savybė	useFormStatus	useState	Išorinis būsenos valdymas
Sudėtingumas	Žemas	Vidutinis	Aukštas
Integracija su serverio veiksmais	Sklandi	Reikalinga rankinė integracija	Reikalinga rankinė integracija
Pasikartojantis kodas (Boilerplate)	Minimalus	Vidutinis	Ženklus
Tinkami naudojimo atvejai	Formos, pateikiamos tiesiogiai serverio veiksmams	Paprastos formos su ribota būsena	Sudėtingos formos su bendra būsena tarp komponentų

useFormStatus puikiai tinka, kai jūsų formos sąveikauja tiesiogiai su React serverio veiksmais. Jis sumažina pasikartojančio kodo kiekį ir supaprastina procesą. Tačiau labai sudėtingoms formoms su būsena, bendrinama tarp kelių komponentų, vis dar gali būti reikalinga visavertė būsenos valdymo biblioteka.

Dažniausiai pasitaikančių problemų sprendimas

Štai keletas dažniausiai pasitaikančių problemų, su kuriomis galite susidurti naudodami useFormStatus, ir kaip jas spręsti:

• useFormStatus neatsinaujina:
  • Įsitikinkite, kad naudojate useFormStatus <form> elemente, kurio action savybė yra nustatyta į serverio veiksmą.
  • Patikrinkite, ar serverio veiksmas yra teisingai apibrėžtas ir eksportuotas.
  • Patikrinkite, ar serverio veiksme nėra klaidų, kurios galėtų trukdyti sėkmingai jį užbaigti.
• Klaidų pranešimai nerodomi:
  • Įsitikinkite, kad teisingai pagaunate klaidas savo serverio veiksme ir grąžinate klaidos pranešimą.
  • Patikrinkite, ar rodote klaidos pranešimą savo komponente naudodami error būseną.
• Įkėlimo indikatorius neatsiranda:
  • Įsitikinkite, kad naudojate pending būseną iš useFormStatus, kad sąlygiškai rodytumėte įkėlimo indikatorių.
  • Patikrinkite, ar serverio veiksmas iš tikrųjų užtrunka (pvz., imituodami delsą).

Išvada

useFormStatus suteikia švarų ir efektyvų būdą valdyti formos pateikimo būseną React programose, naudojančiose serverio komponentus. Naudodami šį kabliuką, galite supaprastinti savo kodą, pagerinti vartotojo patirtį ir sklandžiai integruotis su serverio veiksmais. Šiame vadove buvo apžvelgti useFormStatus pagrindai, pateikti praktiniai pavyzdžiai ir aptartos geriausios jo efektyvaus naudojimo praktikos. Įtraukdami useFormStatus į savo React projektus, galite supaprastinti formų tvarkymą ir kurti tvirtesnes bei vartotojui draugiškesnes programas pasaulinei auditorijai.