Kurs Next.js · Moduł 6: Formularze i Server Actions
Obsługa błędów formularzy i komunikaty
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:
- Błędy walidacji - związane z nieprawidłowymi danymi wprowadzonymi przez użytkownika (np. niepoprawny format email)
- Błędy serwera - problemy podczas przetwarzania danych po stronie serwera (np. błąd bazy danych)
- Błędy sieci - problemy z połączeniem (np. timeout, offline)
- Błędy biznesowe - dane są technicznie poprawne, ale naruszają reguły biznesowe (np. duplikat adresu email)
- 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:
- Stan błędów - osobny obiekt przechowujący błędy dla poszczególnych pól i ogólny błąd
- Atrybuty dostępności -
aria-invalidiaria-describedbydla czytników ekranu - Dynamiczna walidacja - usuwanie błędów podczas edycji pola
- Wskazówki wizualne - czerwona obwódka dla niepoprawnych pól
- 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:
- Walidacja z Zod - czytelne i typowane schematy walidacji
- Wiele stanów formularza -
isSubmitting,touchedFields,isDirty - Tryby walidacji - konfiguracja z
mode: 'onTouched' - Wizualne wskaźniki stanu - zielona obwódka dla poprawnych, czerwona dla błędnych pól
- 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:
- Struktura błędów - specjalny format z błędami dla pól i ogólnym błędem formularza
- useActionState i useFormStatus - hooki do śledzenia stanu formularza i procesu wysyłki
- Focus po sukcesie - przesunięcie fokusu do komunikatu sukcesu dla użytkowników czytników ekranu
- Struktura danych zwrotnych - spójny format odpowiedzi z serwera
- 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
Grupuj powiązane błędy - błędy dotyczące całego formularza umieszczaj na górze, błędy konkretnych pól - przy polach
Zachowaj spójność wizualną - używaj tych samych kolorów, ikon i styli dla błędów w całej aplikacji
Doskonal komunikaty - zamiast "Nieprawidłowe dane" napisz dokładnie, co jest nie tak i jak to naprawić
Zachowaj dane przy błędach - nie resetuj całego formularza po wystąpieniu błędu
Priorytetyzuj błędy - najpierw pokaż krytyczne błędy, potem mniej istotne
Automatycznie przewijaj do błędów - szczególnie w długich formularzach, automatycznie przewijaj do pierwszego błędu
Wykorzystuj ARIA - używaj atrybutów
aria-invalid,aria-describedbyi role="alert" dla dostępnościOznaczaj wymagane pola - jasno oznacz, które pola są wymagane, najlepiej przed wypełnianiem formularza
Podawaj przykłady - dla skomplikowanych formatów (np. data, numer telefonu) podawaj przykłady
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:
Używaj atrybutów ARIA
aria-invalid="true"dla niepoprawnych pólaria-describedbyłączący pole z komunikatem błędurole="alert"dla komunikatów błędów, które powinny być natychmiast odczytane
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
Używaj
<fieldset>i<legend>- Grupuj powiązane pola za pomocą
<fieldset> - Opisuj grupy pól za pomocą
<legend>
- Grupuj powiązane pola za pomocą
Prawidłowa kolejność tabulacji
- Upewnij się, że użytkownicy klawiatury mogą poruszać się między polami w logicznej kolejności
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:
- Projektowanie przyjaznych komunikatów - jasne, konkretne i pomocne
- Walidację na wielu poziomach - klient + serwer, poszczególne pola + cały formularz
- Odpowiedni timing - wybieranie optymalnego momentu na pokaźnie błędów
- Dostępność - zapewnienie, że wszyscy użytkownicy mogą zrozumieć i poprawić błędy
- 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>⚠</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