Действия форм: замена маршрутов API для мутаций

В традиционных приложениях Next.js отправка форм требует клиентского компонента с обработчиком onSubmit, который вызывает fetch() для отправки данных методом POST на маршрут API. Этот подход работает, но требует отдельно писать и поддерживать логику получения данных на клиенте и обработчик маршрута на сервере.

С серверными действиями Вы заменяете вызов функции получения данных и маршрут API одной функцией. Элемент формы получает серверное действие в качестве свойства action: <form action={serverAction}>. React перехватывает отправку и автоматически вызывает действие с данными формы.

При вызове из формы серверное действие автоматически получает объект FormData в качестве аргумента. Вы обращаетесь к отдельным полям с помощью formData.get('email'), который возвращает значение в виде строки. Доступны все стандартные методы FormData, включая getAll() для полей с множественным выбором.

Серверное действие может возвращать сериализуемое значение, которое использует клиент. Возврат объекта ошибки, например { error: 'Email already exists' }, или флага успешного выполнения, например { success: true }, позволяет клиенту соответствующим образом обновить интерфейс без полной перезагрузки страницы.

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

Форма с action={serverAction} работает даже при отключенном JavaScript. Браузер выполняет стандартную отправку формы HTML методом POST, сервер выполняет действие, а затем возвращает обновленную страницу. Благодаря этому настоящему прогрессивному улучшению форма корректно работает в любых средах.

После того как серверное действие изменяет данные, кэшированные данные страницы необходимо обновить. Вызов revalidatePath('/dashboard') внутри действия делает кэш Next.js для этого пути недействительным, поэтому при следующем запросе загружаются свежие данные. Это стандартный способ поддерживать актуальность страниц, отображаемых на сервере, после изменения данных.

revalidateTag('user-data') обеспечивает более точечную инвалидацию кэша, чем revalidatePath. Вы добавляете метки к вызовам получения данных с помощью next: { tags: ['user-data'] }, а затем из серверного действия одновременно делаете недействительными все данные с этой меткой, независимо от того, на каких путях они отображаются.

После успешного изменения данных серверные действия могут перенаправить пользователя на новую страницу с помощью вызова redirect('/success') из модуля next/navigation. Это перенаправление обрабатывается на сервере, поэтому браузер получает корректный ответ навигации, а не перенаправление на стороне клиента.

Серверные действия не ограничиваются отправкой форм. Для нажатий кнопок и других событий вне формы оберните вызов действия в startTransition(() => action(arg)). Это помечает навигацию как переход и позволяет React сохранять текущий интерфейс видимым, пока действие выполняется на сервере.

Серверные действия — подходящее место для проверки данных на сервере. Проверьте поля FormData, верните ошибки проверки, если они обнаружены, и продолжайте изменение данных только в том случае, если все поля корректны. Библиотеки вроде Zod хорошо подходят для этой задачи: преобразуйте FormData в типизированную схему и при ошибке верните карту ошибок.

Что получает серверное действие в качестве аргумента при вызове в результате отправки формы?

Серверные действия заменяют подход с запросом данных и маршрутом API при изменении данных через формы. Свойство формы action напрямую принимает серверное действие, которое получает объект FormData. Действия возвращают сериализуемые результаты для обновления интерфейса клиента, поддерживают revalidatePath и revalidateTag для инвалидации кэша и постепенно работают даже без JavaScript.