Reacti useActionState'i vigadest taastumine: põhjalik tegevuse veakäsitluse strateegia

Veebiarenduse maailmas on vormi kasutajakogemus kriitilise tähtsusega kokkupuutepunkt. Sujuv ja intuitiivne vorm võib viia eduka konversioonini, samas kui frustreeriv vorm võib panna kasutajad ülesandest täielikult loobuma. Serveri tegevuste (Server Actions) ja uue useActionState haagi (hook) tulekuga React 19-s on arendajatel võimsad tööriistad vormide esitamise ja olekute üleminekute haldamiseks. Siiski ei piisa enam pelgalt veateate kuvamisest, kui tegevus ebaõnnestub.

Tõeliselt vastupidav rakendus ennetab tõrkeid ja pakub kasutajale selget taastumisteed. Mis juhtub, kui võrguühendus katkeb? Või kui kasutaja sisend ebaõnnestub serveripoolses valideerimises? Kas kasutaja kaotab kõik andmed, mille sisestamiseks ta just minuteid kulutas? Siin muutub oluliseks läbimõeldud veakäsitluse ja taastumise strateegia.

See põhjalik juhend viib teid kaugemale useActionState'i põhitõdedest. Uurime täielikku strateegiat tegevuste vigade käsitlemiseks, kasutaja sisendi säilitamiseks ja vastupidavate, kasutajasõbralike vormide loomiseks, mis toimivad usaldusväärselt ka globaalsele publikule. Liigume teooriast praktilise rakendamiseni, ehitades süsteemi, mis on nii võimas kui ka hooldatav.

Mis on `useActionState`? Kiire meeldetuletus

Enne meie taastumisstrateegiasse sukeldumist vaatame lühidalt üle useActionState haagi (mida tunti Reacti varasemates eksperimentaalsetes versioonides kui useFormState). Selle peamine eesmärk on hallata vormi tegevuse olekut, sealhulgas ootel olekuid ja serverist tagastatud andmeid.

See lihtsustab mustrit, mis varem nõudis useState'i, useEffect'i ja käsitsi olekuhalduse kombinatsiooni vormide esitamise käsitlemiseks.

Põhisüntaks on järgmine:

            const [state, formAction, isPending] = useActionState(action, initialState);

            

              
                Copy
              
            
          

• action: Serveri tegevuse funktsioon, mis käivitatakse. See funktsioon saab argumentideks eelmise oleku ja vormi andmed.
• initialState: Väärtus, mida soovite olekul algselt omada, enne kui tegevust kunagi kutsutakse.
• state: Tegevuse lõppedes tagastatud olek. Esmasel renderdamisel on see initialState.
• formAction: Uus tegevus, mille edastate oma <form> elemendi action-atribuudile. Selle tegevuse käivitamisel käivitab see algse action'i, uuendab isPending lippu ja uuendab state'i tulemusega.
• isPending: Tõeväärtus, mis on true, kui tegevus on pooleli, ja muul juhul false. See on uskumatult kasulik esitamisnuppude keelamiseks või laadimisindikaatorite kuvamiseks.

Kuigi see haak on fantastiline primitiiv, avaneb selle tõeline jõud siis, kui kujundate selle ümber vastupidava süsteemi.

Väljakutse: enamat kui lihtne veateate kuvamine

Kõige tavalisem veakäsitluse rakendus useActionState'iga hõlmab seda, et serveri tegevus tagastab lihtsa veaobjekti, mis seejärel kuvatakse kasutajaliideses. Näiteks:

            // Lihtne, kuid piiratud serveri tegevus
export async function updateUser(prevState, formData) {
  const name = formData.get('name');
  if (name.length < 3) {
    return { success: false, message: 'Nimi peab olema vähemalt 3 tähemärki pikk.' };
  }
  // ... uuenda kasutajat andmebaasis
  return { success: true, message: 'Profiil uuendatud!' };
}

            

              
                Copy
              
            
          

See töötab, kuid sellel on olulisi piiranguid, mis viivad halva kasutajakogemuseni:

• Kaotatud kasutaja sisend: Kui vorm esitatakse ja tekib viga, renderdab brauser lehe uuesti serveri poolt renderdatud tulemusega. Kui sisendväljad on kontrollimata, võib kasutaja sisestatud teave kaotsi minna, sundides teda uuesti alustama. See on peamine kasutajate frustratsiooni allikas.
• Puudub selge taastumistee: Kasutaja näeb veateadet, aga mis edasi? Kui välju on mitu, ei tea ta, milline neist on vale. Kui tegemist on serveri veaga, ei tea ta, kas peaks proovima kohe uuesti või hiljem.
• Võimatus vigu eristada: Kas viga oli tingitud valest sisendist (400-taseme viga), serveripoolsest krahhist (500-taseme viga) või autentimise ebaõnnestumisest? Lihtne sõnumi string ei suuda seda konteksti edasi anda, mis on intelligentse kasutajaliidese reaktsioonide loomiseks ülioluline.

Professionaalsete, ettevõtte tasemel rakenduste ehitamiseks vajame struktureeritumat ja vastupidavamat lähenemist.

Vastupidav vigadest taastumise strateegia `useActionState`'iga

Meie strateegia põhineb kolmel alustalal: standardiseeritud tegevuse vastus, intelligentne olekuhaldus kliendi poolel ja kasutajakeskne kasutajaliides, mis juhendab taastumist.

1. samm: standardiseeritud tegevuse vastuse kuju määratlemine

Järjepidevus on võtmetähtsusega. Esimene samm on luua leping – järjepidev andmestruktuur, mille iga serveri tegevus tagastab. See prognoositavus võimaldab meie esirakenduse komponentidel käsitleda mis tahes tegevuse tulemust ilma igaühe jaoks kohandatud loogikata.

Siin on vastupidav vastuse kuju, mis suudab käsitleda erinevaid stsenaariume:

            // Meie standardiseeritud vastuse tüübi definitsioon
interface ActionResponse {
  success: boolean;
  message?: string; // Globaalseks, kasutajale suunatud tagasisideks (nt toast-teated)
  errors?: Record | null; // Väljaspetsiifilised valideerimisvead
  errorType?: 'VALIDATION' | 'SERVER_ERROR' | 'AUTH_ERROR' | 'NOT_FOUND' | null;
  data?: T | null; // Payload edu korral
}

            

              
                Copy
              
            
          

• success: Selge tõeväärtus, mis näitab tulemust.
• message: Globaalne, inimloetav sõnum. See sobib ideaalselt toast-teadete või bännerite jaoks nagu "Profiil edukalt uuendatud" või "Serveriga ei saanud ühendust."
• errors: Objekt, kus võtmed vastavad vormiväljade nimedele (nt 'email') ja väärtused on veasõnumite massiivid. See võimaldab kuvada mitu viga välja kohta.
• errorType: Enum-laadne string, mis kategoriseerib vea. See on salajane koostisosa, mis võimaldab meie kasutajaliidesel reageerida erinevalt erinevatele tõrke režiimidele.
• data: Edukalt loodud või uuendatud ressurss, mida saab kasutada kasutajaliidese uuendamiseks või kasutaja ümbersuunamiseks.

Eduka vastuse näide:

            { 
  success: true, 
  message: 'Kasutajaprofiil edukalt uuendatud!',
  data: { id: '123', name: 'John Doe', email: 'john.doe@example.com' }
}

            

              
                Copy
              
            
          

Valideerimisvea vastuse näide:

            { 
  success: false, 
  message: 'Palun parandage allolevad vead.',
  errors: {
    email: ['Palun sisestage kehtiv e-posti aadress.'],
    password: ['Parool peab olema vähemalt 8 tähemärki pikk.', 'Parool peab sisaldama numbrit.']
  },
  errorType: 'VALIDATION'
}

            

              
                Copy
              
            
          

Serveri vea vastuse näide:

            { 
  success: false, 
  message: 'Ilmnes ootamatu viga. Meie meeskonda on teavitatud. Palun proovige hiljem uuesti.',
  errors: null,
  errorType: 'SERVER_ERROR'
}

            

              
                Copy
              
            
          

2. samm: komponendi algse oleku kujundamine

Kui meie vastuse kuju on määratletud, peaks useActionState'ile edastatud algne olek seda peegeldama. See tagab tüübi järjepidevuse ja hoiab ära käitusvigu, mis tekivad omadustele juurdepääsemisel, mida esmasel renderdamisel ei eksisteeri.

            const initialState = {
  success: false,
  message: '',
  errors: null,
  errorType: null,
  data: null
};

            

              
                Copy
              
            
          

3. samm: serveri tegevuse rakendamine

Nüüd rakendame serveri tegevuse, mis järgib meie lepingut. Kasutame populaarset valideerimisteeki zod, et demonstreerida valideerimisvigade puhast käsitlemist.

            'use server';

import { z } from 'zod';

// Määratle valideerimisskeem
const profileSchema = z.object({
  name: z.string().min(3, { message: 'Nimi peab olema vähemalt 3 tähemärki pikk.' }),
  email: z.string().email({ message: 'Palun sisestage kehtiv e-posti aadress.' }),
});

// Serveri tegevus järgib meie standardiseeritud vastust
export async function updateUserProfileAction(previousState, formData) {
  const validatedFields = profileSchema.safeParse({
    name: formData.get('name'),
    email: formData.get('email'),
  });

  // Käsitle valideerimisvigu
  if (!validatedFields.success) {
    return {
      success: false,
      message: 'Valideerimine ebaõnnestus. Palun kontrollige välju.',
      errors: validatedFields.error.flatten().fieldErrors,
      errorType: 'VALIDATION',
      data: null
    };
  }

  try {
    // Simuleeri andmebaasi operatsiooni
    console.log('Uuendan kasutajat:', validatedFields.data);
    // const updatedUser = await db.user.update(...);
    
    // Simuleeri potentsiaalset serveri viga
    if (validatedFields.data.email.includes('fail')) {
      throw new Error('Andmebaasi ühendus ebaõnnestus');
    }

    return {
      success: true,
      message: 'Profiil edukalt uuendatud!',
      errors: null,
      errorType: null,
      data: validatedFields.data
    };
  } catch (error) {
    console.error('Serveri viga:', error);
    return {
      success: false,
      message: 'Ilmnes sisemine serveri viga. Palun proovige hiljem uuesti.',
      errors: null,
      errorType: 'SERVER_ERROR',
      data: null
    };
  }
}

            

              
                Copy
              
            
          

See tegevus on nüüd prognoositav ja vastupidav funktsioon. See eraldab selgelt valideerimisloogika äriloogikast ja käsitleb ootamatuid vigu sujuvalt, tagastades alati vastuse, mida meie esirakendus suudab mõista.

Kasutajaliidese ehitamine: kasutajakeskne lähenemine

Nüüd kõige olulisema osa juurde: selle struktureeritud oleku kasutamine parema kasutajakogemuse loomiseks. Meie eesmärk on kasutajat juhendada, mitte teda lihtsalt blokeerida.

Komponendi põhihäälestus

Seadistame oma vormikomponendi. Kasutaja sisendi säilitamise võti ebaõnnestumise korral on kontrollitud komponentide kasutamine. Me haldame sisendite olekut useState'iga. Kui vormi esitamine ebaõnnestub, renderdatakse komponent uuesti, kuid kuna sisendväärtusi hoitakse Reacti olekus, ei lähe need kaotsi.

            'use client';

import { useState } from 'react';
import { useActionState } from 'react';
import { updateUserProfileAction } from './actions';

const initialState = { success: false, message: '', errors: null, errorType: null };

export function UserProfileForm({ user }) {
  const [state, formAction, isPending] = useActionState(updateUserProfileAction, initialState);

  // Kasuta useState'i vormi sisendite kontrollimiseks ja nende säilitamiseks uuesti renderdamisel
  const [name, setName] = useState(user.name);
  const [email, setEmail] = useState(user.email);

  return (
    

      
Muuda profiili

      {/* Globaalne vea/edu sõnumi bänner */}
      {state.message && (
        

          {state.message}
        
      )}

      

        Nimi
         setName(e.target.value)}
          aria-invalid={!!state.errors?.name}
          aria-describedby="name-error"
        />
        {state.errors?.name && (
          
{state.errors.name[0]}
        )}
      

      

        E-post
         setEmail(e.target.value)}
          aria-invalid={!!state.errors?.email}
          aria-describedby="email-error"
        />
        {state.errors?.email && (
          
{state.errors.email[0]}
        )}
      

      
        {isPending ? 'Salvestan...' : 'Salvesta muudatused'}
      
    
  );
}

            

              
                Copy
              
            
          

Kasutajaliidese rakendamise olulised detailid:

• Kontrollitud sisendid: Kasutades useState'i name'i ja email'i jaoks, haldab sisendväärtusi React. Kui serveri tegevus ebaõnnestub ja komponent renderdatakse uuesti uue veaolekuga, jäävad name'i ja email'i olekumuutujad muutumatuks, säilitades seega täiuslikult kasutaja sisendi. See on kõige olulisem tehnika hea taastumiskogemuse jaoks.
• Globaalne sõnumi bänner: Kasutame state.message'i ülataseme sõnumi kuvamiseks. Saame isegi selle värvi muuta vastavalt state.success'ile.
• Väljaspetsiifilised vead: Kontrollime state.errors?.fieldName'i olemasolu ja kui see on olemas, renderdame veateate otse vastava sisendi alla.
• Juurdepääsetavus: Kasutame aria-invalid'i, et programmiliselt teavitada ekraanilugejaid, et väljal on viga. aria-describedby seob sisendi selle veateatega, tagades, et veatekst loetakse ette, kui kasutaja keskendub valele väljale.
• Ootel olek: isPending tõeväärtust kasutatakse esitamisnupu keelamiseks, vältides topeltesitamisi ja pakkudes selget visuaalset tagasisidet, et toiming on pooleli.

Täpsemad taastumismustrid

Oma tugeva alusega saame nüüd rakendada täpsemaid kasutajakogemusi, mis põhinevad vea tüübil.

Erinevate veatüüpide käsitlemine

Meie errorType väli on nüüd uskumatult kasulik. Saame seda kasutada täiesti erinevate kasutajaliidese komponentide renderdamiseks erinevate ebaõnnestumise stsenaariumide jaoks.

            function ErrorRecoveryUI({ state, onRetry }) {
  if (!state.errorType) return null;

  switch (state.errorType) {
    case 'VALIDATION':
      // Valideerimise puhul on peamine tagasiside reasisesed väljavead,
      // seega me ei pruugi siin spetsiaalset komponenti vajada. Globaalsest sõnumist piisab.
      return 
Palun vaadake üle punasega märgitud väljad.
;
    
    case 'SERVER_ERROR':
      return (
        

          
Ilmnes serveri viga
          
{state.message}
          Proovi uuesti
        
      );
    
    case 'AUTH_ERROR':
       return (
        

          
Sessioon on aegunud
          
Teie sessioon on aegunud. Jätkamiseks logige palun uuesti sisse.
          Mine sisselogimislehele
        
      );

    default:
      return 
{state.message}
;
  }
}

// Teie põhikomponendi return-lauses:

  {/* ... vormiväljad ... */}
   { /* loogika vormi uuesti lubamiseks */ }} />
  Salvesta


            

              
                Copy
              
            
          

"Proovi uuesti" mehhanismi rakendamine

Taastatavate vigade, nagu SERVER_ERROR, puhul on "Proovi uuesti" nupp suurepärane kasutajakogemus. Kuidas me seda rakendame? `formAction` on seotud vormi esitamise sündmusega. Lihtne lähenemine on lasta "Proovi uuesti" nupul lähtestada tegevuse olek ja uuesti lubada vorm, kutsudes kasutajat uuesti peamist esitamisnuppu klõpsama.

Kuna useActionState ei paku `reset` funktsiooni, on levinud muster selle mähkimine kohandatud haaki või selle haldamine, pannes komponendi uue võtmega uuesti renderdama, kuigi sageli on kõige lihtsam lähenemine lihtsalt kasutaja juhendamine.

Pragmaatiline lahendus: kasutaja sisend on juba säilitatud. `isPending` lipp on vale. Parim "proovi uuesti" on lihtsalt lubada kasutajal uuesti klõpsata algsel esitamisnupul. Kasutajaliides saab neid lihtsalt juhendada:

SERVER_ERROR'i korral saab meie kasutajaliides kuvada veateate: "Ilmnes viga. Teie muudatused on salvestatud. Palun proovige uuesti esitada." Esitamisnupp on juba lubatud, sest `isPending` on vale. See ei nõua keerulist olekuhaldust.

Kombineerimine `useOptimistic`'uga

Veelgi reageerivama tunde saavutamiseks sobib useActionState suurepäraselt kokku useOptimistic haagiga. Võite eeldada, et tegevus õnnestub, ja uuendada kasutajaliidest koheselt. Kui tegevus ebaõnnestub, saab useActionState veaoleku, mis käivitab uuesti renderdamise ja pöörab optimistliku uuenduse automaatselt tagasi tegelikule olekule.

See jääb selle veakäsitluse süvaanalüüsi ulatusest välja, kuid see on järgmine loogiline samm tõeliselt kaasaegsete kasutajakogemuste loomisel Reacti tegevustega.

Globaalsed kaalutlused rahvusvahelistele rakendustele

Globaalsele publikule ehitades ei ole veateadete kõvakodeerimine inglise keeles elujõuline valik.

Rahvusvahelistamine (i18n)

Meie standardiseeritud vastuse struktuuri saab hõlpsasti kohandada rahvusvahelistamiseks. Selle asemel, et tagastada kõvakodeeritud `message` stringi, peaks server tagastama sõnumi võtme või koodi.

Muudetud serveri vastus:

            {
  success: false,
  messageKey: 'errors.validation.checkFields',
  errors: {
    email: ['errors.validation.email.invalid'],
  },
  errorType: 'VALIDATION'
}

            

              
                Copy
              
            
          

Kliendi poolel kasutaksite teeki nagu react-i18next või react-intl, et tõlkida need võtmed kasutaja valitud keelde.

            import { useTranslation } from 'react-i18next';

// Teie komponendi sees
const { t } = useTranslation();

// ...

{state.messageKey && 
{t(state.messageKey)}
}

// ...

{state.errors?.email && 
{t(state.errors.email[0])}
}

            

              
                Copy
              
            
          

See eraldab teie tegevusloogika esitluskihist, muutes teie rakenduse lihtsamini hooldatavaks ja uutesse keeltesse tõlgitavaks.

Kokkuvõte

useActionState haak on midagi enamat kui lihtsalt mugavus; see on alustala kaasaegsete ja vastupidavate veebirakenduste ehitamiseks Reactis. Minnes kaugemale põhiliste veateadete kuvamisest ja võttes kasutusele põhjaliku vigadest taastumise strateegia, saate kasutajakogemust dramaatiliselt parandada.

Võtame kokku meie strateegia peamised põhimõtted:

1. Standardiseerige oma serveri vastus: Looge järjepidev JSON-struktuur kõigi oma tegevuste jaoks. See leping on prognoositava esirakenduse käitumise alustala. Lisage selge errorType, et eristada erinevaid tõrkerežiime.
2. Säilitage kasutaja sisend iga hinna eest: Kasutage vormiväljade väärtuste haldamiseks kontrollitud komponente (useState). See hoiab ära andmete kaotsimineku esitamise ebaõnnestumisel ja on andestava kasutajakogemuse nurgakivi.
3. Pakkuge kontekstipõhist tagasisidet: Kasutage oma struktureeritud veaolekut globaalsete sõnumite, reasiseste väljavigade ja kohandatud kasutajaliidese kuvamiseks erinevate veatüüpide jaoks (nt valideerimis- vs. serverivead).
4. Ehitage globaalsele publikule: Eraldage veateated oma serveriloogikast, kasutades rahvusvahelistamise võtmeid, ja arvestage alati juurdepääsetavuse standarditega (ARIA atribuudid), et tagada teie vormide kasutatavus kõigile.

Investeerides vastupidavasse veakäsitluse strateegiasse, ei paranda te ainult vigu – te ehitate usaldust oma kasutajatega. Te loote rakendusi, mis tunduvad stabiilsed, professionaalsed ning austavad nende aega ja vaeva. Laske sellel raamistikul end Reacti tegevustega edasi ehitades juhendada, et luua kogemusi, mis pole mitte ainult funktsionaalsed, vaid ka tõeliselt meeldivad kasutada, olenemata sellest, kus teie kasutajad maailmas asuvad.