React - useActionState、useFormStatus与表单处理

参考文档：react@18.3.1官方文档

一些概念：
React 的 Canary 和 Experimental 频道是 React 团队用于发布和测试新功能的渠道。

useActionState

useActionState 是一个可以根据某个表单动作的结果更新 state 的 Hook。

const [state, formAction, isPending] = useActionState(fn, initialState, permalink?);

参数

• fn：当按钮被按下或者表单被提交时触发的函数。当函数被调用时，该函数会接收到表单的上一个 state（初始值为传入的 initialState 参数，否则为上一次执行完该函数的结果）作为函数的第一个参数，余下参数为普通表单动作接到的参数。
• initialState ：state 的初始值。任何可序列化的值都可接收。当 action 被调用一次后该参数会被忽略。
• 可选的permalink ：通常是一个布尔值或字符串，用于指示是否将当前的状态与 URL 进行关联。如果 permalink 为 true，useActionState 可能会将状态信息保存到 URL 中，允许用户在刷新页面或分享链接时保留当前的表单状态。

返回

• state：当前的 state。第一次渲染期间，该值为传入的 initialState 参数值。在 action 被调用后该值会变为 action 的返回值。
• formAction：通常是一个函数，用于处理表单的提交或其他动作。它封装了提交表单所需的逻辑，可以通过调用这个函数来触发与服务器的交互或状态更新。调用 formAction 后，useActionState 会根据 fn 的执行结果更新 state 和 isPending，从而反映最新的状态。
• isPending：指示当前的操作（通常是表单提交或其他异步操作）是否正在进行中

用法
假设我们要实现这样一个功能：

点击Submit，如果First Name值为空，提示：Name is required，如果不为空，提示：User save来模拟表单提交。
如果使用useState来实现

如果使用useActionState来实现

"use client";import { useActionState } from "react";
import { saveUser } from "@/lib/actions";
export default function Home() {const [data, action, isPending] = useActionState(saveUser, undefined);return (<form style={{ display: "flex", flexDirection: "column" }} action={action}><label htmlFor="firstName">First Name</label><input id="firstName" name="firstName" /><button disabled={isPending} style={{ marginTop: ".5rem" }}>{" "}Submit</button>{data?.error && <span style={{ color: "red" }}>{data?.error}</span>}{data?.message && <span style={{ color: "green" }}>{data?.message}</span>}</form>);
}

"use server";
export async function saveUser(previousState: unknown, formData: FormData) {// Do some fetch request to save user to databaseconst firstName = formData.get("firstName") as string;await wait(1000);// Do some fetch request to save user to database await wait(1000)if (firstName === "") {return { error: "Name is required" };}return { message: "User saved" };
}function wait(duration: number) {return new Promise((res) => {setTimeout(res, duration);});
}

useActionState 返回一个包含以下值的数组：

1. 该表单的 当前 state，初始值为提供的 初始 state，当表单被提交后则改为传入的 action 的返回值。
2. 传入 <form> 标签的 action 属性的 新 action。
3. 一个 pending state，可以在处理 action 的过程中使用它。

表单被提交后，传入的 action 函数会被执行。返回值将会作为该表单的新的 当前 state。

传入的 action 接受到的第一个参数将会变为该表单的 当前 state。当表单第一次被提交时将会传入提供的 初始 state，之后都将传入上一次调用 action 函数的返回值。余下参数与未使用 useActionState 前接受的参数别无二致。

注意
useActionState Hook 当前仅在 React Canary 与 experimental 渠道中可用。此外，需要一款完全支持 React 服务器组件 特性的框架才可以使用 useActionState 的所有特性。

在早期的 React Canary 版本中，这个 API 是 React DOM 的一部分，称为 useFormState。

• 在支持 React 服务器组件的框架中使用该功能时，useActionState 允许表单在服务器渲染阶段时获得部分交互性。当不使用服务器组件时，它的特性与本地 state 相同。

• 与直接通过表单动作调用的函数不同，传入 useActionState 的函数被调用时，会多传入一个代表 state 的上一个值或初始值的参数作为该函数的第一个参数。

useFormStatus

useFormStatus 是一个提供上次表单提交状态信息的 Hook。

const { pending, data, method, action } = useFormStatus();

参数
useFormStatus 不接收任何参数
返回
useFormStatus 返回一个包含以下属性的 status 对象：

• pending：布尔值。如果为 true，则表示父级<form>正在等待提交；否则为 false。
• data：实现了 FormData interface 的对象，包含父级<form>正在提交的数据；如果没有进行提交或没有父级 <form>，它将为 null。
• method：字符串，可以是 ‘get’ 或 ‘post’。表示父级 <form> 使用 GET 或 POST HTTP 方法 进行提交。默认情况下，<form> 将使用 GET 方法，并可以通过 method 属性指定。
• action：一个传递给父级 <form> 的 action 属性的函数引用。如果没有父级 <form>，则该属性为 null。如果在 action 属性上提供了 URI 值，或者未指定 action 属性，status.action 将为 null。

用法

示例：使用从 useFormStatus 返回的状态信息中的 data 属性来显示用户正在提交的数据是什么。
UsernameForm.js:

import {useState, useMemo, useRef} from 'react';
import {useFormStatus} from 'react-dom';export default function UsernameForm() {const {pending, data} = useFormStatus();return (<div><h3>请求用户名：</h3><input type="text" name="username" disabled={pending}/><button type="submit" disabled={pending}>提交  </button><br /><p>{data ? `请求 ${data?.get("username")}...`: ''}</p></div>);
}

App.js

import UsernameForm from './UsernameForm';
import { submitForm } from "./actions.js";
import {useRef} from 'react';export default function App() {const ref = useRef(null);return (<form ref={ref} action={async (formData) => {await submitForm(formData);ref.current.reset();}}><UsernameForm /></form>);
}

actions.js

export async function submitForm(query) {await new Promise((res) => setTimeout(res, 2000));
}

注意

• useFormStatus Hook 必须从在 内渲染的组件中调用。
• useFormStatus 仅会返回父级 的状态信息。它不会返回同一组件或子组件中渲染的任何 的状态信息。

总结

useActionState钩子旨在无缝处理服务器操作。当您将服务器操作传递给 useActionState 时，它将返回一个包含错误（或状态）、isPending 状态和操作本身的对象。此设置对于管理表单提交和在返回结果之前跟踪加载状态特别有用。

useFormStatus钩子旨在让您深入了解表单的当前状态，例如了解表单是否处于 “submitting” 状态。这对于显示 UI 元素（如加载指示器）或阻止多个表单提交（直到当前提交完成）特别有用