Kurs Next.js · Moduł 6: Formularze i Server Actions

Obsługa błędów formularzy i komunikaty

18 min czytania ·
W tej lekcji8

Efektywna obsługa błędów formularzy to kluczowy element tworzenia przyjaznych dla użytkownika aplikacji webowych. Dobrze zaprojektowane komunikaty błędów nie tylko informują użytkownika o problemach, ale także wskazują, jak je rozwiązać. W tym module omowimy najlepsze praktyki obsługi błędów w formularzach React i Next.js, od projektowania przyjaznych komunikatów aż po zaawansowane techniki walidacji.

Rodzaje błędów w formularzach

Przed zagłębieniem się w szczegóły implementacji, warto zrozumieć różne rodzaje błędów, które mogą wystąpić w formularzach:

  1. Błędy walidacji - związane z nieprawidłowymi danymi wprowadzonymi przez użytkownika (np. niepoprawny format email)
  2. Błędy serwera - problemy podczas przetwarzania danych po stronie serwera (np. błąd bazy danych)
  3. Błędy sieci - problemy z połączeniem (np. timeout, offline)
  4. Błędy biznesowe - dane są technicznie poprawne, ale naruszają reguły biznesowe (np. duplikat adresu email)
  5. Błędy dostępności - formularz jest trudny lub niemożliwy do użycia dla osób z niepełnosprawnościami

Projektowanie przyjaznych komunikatów błędów

Dobrze zaprojektowane komunikaty błędów powinny spełniać następujące kryteria:

1. Być jasne i konkretne

Źle: "Błąd walidacji" Dobrze: "Hasło musi zawierać co najmniej 8 znaków, w tym cyfrę i wielką literę"

2. Używać języka przyjaznego dla użytkownika

Źle: "Wystąpił błąd parsowania JSON: nieoczekiwany token na pozycji 42" Dobrze: "Wystąpił problem techniczny. Spróbuj ponownie lub skontaktuj się z nami."

3. Sugerować rozwiązanie

Źle: "Niepoprawny format numeru telefonu" Dobrze: "Wprowadź numer telefonu w formacie 123-456-789"

4. Być widoczne w odpowiednim miejscu

Komunikaty błędów powinny być wyświetlane blisko problematycznego pola, a nie tylko na górze formularza.

5. Mieć odpowiedni kontrast i dostępność

Komunikaty błędów powinny być dobrze widoczne i dostępne dla wszystkich użytkowników, w tym osób korzystających z czytników ekranu.

Implementacja obsługi błędów w formularzach React

Przejdźmy do praktycznych przykładów implementacji obsługi błędów w różnych podejściach do formularzy.

Natywne formularze React

W natywnych formularzach React, błędy możemy obsługiwać za pomocą stanu:

import { useState, FormEvent, ChangeEvent } from 'react';

type FormErrors = {
  name?: string;
  email?: string;
  password?: string;
  generalError?: string;
};

export default function SignupForm() {
  const [formData, setFormData] = useState({
    name: '',
    email: '',
    password: ''
  });

  const [errors, setErrors] = useState<FormErrors>({});
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [submitSuccess, setSubmitSuccess] = useState(false);

  const validateForm = (): boolean => {
    const newErrors: FormErrors = {};
    let isValid = true;

    // Walidacja imienia
    if (!formData.name.trim()) {
      newErrors.name = 'Imię jest wymagane';
      isValid = false;
    }

    // Walidacja email
    if (!formData.email.trim()) {
      newErrors.email = 'Email jest wymagany';
      isValid = false;
    } else if (!/^\S+@\S+\.\S+$/.test(formData.email)) {
      newErrors.email = 'Podaj prawidłowy adres email';
      isValid = false;
    }

    // Walidacja hasła
    if (!formData.password) {
      newErrors.password = 'Hasło jest wymagane';
      isValid = false;
    } else if (formData.password.length < 8) {
      newErrors.password = 'Hasło musi mieć co najmniej 8 znaków';
      isValid = false;
    } else if (!/[A-Z]/.test(formData.password)) {
      newErrors.password = 'Hasło musi zawierać co najmniej jedną wielką literę';
      isValid = false;
    } else if (!/[0-9]/.test(formData.password)) {
      newErrors.password = 'Hasło musi zawierać co najmniej jedną cyfrę';
      isValid = false;
    }

    setErrors(newErrors);
    return isValid;
  };

  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
    const { name, value } = e.target;

    // Aktualizacja danych formularza
    setFormData(prev => ({
      ...prev,
      [name]: value
    }));

    // Usunięcie błędu dla edytowanego pola
    if (errors[name as keyof FormErrors]) {
      setErrors(prev => {
        const newErrors = { ...prev };
        delete newErrors[name as keyof FormErrors];
        return newErrors;
      });
    }
  };

  const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    // Resetowanie stanu przed wysyłką
    setErrors({});
    setSubmitSuccess(false);

    // Walidacja formularza
    if (!validateForm()) {
      return;
    }

    setIsSubmitting(true);

    try {
      // Symulacja wysyłki do API z losowym błędem
      await new Promise(resolve => setTimeout(resolve, 1000));

      // Symulacja losowego błędu serwera (25% szans)
      if (Math.random() < 0.25) {
        throw new Error('Wystąpił błąd podczas przetwarzania formularza');
      }

      // Symulacja błędu biznesowego - już istniejący email (25% szans)
      if (Math.random() < 0.25) {
        setErrors({
          email: 'Ten adres email jest już zarejestrowany'
        });
        return;
      }

      // Sukces
      setSubmitSuccess(true);
      setFormData({ name: '', email: '', password: '' });
      console.log('Formularz wysłany pomyślnie:', formData);
    } catch (error) {
      // Obsługa błędu serwera
      setErrors({
        generalError: 'Wystąpił problem podczas przetwarzania formularza. Spróbuj ponownie później.'
      });
      console.error('Błąd wysyłki formularza:', error);
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
      <h1 className="text-2xl font-bold mb-6">Rejestracja</h1>

      {submitSuccess && (
        <div className="mb-4 p-3 bg-green-100 border border-green-400 text-green-700 rounded">
          Rejestracja przebiegła pomyślnie! Sprawdź swój email w celu aktywacji konta.
        </div>
      )}

      {errors.generalError && (
        <div className="mb-4 p-3 bg-red-100 border border-red-400 text-red-700 rounded" role="alert">
          <p className="font-bold">Wystąpił błąd</p>
          <p>{errors.generalError}</p>
        </div>
      )}

      <form onSubmit={handleSubmit} className="space-y-4" noValidate>
        <div>
          <label htmlFor="name" className="block text-sm font-medium text-gray-700">
            Imię i nazwisko
          </label>
          <input
            type="text"
            id="name"
            name="name"
            value={formData.name}
            onChange={handleChange}
            aria-invalid={Boolean(errors.name)}
            aria-describedby={errors.name ? 'name-error' : undefined}
            className={`mt-1 block w-full rounded-md shadow-sm ${errors.name ? 'border-red-500' : 'border-gray-300'}`}
          />
          {errors.name && (
            <p className="mt-1 text-sm text-red-600" id="name-error" role="alert">
              {errors.name}
            </p>
          )}
        </div>

        <div>
          <label htmlFor="email" className="block text-sm font-medium text-gray-700">
            Email
          </label>
          <input
            type="email"
            id="email"
            name="email"
            value={formData.email}
            onChange={handleChange}
            aria-invalid={Boolean(errors.email)}
            aria-describedby={errors.email ? 'email-error' : undefined}
            className={`mt-1 block w-full rounded-md shadow-sm ${errors.email ? 'border-red-500' : 'border-gray-300'}`}
          />
          {errors.email && (
            <p className="mt-1 text-sm text-red-600" id="email-error" role="alert">
              {errors.email}
            </p>
          )}
        </div>

        <div>
          <label htmlFor="password" className="block text-sm font-medium text-gray-700">
            Hasło
          </label>
          <input
            type="password"
            id="password"
            name="password"
            value={formData.password}
            onChange={handleChange}
            aria-invalid={Boolean(errors.password)}
            aria-describedby={errors.password ? 'password-error' : 'password-rules'}
            className={`mt-1 block w-full rounded-md shadow-sm ${errors.password ? 'border-red-500' : 'border-gray-300'}`}
          />
          {errors.password ? (
            <p className="mt-1 text-sm text-red-600" id="password-error" role="alert">
              {errors.password}
            </p>
          ) : (
            <p className="mt-1 text-xs text-gray-500" id="password-rules">
              Hasło powinno mieć co najmniej 8 znaków, zawierać wielką literę i cyfrę.
            </p>
          )}
        </div>

        <button
          type="submit"
          disabled={isSubmitting}
          className="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50"
        >
          {isSubmitting ? 'Przetwarzanie...' : 'Zarejestruj się'}
        </button>
      </form>
    </div>
  );
}

Kluczowe elementy obsługi błędów w tym przykładzie:

  1. Stan błędów - osobny obiekt przechowujący błędy dla poszczególnych pól i ogólny błąd
  2. Atrybuty dostępności - aria-invalid i aria-describedby dla czytników ekranu
  3. Dynamiczna walidacja - usuwanie błędów podczas edycji pola
  4. Wskazówki wizualne - czerwona obwódka dla niepoprawnych pól
  5. Komunikaty pomocnicze - wskazówki dotyczące zasad hasła przed wystąpieniem błędu

Obsługa błędów z React Hook Form

React Hook Form oferuje zaawansowane możliwości obsługi błędów:

import { useForm, SubmitHandler } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { useState } from 'react';

// Schemat walidacji
const signupSchema = z.object({
  name: z.string().min(1, { message: 'Imię jest wymagane' }),
  email: z.string().email({ message: 'Podaj prawidłowy adres email' }),
  password: z.string()
    .min(8, { message: 'Hasło musi mieć co najmniej 8 znaków' })
    .regex(/[A-Z]/, { message: 'Hasło musi zawierać co najmniej jedną wielką literę' })
    .regex(/[0-9]/, { message: 'Hasło musi zawierać co najmniej jedną cyfrę' })
});

type SignupFormInputs = z.infer<typeof signupSchema>;

export default function HookFormSignup() {
  const [serverError, setServerError] = useState<string | null>(null);
  const [submitSuccess, setSubmitSuccess] = useState(false);

  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting, touchedFields, isDirty },
    reset
  } = useForm<SignupFormInputs>({
    resolver: zodResolver(signupSchema),
    mode: 'onTouched' // Walidacja przy utracie fokusu
  });

  const onSubmit: SubmitHandler<SignupFormInputs> = async (data) => {
    // Resetujemy błędy serwera i sukces przed nową próbą
    setServerError(null);
    setSubmitSuccess(false);

    try {
      // Symulacja wysyłki do API
      await new Promise(resolve => setTimeout(resolve, 1000));

      // Symulacja losowego błędu serwera (25% szans)
      if (Math.random() < 0.25) {
        throw new Error('Wystąpił błąd podczas przetwarzania formularza');
      }

      // Symulacja błędu biznesowego - już istniejący email (25% szans)
      if (Math.random() < 0.25) {
        throw new Error('Ten adres email jest już zarejestrowany');
      }

      // Sukces
      console.log('Formularz wysłany pomyślnie:', data);
      setSubmitSuccess(true);
      reset(); // Czyszczenie formularza
    } catch (error) {
      if (error instanceof Error) {
        setServerError(error.message);
      } else {
        setServerError('Wystąpił nieznany błąd. Spróbuj ponownie później.');
      }
      console.error('Błąd wysyłki formularza:', error);
    }
  };

  return (
    <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
      <h1 className="text-2xl font-bold mb-6">Rejestracja (React Hook Form)</h1>

      {submitSuccess && (
        <div className="mb-4 p-3 bg-green-100 border border-green-400 text-green-700 rounded">
          Rejestracja przebiegła pomyślnie! Sprawdź swój email w celu aktywacji konta.
        </div>
      )}

      {serverError && (
        <div className="mb-4 p-3 bg-red-100 border border-red-400 text-red-700 rounded" role="alert">
          <p className="font-bold">Wystąpił błąd</p>
          <p>{serverError}</p>
        </div>
      )}

      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4" noValidate>
        <div>
          <label htmlFor="name" className="block text-sm font-medium text-gray-700">
            Imię i nazwisko
          </label>
          <input
            id="name"
            type="text"
            aria-invalid={Boolean(errors.name)}
            aria-describedby={errors.name ? 'name-error' : undefined}
            className={`mt-1 block w-full rounded-md shadow-sm ${errors.name ? 'border-red-500' : touchedFields.name ? 'border-green-500' : 'border-gray-300'}`}
            {...register('name')}
          />
          {errors.name && (
            <p className="mt-1 text-sm text-red-600" id="name-error" role="alert">
              {errors.name.message}
            </p>
          )}
        </div>

        <div>
          <label htmlFor="email" className="block text-sm font-medium text-gray-700">
            Email
          </label>
          <input
            id="email"
            type="email"
            aria-invalid={Boolean(errors.email)}
            aria-describedby={errors.email ? 'email-error' : undefined}
            className={`mt-1 block w-full rounded-md shadow-sm ${errors.email ? 'border-red-500' : touchedFields.email ? 'border-green-500' : 'border-gray-300'}`}
            {...register('email')}
          />
          {errors.email && (
            <p className="mt-1 text-sm text-red-600" id="email-error" role="alert">
              {errors.email.message}
            </p>
          )}
        </div>

        <div>
          <label htmlFor="password" className="block text-sm font-medium text-gray-700">
            Hasło
          </label>
          <input
            id="password"
            type="password"
            aria-invalid={Boolean(errors.password)}
            aria-describedby={errors.password ? 'password-error' : 'password-rules'}
            className={`mt-1 block w-full rounded-md shadow-sm ${errors.password ? 'border-red-500' : touchedFields.password ? 'border-green-500' : 'border-gray-300'}`}
            {...register('password')}
          />
          {errors.password ? (
            <p className="mt-1 text-sm text-red-600" id="password-error" role="alert">
              {errors.password.message}
            </p>
          ) : (
            <p className="mt-1 text-xs text-gray-500" id="password-rules">
              Hasło powinno mieć co najmniej 8 znaków, zawierać wielką literę i cyfrę.
            </p>
          )}
        </div>

        <button
          type="submit"
          disabled={isSubmitting || !isDirty}
          className="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50"
        >
          {isSubmitting ? 'Przetwarzanie...' : 'Zarejestruj się'}
        </button>
      </form>
    </div>
  );
}

Kluczowe elementy obsługi błędów w React Hook Form:

  1. Walidacja z Zod - czytelne i typowane schematy walidacji
  2. Wiele stanów formularza - isSubmitting, touchedFields, isDirty
  3. Tryby walidacji - konfiguracja z mode: 'onTouched'
  4. Wizualne wskaźniki stanu - zielona obwódka dla poprawnych, czerwona dla błędnych pól
  5. Integracja z ARIA - pełna dostępność forŭmularza

Obsługa błędów w Server Actions (Next.js)

W formularzach korzystających z Server Actions w Next.js, obsługa błędów jest szczególnie istotna, ponieważ procesowanie odbywa się na serwerze:

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

import { z } from 'zod';

const contactSchema = z.object({
  name: z.string().min(1, { message: 'Imię jest wymagane' }),
  email: z.string().email({ message: 'Podaj prawidłowy adres email' }),
  subject: z.string().min(3, { message: 'Temat jest zbyt krótki' }),
  message: z.string().min(10, { message: 'Wiadomość musi mieć co najmniej 10 znaków' })
});

export type ContactFormState = {
  errors?: {
    name?: string[];
    email?: string[];
    subject?: string[];
    message?: string[];
    _form?: string[];
  };
  message?: string;
  success?: boolean;
};

export async function submitContactForm(
  prevState: ContactFormState,
  formData: FormData
): Promise<ContactFormState> {
  // Konwersja FormData na obiekt
  const rawFormData = {
    name: formData.get('name'),
    email: formData.get('email'),
    subject: formData.get('subject'),
    message: formData.get('message')
  };

  // Walidacja danych
  const validationResult = contactSchema.safeParse(rawFormData);

  // Jeśli walidacja nie powiedzie się
  if (!validationResult.success) {
    // Konwersja błędów Zod na format dla formularza
    return {
      errors: validationResult.error.flatten().fieldErrors,
      message: 'Proszę poprawić błędy w formularzu',
      success: false
    };
  }

  try {
    // Symulacja opóźnienia API
    await new Promise(resolve => setTimeout(resolve, 1000));

    // Symulacja losowego błędu serwera (15% szans)
    if (Math.random() < 0.15) {
      throw new Error('Problem z połączeniem z serwerem');
    }

    // Symulacja błędu spamowego (10% szans)
    if (Math.random() < 0.1) {
      return {
        errors: {
          _form: ['Wykryto możliwy spam. Spróbuj ponownie później.']
        },
        success: false
      };
    }

    // Symulacja przetwarzania formularza
    console.log('Przetwarzanie formularza kontaktowego:', validationResult.data);

    return {
      message: 'Wiadomość została wysłana pomyślnie. Odpowiemy najszybciej jak to możliwe.',
      success: true
    };
  } catch (error) {
    // Obsługa błędów serwera
    return {
      errors: {
        _form: [
          'Wystąpił błąd podczas przetwarzania formularza. ' +
          'Spróbuj ponownie później lub skontaktuj się z nami bezpośrednio.'
        ]
      },
      success: false
    };
  }
}

I komponent używający tej akcji:

// app/contact/page.tsx
'use client';

import { useRef, useEffect } from 'react';
import { useActionState } from 'react';
import { useFormStatus } from 'react-dom';
import { submitContactForm, type ContactFormState } from '../actions';

// Komponent przycisku z obsługą stanu wysyłania
function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      aria-disabled={pending}
      className="w-full py-2 px-4 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50"
    >
      {pending ? 'Wysyłanie...' : 'Wyślij wiadomość'}
    </button>
  );
}

export default function ContactForm() {
  const formRef = useRef<HTMLFormElement>(null);

  // Inicjalizacja stanu formularza
  const initialState: ContactFormState = { errors: {} };

  // Połączenie z Server Action
  const [state, formAction] = useActionState(submitContactForm, initialState);

  // Resetowanie formularza po pomyślnym wysłaniu
  useEffect(() => {
    if (state.success && formRef.current) {
      formRef.current.reset();

      // Skupienie się na komunikacie sukcesu dla czytników ekranu
      const successMessage = document.getElementById('success-message');
      if (successMessage) {
        successMessage.focus();
      }
    }
  }, [state.success]);

  return (
    <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
      <h1 className="text-2xl font-bold mb-6">Skontaktuj się z nami</h1>

      {state.success && (
        <div
          id="success-message"
          tabIndex={-1}
          className="mb-4 p-3 bg-green-100 border border-green-400 text-green-700 rounded"
          role="alert"
        >
          {state.message}
        </div>
      )}

      {state.errors?._form && (
        <div className="mb-4 p-3 bg-red-100 border border-red-400 text-red-700 rounded" role="alert">
          <ul className="list-disc pl-5">
            {state.errors._form.map((error, index) => (
              <li key={index}>{error}</li>
            ))}
          </ul>
        </div>
      )}

      <form ref={formRef} action={formAction} className="space-y-4" noValidate>
        <div>
          <label htmlFor="name" className="block text-sm font-medium text-gray-700">
            Imię i nazwisko
          </label>
          <input
            type="text"
            id="name"
            name="name"
            aria-invalid={Boolean(state.errors?.name)}
            aria-describedby={state.errors?.name ? 'name-error' : undefined}
            className={`mt-1 block w-full rounded-md shadow-sm ${state.errors?.name ? 'border-red-500' : 'border-gray-300'}`}
          />
          {state.errors?.name && (
            <p className="mt-1 text-sm text-red-600" id="name-error" role="alert">
              {state.errors.name[0]}
            </p>
          )}
        </div>

        <div>
          <label htmlFor="email" className="block text-sm font-medium text-gray-700">
            Email
          </label>
          <input
            type="email"
            id="email"
            name="email"
            aria-invalid={Boolean(state.errors?.email)}
            aria-describedby={state.errors?.email ? 'email-error' : undefined}
            className={`mt-1 block w-full rounded-md shadow-sm ${state.errors?.email ? 'border-red-500' : 'border-gray-300'}`}
          />
          {state.errors?.email && (
            <p className="mt-1 text-sm text-red-600" id="email-error" role="alert">
              {state.errors.email[0]}
            </p>
          )}
        </div>

        <div>
          <label htmlFor="subject" className="block text-sm font-medium text-gray-700">
            Temat
          </label>
          <input
            type="text"
            id="subject"
            name="subject"
            aria-invalid={Boolean(state.errors?.subject)}
            aria-describedby={state.errors?.subject ? 'subject-error' : undefined}
            className={`mt-1 block w-full rounded-md shadow-sm ${state.errors?.subject ? 'border-red-500' : 'border-gray-300'}`}
          />
          {state.errors?.subject && (
            <p className="mt-1 text-sm text-red-600" id="subject-error" role="alert">
              {state.errors.subject[0]}
            </p>
          )}
        </div>

        <div>
          <label htmlFor="message" className="block text-sm font-medium text-gray-700">
            Wiadomość
          </label>
          <textarea
            id="message"
            name="message"
            rows={4}
            aria-invalid={Boolean(state.errors?.message)}
            aria-describedby={state.errors?.message ? 'message-error' : undefined}
            className={`mt-1 block w-full rounded-md shadow-sm ${state.errors?.message ? 'border-red-500' : 'border-gray-300'}`}
          />
          {state.errors?.message && (
            <p className="mt-1 text-sm text-red-600" id="message-error" role="alert">
              {state.errors.message[0]}
            </p>
          )}
        </div>

        <SubmitButton />
      </form>
    </div>
  );
}

Kluczowe elementy obsługi błędów z Server Actions:

  1. Struktura błędów - specjalny format z błędami dla pól i ogólnym błędem formularza
  2. useActionState i useFormStatus - hooki do śledzenia stanu formularza i procesu wysyłki
  3. Focus po sukcesie - przesunięcie fokusu do komunikatu sukcesu dla użytkowników czytników ekranu
  4. Struktura danych zwrotnych - spójny format odpowiedzi z serwera
  5. Wiele rodzajów błędów - różne scenariusze błędów dla różnych przyczyn

Zaawansowane wzorce obsługi błędów

Konteksty błędów formularza

Dla bardziej złożonych formularzy, warto rozważyć utworzenie kontekstu błędów:

// contexts/FormErrorContext.tsx
import { createContext, useContext, ReactNode, useState } from 'react';

type ErrorsType = Record<string, string[]>;

interface FormErrorContextType {
  errors: ErrorsType;
  setErrors: (errors: ErrorsType) => void;
  clearErrors: () => void;
  clearFieldError: (fieldName: string) => void;
  hasErrors: boolean;
  getFieldErrors: (fieldName: string) => string[] | undefined;
}

const FormErrorContext = createContext<FormErrorContextType | null>(null);

export function FormErrorProvider({ children }: { children: ReactNode }) {
  const [errors, setErrors] = useState<ErrorsType>({});

  const clearErrors = () => setErrors({});

  const clearFieldError = (fieldName: string) => {
    setErrors(prev => {
      const newErrors = { ...prev };
      delete newErrors[fieldName];
      return newErrors;
    });
  };

  const getFieldErrors = (fieldName: string) => errors[fieldName];

  const hasErrors = Object.keys(errors).length > 0;

  return (
    <FormErrorContext.Provider value={{
      errors,
      setErrors,
      clearErrors,
      clearFieldError,
      hasErrors,
      getFieldErrors
    }}>
      {children}
    </FormErrorContext.Provider>
  );
}

export function useFormErrors() {
  const context = useContext(FormErrorContext);
  if (!context) {
    throw new Error('useFormErrors must be used within a FormErrorProvider');
  }
  return context;
}

Komponent błędu formularza (reużywalny)

// components/FormError.tsx
import { useId } from 'react';

interface FormErrorProps {
  errors?: string[];
  id?: string;
}

export function FormError({ errors, id: propId }: FormErrorProps) {
  const generatedId = useId();
  const id = propId || generatedId;

  if (!errors || errors.length === 0) {
    return null;
  }

  return (
    <div className="mt-1" id={id} role="alert">
      {errors.map((error, index) => (
        <p key={index} className="text-sm text-red-600">
          {error}
        </p>
      ))}
    </div>
  );
}

Komponent pola formularza (reużywalny)

// components/FormField.tsx
import { InputHTMLAttributes, ReactNode, useId } from 'react';
import { FormError } from './FormError';
import { useFormErrors } from '../contexts/FormErrorContext';

interface FormFieldProps extends InputHTMLAttributes<HTMLInputElement> {
  label: string;
  name: string;
  errors?: string[];
  children?: ReactNode;
  helpText?: string;
}

export function FormField({
  label,
  name,
  errors: propErrors,
  children,
  helpText,
  ...rest
}: FormFieldProps) {
  const fieldId = useId();
  const errorId = `${fieldId}-error`;
  const helpId = `${fieldId}-help`;

  // Możemy użyć kontekstu błędów, jeśli błędy nie są przekazane jako prop
  const { getFieldErrors } = useFormErrors();
  const errors = propErrors || getFieldErrors(name);

  const hasError = errors && errors.length > 0;

  // Określ, który element opisuje to pole (błąd lub tekst pomocniczy)
  const ariaDescribedBy = hasError ? errorId : helpText ? helpId : undefined;

  return (
    <div>
      <label htmlFor={fieldId} className="block text-sm font-medium text-gray-700">
        {label}
      </label>

      <div className="mt-1">
        {children ? (
          // Jeśli przekazano dzieci (np. niestandardowe pola)
          children
        ) : (
          // Domyślnie renderuj inputa
          <input
            id={fieldId}
            name={name}
            aria-invalid={hasError}
            aria-describedby={ariaDescribedBy}
            className={`block w-full rounded-md shadow-sm ${hasError ? 'border-red-500' : 'border-gray-300'}`}
            {...rest}
          />
        )}
      </div>

      {hasError ? (
        // Pokaż błędy
        <FormError errors={errors} id={errorId} />
      ) : helpText ? (
        // Pokaż tekst pomocniczy jeśli nie ma błędów
        <p className="mt-1 text-xs text-gray-500" id={helpId}>
          {helpText}
        </p>
      ) : null}
    </div>
  );
}

Przykład użycia reużywalnych komponentów

// app/registration/page.tsx
import { FormErrorProvider } from '../contexts/FormErrorContext';
import { FormField } from '../components/FormField';

export default function RegistrationPage() {
  return (
    <FormErrorProvider>
      <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
        <h1 className="text-2xl font-bold mb-6">Rejestracja</h1>

        <form className="space-y-4" noValidate>
          <FormField
            label="Imię i nazwisko"
            name="name"
            type="text"
            required
            helpText="Wprowadź swoje pełne imię i nazwisko"
          />

          <FormField
            label="Email"
            name="email"
            type="email"
            required
            helpText="Ten adres będzie służył do logowania do konta"
          />

          <FormField
            label="Hasło"
            name="password"
            type="password"
            required
            helpText="Hasło powinno mieć co najmniej 8 znaków, zawierać wielką literę i cyfrę"
          />

          {/* Niestandardowe pole z własną implementacją */}
          <FormField
            label="Kategoria konta"
            name="accountType"
            helpText="Wybierz typ konta odpowiedni dla Twoich potrzeb"
          >
            <div className="flex space-x-4">
              <label className="inline-flex items-center">
                <input type="radio" name="accountType" value="personal" className="mr-2" />
                Osobiste
              </label>
              <label className="inline-flex items-center">
                <input type="radio" name="accountType" value="business" className="mr-2" />
                Biznesowe
              </label>
            </div>
          </FormField>

          <button
            type="submit"
            className="w-full py-2 px-4 bg-blue-600 text-white rounded-md hover:bg-blue-700"
          >
            Zarejestruj się
          </button>
        </form>
      </div>
    </FormErrorProvider>
  );
}

Strategie obsługi błędów formularzy i ich wpływ na UX

Różne strategie obsługi błędów mogą znacząco wpłynąć na doświadczenie użytkownika:

1. Walidacja w czasie rzeczywistym vs przy wysyłce

Walidacja w czasie rzeczywistym:

  • Zalety: Natychmiastowa informacja zwrotna, mniej frustracji przy wysyłce
  • Wady: Może być przytłaczająca i irytująca, jeśli pojawia się zbyt wcześnie

Walidacja przy wysyłce:

  • Zalety: Mniej rozpraszająca, pozwala użytkownikowi najpierw wprowadzić dane
  • Wady: Może być frustrująca, jeśli użytkownik wypełnia długi formularz, a potem musi wracać do poprawek

Najlepsze podejście: Kompromis - walidacja przy utracie fokusu lub po pierwszej próbie wysyłki

2. Walidacja po stronie klienta vs serwera

Walidacja po stronie klienta:

  • Zalety: Szybka, bez opóźnienia sieciowego, oszczędza zasoby serwera
  • Wady: Może zostać ominięta, nie zawsze odzwierciedla faktyczne reguły biznesowe

Walidacja po stronie serwera:

  • Zalety: Niezawodna, spójna, uwzględnia aktualny stan systemu
  • Wady: Opóźniona informacja zwrotna, większe obciążenie serwera

Najlepsze podejście: Walidacja na obu poziomach - klient dla UX, serwer dla bezpieczeństwa

3. Walidacja pól vs formularza jako całości

Walidacja poszczególnych pól:

  • Zalety: Precyzyjna informacja o błędach, łatwiejsze poprawianie
  • Wady: Nie uwzględnia zależności między polami

Walidacja całego formularza:

  • Zalety: Może uwzględniać zależności między polami
  • Wady: Może być przytłaczająca, jeśli formularz ma wiele błędów

Najlepsze podejście: Walidacja pól podczas wprowadzania i pełna walidacja przy wysyłce

Dobre praktyki obsługi błędów formularzy

  1. Grupuj powiązane błędy - błędy dotyczące całego formularza umieszczaj na górze, błędy konkretnych pól - przy polach

  2. Zachowaj spójność wizualną - używaj tych samych kolorów, ikon i styli dla błędów w całej aplikacji

  3. Doskonal komunikaty - zamiast "Nieprawidłowe dane" napisz dokładnie, co jest nie tak i jak to naprawić

  4. Zachowaj dane przy błędach - nie resetuj całego formularza po wystąpieniu błędu

  5. Priorytetyzuj błędy - najpierw pokaż krytyczne błędy, potem mniej istotne

  6. Automatycznie przewijaj do błędów - szczególnie w długich formularzach, automatycznie przewijaj do pierwszego błędu

  7. Wykorzystuj ARIA - używaj atrybutów aria-invalid, aria-describedby i role="alert" dla dostępności

  8. Oznaczaj wymagane pola - jasno oznacz, które pola są wymagane, najlepiej przed wypełnianiem formularza

  9. Podawaj przykłady - dla skomplikowanych formatów (np. data, numer telefonu) podawaj przykłady

  10. Testuj z użytkownikami - regularnie testuj formularze z rzeczywistymi użytkownikami, aby zidentyfikować problemy

Obsługa błędów a dostępność

Efektywna obsługa błędów jest szczególnie ważna dla użytkowników z niepełnosprawnościami:

  1. Używaj atrybutów ARIA

    • aria-invalid="true" dla niepoprawnych pól
    • aria-describedby łączący pole z komunikatem błędu
    • role="alert" dla komunikatów błędów, które powinny być natychmiast odczytane
  2. Nie polegaj tylko na kolorach

    • Dodaj ikony lub inne wskaźniki wizualne oprócz koloru czerwonego
    • Zapewnij wystarczający kontrast między tekstem a tłem
  3. Używaj <fieldset> i <legend>

    • Grupuj powiązane pola za pomocą <fieldset>
    • Opisuj grupy pól za pomocą <legend>
  4. Prawidłowa kolejność tabulacji

    • Upewnij się, że użytkownicy klawiatury mogą poruszać się między polami w logicznej kolejności
  5. Podsumowanie błędów

    • Dla złożonych formularzy, dodaj podsumowanie błędów na górze formularza
    • Każdy błąd powinien zawierać link do odpowiedniego pola

Podsumowanie

Efektywna obsługa błędów formularzy to znacznie więcej niż tylko informowanie użytkownika o problemach. To kompleksowe podejście, łączące:

  1. Projektowanie przyjaznych komunikatów - jasne, konkretne i pomocne
  2. Walidację na wielu poziomach - klient + serwer, poszczególne pola + cały formularz
  3. Odpowiedni timing - wybieranie optymalnego momentu na pokaźnie błędów
  4. Dostępność - zapewnienie, że wszyscy użytkownicy mogą zrozumieć i poprawić błędy
  5. Spójność wizualną - jednolite style i zachowania w całej aplikacji

Pamiętaj, że cel to nie tylko wykrycie błędów, ale przede wszystkim pomoc użytkownikowi w ich skutecznym poprawieniu i pomyślnym ukończeniu formularza. Dobrze zaprojektowana obsługa błędów może znacząco poprawić współczynnik konwersji i satysfakcję użytkowników.

Kod do tej lekcji: App.tsx
import React, { useState } from 'react';

// Obsluga bledow formularzy - komunikaty, UX, strategie wyswietlania

type ValidationStrategy = 'onSubmit' | 'onBlur' | 'onChange';

interface FieldState {
  value: string;
  error: string;
  touched: boolean;
}

const validateField = (name: string, value: string): string => {
  switch (name) {
    case 'name':
      if (!value) return 'Imie jest wymagane';
      if (value.length < 2) return 'Imie musi miec min. 2 znaki';
      return '';
    case 'email':
      if (!value) return 'Email jest wymagany';
      if (!/\S+@\S+\.\S+/.test(value)) return 'Nieprawidlowy format email';
      return '';
    case 'password':
      if (!value) return 'Haslo jest wymagane';
      if (value.length < 8) return 'Haslo musi miec min. 8 znakow';
      if (!/[A-Z]/.test(value)) return 'Haslo musi zawierac wielka litere';
      if (!/[0-9]/.test(value)) return 'Haslo musi zawierac cyfre';
      return '';
    default: return '';
  }
};

export default function ErrorHandlingDemo() {
  const [strategy, setStrategy] = useState<ValidationStrategy>('onBlur');
  const [fields, setFields] = useState<Record<string, FieldState>>({
    name: { value: '', error: '', touched: false },
    email: { value: '', error: '', touched: false },
    password: { value: '', error: '', touched: false },
  });
  const [submitted, setSubmitted] = useState(false);

  const updateField = (name: string, value: string) => {
    const error = strategy === 'onChange' ? validateField(name, value) : fields[name].error;
    setFields(prev => ({ ...prev, [name]: { ...prev[name], value, error } }));
  };

  const blurField = (name: string) => {
    if (strategy === 'onBlur' || strategy === 'onChange') {
      const error = validateField(name, fields[name].value);
      setFields(prev => ({ ...prev, [name]: { ...prev[name], touched: true, error } }));
    }
  };

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const newFields = { ...fields };
    let valid = true;
    for (const name of Object.keys(newFields)) {
      const error = validateField(name, newFields[name].value);
      newFields[name] = { ...newFields[name], error, touched: true };
      if (error) valid = false;
    }
    setFields(newFields);
    setSubmitted(valid);
  };

  const inputStyle = (hasError: boolean): React.CSSProperties => ({
    width: '100%', padding: '10px', background: '#0d1117',
    border: `1px solid ${hasError ? '#f44336' : '#333'}`, borderRadius: 6,
    color: '#e0e0e0', fontFamily: 'monospace', fontSize: 13, boxSizing: 'border-box' as const
  });

  const strategies: { value: ValidationStrategy; label: string }[] = [
    { value: 'onSubmit', label: 'Przy submit' },
    { value: 'onBlur', label: 'Przy blur (opuszczeniu pola)' },
    { value: 'onChange', label: 'Przy kazdej zmianie' },
  ];

  return (
    <div style={{ background: '#0f0f23', minHeight: '100vh', padding: 20, color: '#e0e0e0', fontFamily: 'monospace' }}>
      <h1 style={{ color: '#64ffda' }}>Obsluga bledow formularzy</h1>

      <div style={{ display: 'flex', gap: 8, marginBottom: 16, flexWrap: 'wrap' }}>
        {strategies.map(s => (
          <button key={s.value} onClick={() => {
            setStrategy(s.value);
            setFields(Object.fromEntries(Object.keys(fields).map(k => [k, { value: '', error: '', touched: false }])));
            setSubmitted(false);
          }} style={{
            background: strategy === s.value ? '#1565c0' : '#1a2744',
            color: '#fff', border: `1px solid ${strategy === s.value ? '#64ffda' : '#333'}`,
            borderRadius: 6, padding: '6px 12px', cursor: 'pointer', fontSize: 11, fontFamily: 'monospace'
          }}>
            {s.label}
          </button>
        ))}
      </div>

      <form onSubmit={handleSubmit} style={{ maxWidth: 400 }}>
        {Object.entries(fields).map(([name, field]) => (
          <div key={name} style={{ marginBottom: 12 }}>
            <label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>{name}</label>
            <input
              type={name === 'password' ? 'password' : 'text'}
              value={field.value}
              onChange={e => updateField(name, e.target.value)}
              onBlur={() => blurField(name)}
              style={inputStyle(!!field.error && field.touched)}
            />
            {field.error && field.touched && (
              <div style={{ color: '#f44336', fontSize: 11, marginTop: 4, display: 'flex', alignItems: 'center', gap: 4 }}>
                <span>&#9888;</span> {field.error}
              </div>
            )}
          </div>
        ))}
        <button type="submit" style={{
          background: '#f44336', color: '#fff', border: 'none', borderRadius: 6,
          padding: '10px 20px', cursor: 'pointer', fontFamily: 'monospace', width: '100%'
        }}>
          Wyslij
        </button>
      </form>

      {submitted && (
        <div style={{ marginTop: 16, background: '#1b5e20', borderRadius: 8, padding: 12, maxWidth: 400, border: '1px solid #4caf50' }}>
          Formularz wyslany pomyslnie!
        </div>
      )}
    </div>
  );
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Zadania praktyczne w grze

  • Układanie w poziomie

    Ułóż łańcuch walidacji Zod dla pola email z minimum 5 znakami

  • Klikanie w kolejności

    Ułóż składnię konfiguracji formularza z resolverem Zod

  1. Ułóż w kolejnościŁańcuch walidacji Zod dla emaila
  2. Kliknij w kolejnościSkładnia walidacji Zod z React Hook Form

Przydatne artykuły