React useFormStatus: вичерпний посібник з керування станом форм

Хук useFormStatus, представлений у React 18, надає потужний та ефективний спосіб керування станом відправки форм у серверних компонентах React. Цей хук спеціально розроблений для роботи з серверними діями (server actions), пропонуючи безшовну інтеграцію для обробки відправок форм безпосередньо на сервері. Він спрощує процес відстеження статусу відправки форми, надаючи цінну інформацію, таку як чи форма очікує на виконання, чи була успішно відправлена, чи виникла помилка. Цей посібник досліджує можливості useFormStatus, його переваги та практичні приклади, що демонструють його використання в різних сценаріях.

Розуміння серверних дій та useFormStatus

Перш ніж зануритися у useFormStatus, важливо зрозуміти серверні компоненти React та серверні дії. Серверні дії дозволяють визначати функції, які виконуються на сервері та є безпосередньо доступними з ваших компонентів React. Це дає змогу обробляти відправку форм, отримувати дані та виконувати інші серверні операції без необхідності створення окремої кінцевої точки API.

Хук useFormStatus надає інформацію про виконання цих серверних дій, викликаних відправкою форми.

Що таке useFormStatus?

useFormStatus — це хук React, який повертає об'єкт, що містить інформацію про статус останньої відправки форми. Ця інформація включає:

• pending: логічне значення, що вказує, чи форма зараз відправляється.
• data: об'єкт FormData, пов'язаний з відправкою.
• method: HTTP-метод, використаний для відправки (зазвичай 'POST').
• action: функція серверної дії, яка була викликана.

Переваги використання useFormStatus

Використання useFormStatus пропонує кілька ключових переваг:

• Спрощене керування станом: Усуває необхідність ручного керування станом для відстеження статусу відправки форми. Хук автоматично оновлюється в процесі відправки.
• Покращений користувацький досвід: Надає користувачам зворотний зв'язок у реальному часі, наприклад, відображення індикаторів завантаження під час обробки форми або показ повідомлень про помилки в разі невдачі.
• Чистий код: Сприяє більш декларативній та підтримуваній кодовій базі, відокремлюючи логіку відправки форми від рендерингу компонента.
• Безшовна інтеграція з серверними діями: Розроблений для ідеальної роботи з серверними діями, що полегшує обробку відправок форм безпосередньо на сервері.

Практичні приклади використання useFormStatus

Розглянемо кілька практичних прикладів для ілюстрації використання useFormStatus у різних сценаріях.

Базова відправка форми з індикатором завантаження

Цей приклад демонструє просту форму з індикатором завантаження, який відображається під час відправки форми.

Серверна дія (actions.js):

'use server'

export async function submitForm(formData) {
  // Симулюємо затримку для демонстрації стану завантаження
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Форму відправлено з іменем:', name);
  return { message: `Форму успішно відправлено з іменем: ${name}` };
}

Компонент React (FormComponent.jsx):

'use client'

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

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

  return (
    

      Ім'я:
      
      
        {pending ? 'Відправка...' : 'Відправити'}
      
    
  )
}

export default FormComponent

У цьому прикладі властивість pending з useFormStatus використовується для вимкнення поля вводу та кнопки під час відправки форми, а також для відображення повідомлення "Відправка...".

Обробка станів успіху та помилки

Цей приклад демонструє, як обробляти стани успіху та помилки після відправки форми.

Серверна дія (actions.js):

'use server'

export async function submitForm(formData) {
  // Симулюємо затримку
  await new Promise(resolve => setTimeout(resolve, 2000));

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

  if (!name) {
    throw new Error('Ім\'я є обов\'язковим');
  }

  console.log('Форму відправлено з іменем:', name);
  return { message: `Форму успішно відправлено з іменем: ${name}` };
}

Компонент React (FormComponent.jsx):

'use client'

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

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

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

  return (
    

      Ім'я:
      
      
        {pending ? 'Відправка...' : 'Відправити'}
      
      {pending && 
Відправка...
}
      {message && 
{message}
}
      {error && 
Помилка: {error}
}
    
  )
}

export default FormComponent

У цьому прикладі використовується блок try/catch у функції handleSubmit. Якщо серверна дія генерує помилку, вона перехоплюється та відображається користувачеві. Повідомлення про успіх відображається після успішної відправки.

Використання FormData для складних даних

useFormStatus безшовно працює з FormData, дозволяючи легко обробляти складні структури даних. Ось приклад, що демонструє завантаження файлів.

Серверна дія (actions.js):

'use server'

export async function uploadFile(formData) {
  // Симулюємо обробку файлу
  await new Promise(resolve => setTimeout(resolve, 2000));

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

  if (!file) {
    throw new Error('Файл не завантажено');
  }

  console.log('Файл завантажено:', file.name);
  return { message: `Файл успішно завантажено: ${file.name}` };
}

Компонент React (FormComponent.jsx):

'use client'

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

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

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

  return (
    

      Завантажити файл:
      
      
        {pending ? 'Завантаження...' : 'Завантажити'}
      
      {pending && 
Завантаження...
}
      {message && 
{message}
}
      {error && 
Помилка: {error}
}
    
  )
}

export default FormComponent

Цей приклад демонструє, як обробляти завантаження файлів за допомогою FormData. Серверна дія отримує файл з об'єкта FormData та обробляє його. Хук useFormStatus керує станом завантаження під час передачі файлу.

Найкращі практики використання useFormStatus

Щоб максимізувати переваги useFormStatus, дотримуйтесь цих найкращих практик:

• Надавайте чіткий зворотний зв'язок користувачеві: Використовуйте стан pending для відображення інформативних індикаторів завантаження та вимикайте елементи форми, щоб запобігти повторним відправкам.
• Витончено обробляйте помилки: Реалізуйте обробку помилок для перехоплення винятків у ваших серверних діях та відображення дружніх до користувача повідомлень про помилки.
• Валідуйте дані на сервері: Виконуйте валідацію на стороні сервера для забезпечення цілісності та безпеки даних.
• Зберігайте серверні дії лаконічними: Фокусуйте серверні дії на конкретних завданнях для покращення продуктивності та підтримуваності.
• Враховуйте доступність: Переконайтеся, що ваші форми доступні, надаючи правильні мітки, атрибути ARIA та підтримку навігації з клавіатури.

Розширені випадки використання

Окрім базових прикладів, useFormStatus можна використовувати у складніших сценаріях:

• Прогресивне покращення: Використовуйте серверні дії та useFormStatus для прогресивного покращення ваших форм, надаючи базовий досвід для користувачів з вимкненим JavaScript та багатший досвід для тих, у кого він увімкнений.
• Оптимістичні оновлення: Реалізуйте оптимістичні оновлення, оновлюючи інтерфейс користувача одразу після відправки форми, припускаючи, що відправка буде успішною. Поверніть оновлення, якщо відправка не вдалася.
• Інтеграція з бібліотеками форм: Інтегруйте useFormStatus з популярними бібліотеками форм, такими як Formik або React Hook Form, для керування станом та валідацією форми. Хоча ці бібліотеки часто мають власне керування станом, useFormStatus може бути корисним для фінального етапу відправки до серверної дії.

Рекомендації щодо інтернаціоналізації (i18n)

При створенні форм для глобальної аудиторії інтернаціоналізація (i18n) є надзвичайно важливою. Ось як враховувати i18n при використанні useFormStatus:

• Локалізовані повідомлення про помилки: Переконайтеся, що повідомлення про помилки, які відображаються користувачеві, локалізовані відповідно до його мови. Це можна досягти, зберігаючи повідомлення про помилки у файлах перекладу та використовуючи бібліотеку, таку як react-intl або i18next, для отримання відповідного перекладу.
• Форматування дат і чисел: Обробляйте форматування дат і чисел відповідно до локалі користувача. Використовуйте бібліотеки, такі як Intl.DateTimeFormat та Intl.NumberFormat, для правильного форматування цих значень.
• Підтримка справа наліво (RTL): Якщо ваша програма підтримує мови, що пишуться справа наліво (наприклад, арабська, іврит), переконайтеся, що ваші форми правильно стилізовані для розмітки RTL.
• Валідація форм: Адаптуйте правила валідації форм до різних локалей. Наприклад, валідація телефонного номера може значно відрізнятися в різних країнах.

Приклад локалізованих повідомлень про помилки:

// translations/uk.json
{
  "form.error.nameRequired": "Будь ласка, введіть ваше ім'я.",
  "form.success.submission": "Дякуємо за вашу заявку!"
}

// translations/fr.json
{
  "form.error.nameRequired": "Будь ласка, введіть ваше ім'я.",
  "form.success.submission": "Дякуємо за вашу заявку!"
}

// Компонент, що використовує react-intl
import { useIntl } from 'react-intl';

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

  // ...

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

Рекомендації щодо доступності

Доступність є ключовим аспектом створення інклюзивних веб-додатків. Ось кілька рекомендацій щодо доступності, які слід враховувати при використанні useFormStatus:

• Атрибути ARIA: Використовуйте атрибути ARIA для надання допоміжним технологіям інформації про статус форми. Наприклад, використовуйте aria-busy="true" на кнопці відправки, поки форма очікує на виконання.
• Мітки: Переконайтеся, що всі поля форми мають чіткі та описові мітки, пов'язані з елементами вводу за допомогою елемента <label>.
• Повідомлення про помилки: Відображайте повідомлення про помилки так, щоб їх було легко помітити та зрозуміти користувачам з обмеженими можливостями. Використовуйте атрибути ARIA, такі як aria-live="assertive", для оголошення повідомлень про помилки екранними читачами.
• Навігація з клавіатури: Переконайтеся, що користувачі можуть переміщатися по формі, використовуючи лише клавіатуру. Використовуйте атрибут tabindex для керування порядком отримання фокусу елементами.
• Контраст кольорів: Переконайтеся, що кольори тексту та фону, які використовуються у формі, мають достатній контраст, щоб їх було легко читати користувачам з вадами зору.

useFormStatus у порівнянні з традиційним керуванням станом

Традиційно розробники React керували станом відправки форми за допомогою стану компонента (useState) або складніших бібліотек керування станом (наприклад, Redux, Zustand). Ось порівняння цих підходів з useFormStatus:

Характеристика	useFormStatus	useState	Зовнішнє керування станом
Складність	Низька	Середня	Висока
Інтеграція з серверними діями	Безшовна	Потребує ручної інтеграції	Потребує ручної інтеграції
Шаблонний код	Мінімальний	Помірний	Значний
Відповідні випадки використання	Форми, що відправляються безпосередньо до серверних дій	Прості форми з обмеженим станом	Складні форми зі спільним станом між компонентами

useFormStatus виявляється найкращим, коли ваші форми взаємодіють безпосередньо з серверними діями React. Він зменшує кількість шаблонного коду та спрощує процес. Однак для дуже складних форм зі станом, що спільно використовується кількома компонентами, повноцінна бібліотека керування станом все ще може бути виправданою.

Вирішення поширених проблем

Ось деякі поширені проблеми, з якими ви можете зіткнутися при використанні useFormStatus, та способи їх вирішення:

• useFormStatus не оновлюється:
  • Переконайтеся, що ви використовуєте useFormStatus всередині елемента <form>, у якого властивість action встановлена на серверну дію.
  • Перевірте, що серверна дія правильно визначена та експортована.
  • Перевірте наявність будь-яких помилок у серверній дії, які можуть перешкоджати її успішному завершенню.
• Повідомлення про помилки не відображаються:
  • Переконайтеся, що ви правильно перехоплюєте помилки у вашій серверній дії та повертаєте повідомлення про помилку.
  • Перевірте, що ви відображаєте повідомлення про помилку у вашому компоненті за допомогою стану error.
• Індикатор завантаження не з'являється:
  • Переконайтеся, що ви використовуєте стан pending з useFormStatus для умовного відображення індикатора завантаження.
  • Перевірте, що серверна дія дійсно займає деякий час для виконання (наприклад, симулюючи затримку).

Висновок

useFormStatus надає чистий та ефективний спосіб керування станом відправки форми в додатках React, що використовують серверні компоненти. Використовуючи цей хук, ви можете спростити свій код, покращити користувацький досвід та безшовно інтегруватися з серверними діями. Цей посібник охопив основи useFormStatus, надав практичні приклади та обговорив найкращі практики для його ефективного використання. Включаючи useFormStatus у ваші проекти на React, ви можете оптимізувати обробку форм та створювати більш надійні та дружні до користувача додатки для глобальної аудиторії.