React - useActionState、useFormStatus与表单处理

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

一些概念：

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

useActionState

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

typescript 复制代码

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来实现

typescript 复制代码

"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>
  );
}

typescript 复制代码

"use server";
export async function saveUser(previousState: unknown, formData: FormData) {
  // Do some fetch request to save user to database
  const 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 返回一个包含以下值的数组：

该表单的当前 state，初始值为提供的初始 state，当表单被提交后则改为传入的 action 的返回值。
传入 <form> 标签的 action 属性的新 action。
一个 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。

typescript 复制代码

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:

typescript 复制代码

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

typescript 复制代码

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

typescript 复制代码

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

注意

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

总结

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

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