React useActionState: Полное руководство по современному управлению формами

Мир веб-разработки постоянно развивается, и экосистема React находится в авангарде этих изменений. В последних версиях React представил мощные функции, которые кардинально улучшают способы создания интерактивных и устойчивых приложений. Среди наиболее значимых из них — хук useActionState, который меняет правила игры в обработке форм и асинхронных операций. Этот хук, ранее известный как useFormState в экспериментальных версиях, теперь является стабильным и незаменимым инструментом для любого современного React-разработчика.

Это подробное руководство погрузит вас в мир useActionState. Мы рассмотрим проблемы, которые он решает, его основные механики и способы использования в сочетании с дополнительными хуками, такими как useFormStatus, для создания превосходного пользовательского опыта. Независимо от того, создаете ли вы простую контактную форму или сложное, насыщенное данными приложение, понимание useActionState сделает ваш код чище, декларативнее и надежнее.

Проблема: сложность традиционного управления состоянием формы

Прежде чем мы сможем оценить элегантность useActionState, мы должны понять проблемы, которые он решает. В течение многих лет управление состоянием формы в React включало предсказуемый, но часто громоздкий паттерн с использованием хука useState.

Рассмотрим распространенный сценарий: простая форма для добавления нового продукта в список. Нам нужно управлять несколькими частями состояния:

Значение ввода для названия продукта.
Состояние загрузки или ожидания для обратной связи с пользователем во время вызова API.
Состояние ошибки для отображения сообщений в случае сбоя отправки.
Состояние успеха или сообщение по завершении.

Типичная реализация может выглядеть примерно так:

Пример: «Старый способ» с несколькими хуками useState

// Вымышленная функция API
const addProductAPI = async (productName) => {
await new Promise(resolve => setTimeout(resolve, 1500));
if (!productName || productName.length < 3) {
throw new Error('Product name must be at least 3 characters long.');
}
console.log(`Product "${productName}" added.`);
return { success: true };
};

// Компонент
import { useState } from 'react';

function OldProductForm() {
const [productName, setProductName] = useState('');
const [error, setError] = useState(null);
const [isPending, setIsPending] = useState(false);

const handleSubmit = async (event) => {
event.preventDefault();
setIsPending(true);
setError(null);

try {
await addProductAPI(productName);
setProductName(''); // Очищаем поле ввода при успехе
} catch (err) {
setError(err.message);
} finally {
setIsPending(false);
}
};

return (

Product Name:

      

        id="productName"

        name="productName"

        value={productName}

        onChange={(e) => setProductName(e.target.value)}

      />

      

      {error && {error}
}

    

  );

}


Этот подход работает, но у него есть несколько недостатков:

  Шаблонный код: Нам нужно три отдельных вызова useState для управления тем, что по сути является единым процессом отправки формы.
  Ручное управление состоянием: Разработчик несет ответственность за ручную установку и сброс состояний загрузки и ошибки в правильном порядке внутри блока try...catch...finally. Это повторяющаяся и подверженная ошибкам задача.
  Сильная связанность: Логика обработки результата отправки формы тесно связана с логикой рендеринга компонента.


Представляем useActionState: смена парадигмы

useActionState — это хук React, специально разработанный для управления состоянием асинхронного действия, такого как отправка формы. Он оптимизирует весь процесс, связывая состояние напрямую с результатом функции-действия.

Его сигнатура ясна и лаконична:
const [state, formAction] = useActionState(actionFn, initialState);

Давайте разберем его компоненты:

  actionFn(previousState, formData): Это ваша асинхронная функция, которая выполняет работу (например, вызывает API). Она получает предыдущее состояние и данные формы в качестве аргументов. Важно то, что все, что эта функция возвращает, становится новым состоянием.
  initialState: Это значение состояния до первого выполнения действия.
  state: Это текущее состояние. Изначально оно содержит initialState и обновляется до возвращаемого значения вашей actionFn после каждого выполнения.
  formAction: Это новая, обернутая версия вашей функции-действия. Вы должны передать эту функцию в проп action элемента <form>. React использует эту обернутую функцию для отслеживания состояния ожидания действия.


Практический пример: рефакторинг с useActionState

Теперь давайте проведем рефакторинг нашей формы продукта с использованием useActionState. Улучшение становится очевидным сразу.

Сначала нам нужно адаптировать логику нашего действия. Вместо выбрасывания ошибок, действие должно возвращать объект состояния, описывающий результат.

Пример: «Новый способ» с useActionState

// Функция-действие, разработанная для работы с useActionState

const addProductAction = async (previousState, formData) => {

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

  await new Promise(resolve => setTimeout(resolve, 1500)); // Имитация сетевой задержки



  if (!productName || productName.length < 3) {

    return { message: 'Product name must be at least 3 characters long.', success: false };

  }



  console.log(`Product "${productName}" added.`);

  // При успехе возвращаем сообщение об успехе и очищаем форму.

  return { message: `Successfully added "${productName}"`, success: true };

};


// Компонент после рефакторинга

import { useActionState } from 'react';

// Примечание: Мы добавим useFormStatus в следующем разделе для обработки состояния ожидания.



function NewProductForm() {

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

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



  return (

    


      Product Name:

      

      

      {!state.success && state.message && (

        {state.message}

      )}

      {state.success && state.message && (

        {state.message}

      )}

    

  );

}


Посмотрите, насколько чище это стало! Мы заменили три хука useState одним хуком useActionState. Ответственность компонента теперь сводится исключительно к рендерингу интерфейса на основе объекта `state`. Вся бизнес-логика аккуратно инкапсулирована в функции `addProductAction`. Состояние обновляется автоматически на основе того, что возвращает действие.

Но подождите, а как насчет состояния ожидания? Как нам отключить кнопку во время отправки формы?

Обработка состояний ожидания с помощью useFormStatus

React предоставляет сопутствующий хук, useFormStatus, разработанный для решения именно этой проблемы. Он предоставляет информацию о статусе последней отправки формы, но с одним важным правилом: он должен вызываться из компонента, который рендерится внутри <form>, статус которой вы хотите отслеживать.

Это способствует четкому разделению ответственности. Вы создаете компонент специально для элементов интерфейса, которым необходимо знать о статусе отправки формы, например, для кнопки отправки.

Хук useFormStatus возвращает объект с несколькими свойствами, наиболее важным из которых является `pending`.
const { pending, data, method, action } = useFormStatus();

  pending: Булево значение, которое равно `true`, если родительская форма в данный момент отправляется, и `false` в противном случае.
  data: Объект `FormData`, содержащий отправляемые данные.
  method: Строка, указывающая HTTP-метод (`'get'` или `'post'`).
  action: Ссылка на функцию, переданную в проп `action` формы.


Создание кнопки отправки, знающей о статусе

Давайте создадим специальный компонент `SubmitButton` и интегрируем его в нашу форму.

Пример: компонент SubmitButton
import { useFormStatus } from 'react-dom';

// Примечание: useFormStatus импортируется из 'react-dom', а не из 'react'.



function SubmitButton() {

  const { pending } = useFormStatus();



  return (

    

  );

}


Теперь мы можем обновить наш основной компонент формы, чтобы использовать его.

Пример: полная форма с useActionState и useFormStatus
import { useActionState } from 'react';

import { useFormStatus } from 'react-dom';



// ... (функция addProductAction остается прежней)



function SubmitButton() { /* ... как определено выше ... */ }



function CompleteProductForm() {

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

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



  return (

    


      Product Name:

      {/* Мы можем добавить ключ для сброса поля ввода при успехе */}

      

      

      {!state.success && state.message && (

        {state.message}

      )}

      {state.success && state.message && (

        {state.message}

      )}

    

  );

}


С такой структурой компоненту `CompleteProductForm` не нужно ничего знать о состоянии ожидания. Компонент `SubmitButton` полностью автономен. Этот композиционный паттерн невероятно мощен для создания сложных, поддерживаемых интерфейсов.

Сила прогрессивного улучшения

Одним из самых глубоких преимуществ этого нового подхода, основанного на действиях, особенно при использовании с Server Actions, является автоматическое прогрессивное улучшение. Это жизненно важная концепция для создания приложений для глобальной аудитории, где сетевые условия могут быть ненадежными, а пользователи могут иметь старые устройства или отключенный JavaScript.

Вот как это работает:

  Без JavaScript: Если браузер пользователя не выполняет клиентский JavaScript, `<form action={...}>` работает как стандартная HTML-форма. Он отправляет запрос на сервер с полной перезагрузкой страницы. Если вы используете фреймворк, такой как Next.js, серверное действие выполняется, и фреймворк перерисовывает всю страницу с новым состоянием (например, показывая ошибку валидации). Приложение полностью функционально, просто без гладкости, присущей SPA.
  С JavaScript: Как только JavaScript-бандл загружается и React гидрирует страницу, тот же `formAction` выполняется на стороне клиента. Вместо полной перезагрузки страницы он ведет себя как обычный fetch-запрос. Действие вызывается, состояние обновляется, и перерисовываются только необходимые части компонента.


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

Продвинутые паттерны и сценарии использования

1. Серверные действия vs. Клиентские действия
Функция `actionFn`, которую вы передаете в useActionState, может быть стандартной клиентской асинхронной функцией (как в наших примерах) или серверным действием (Server Action). Server Action — это функция, определенная на сервере, которую можно вызывать напрямую из клиентских компонентов. Во фреймворках, таких как Next.js, вы определяете ее, добавляя директиву "use server"; в начало тела функции.


  Клиентские действия: Идеальны для мутаций, которые затрагивают только состояние на стороне клиента или вызывают сторонние API напрямую с клиента.
  Серверные действия: Идеальны для мутаций, затрагивающих базу данных или другие серверные ресурсы. Они упрощают вашу архитектуру, устраняя необходимость вручную создавать конечные точки API для каждой мутации.


Прелесть в том, что useActionState работает одинаково с обоими типами действий. Вы можете заменить клиентское действие на серверное, не меняя код компонента.

2. Оптимистичные обновления с `useOptimistic`
Для еще большей отзывчивости вы можете комбинировать useActionState с хуком useOptimistic. Оптимистичное обновление — это когда вы обновляете интерфейс немедленно, *предполагая*, что асинхронное действие будет успешным. Если оно завершается неудачей, вы возвращаете интерфейс к предыдущему состоянию.

Представьте себе приложение социальной сети, где вы добавляете комментарий. Оптимистично вы бы сразу же показали новый комментарий в списке, пока запрос отправляется на сервер. useOptimistic разработан для совместной работы с действиями, чтобы сделать этот паттерн простым в реализации.

3. Сброс формы при успешной отправке
Частым требованием является очистка полей формы после успешной отправки. Есть несколько способов достичь этого с помощью useActionState.


  Трюк с пропом `key`: Как показано в нашем примере `CompleteProductForm`, вы можете присвоить уникальный `key` полю ввода или всей форме. Когда ключ меняется, React размонтирует старый компонент и смонтирует новый, эффективно сбрасывая его состояние. Привязка ключа к флагу успеха (`key={state.success ? 'success' : 'initial'}`) — простой и эффективный метод.
  Контролируемые компоненты: При необходимости вы все еще можете использовать контролируемые компоненты. Управляя значением поля ввода с помощью useState, вы можете вызвать функцию-сеттер для его очистки внутри useEffect, который отслеживает состояние успеха от useActionState.


Распространенные ошибки и лучшие практики


  Размещение useFormStatus: Помните, что компонент, вызывающий useFormStatus, должен быть отрендерен как дочерний элемент `<form>`. Он не будет работать, если является соседним элементом или родителем.
  Сериализуемое состояние: При использовании серверных действий объект состояния, возвращаемый вашим действием, должен быть сериализуемым. Это означает, что он не может содержать функции, символы или другие несериализуемые значения. Придерживайтесь простых объектов, массивов, строк, чисел и булевых значений.
  Не выбрасывайте ошибки в действиях: Вместо `throw new Error()` ваша функция-действие должна корректно обрабатывать ошибки и возвращать объект состояния, описывающий ошибку (например, `{ success: false, message: 'Произошла ошибка' }`). Это гарантирует, что состояние всегда обновляется предсказуемо.
  Определите четкую структуру состояния: С самого начала установите последовательную структуру для вашего объекта состояния. Структура вида `{ data: T | null, message: string | null, success: boolean, errors: Record | null }` может покрыть множество сценариев использования.


useActionState vs. useReducer: краткое сравнение

На первый взгляд, useActionState может показаться похожим на useReducer, поскольку оба включают обновление состояния на основе предыдущего. Однако они служат разным целям.


  useReducer — это хук общего назначения для управления сложными переходами состояния на клиентской стороне. Он запускается путем отправки (dispatching) действий и идеально подходит для логики состояний со множеством возможных синхронных изменений (например, сложный многошаговый мастер).
  useActionState — это специализированный хук, предназначенный для состояния, которое изменяется в ответ на одно, как правило, асинхронное действие. Его основная роль — интеграция с HTML-формами, серверными действиями и функциями конкурентного рендеринга React, такими как переходы состояния ожидания.


Вывод: для отправки форм и асинхронных операций, связанных с формами, useActionState — это современный, специально созданный инструмент. Для других сложных клиентских конечных автоматов useReducer остается отличным выбором.

Заключение: принимая будущее форм в React

Хук useActionState — это больше, чем просто новый API; он представляет собой фундаментальный сдвиг в сторону более надежного, декларативного и ориентированного на пользователя способа обработки форм и мутаций данных в React. Используя его, вы получаете:


  Сокращение шаблонного кода: Один хук заменяет несколько вызовов useState и ручную организацию состояния.
  Интегрированные состояния ожидания: Бесшовная обработка интерфейсов загрузки с помощью сопутствующего хука useFormStatus.
  Встроенное прогрессивное улучшение: Пишите код, который работает как с JavaScript, так и без него, обеспечивая доступность и отказоустойчивость для всех пользователей.
  Упрощенное взаимодействие с сервером: Естественная совместимость с серверными действиями, оптимизирующая опыт full-stack разработки.


Начиная новые проекты или проводя рефакторинг существующих, рассмотрите возможность использования useActionState. Это не только улучшит ваш опыт разработки, сделав код чище и предсказуемее, но и позволит вам создавать более качественные приложения, которые будут быстрее, отказоустойчивее и доступнее для разнообразной глобальной аудитории.