useFormState

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

• 参考
  • useFormState(action, initialState, permalink?)
• 用法
  • 使用表单操作返回的信息
• 故障排除
  • 我的操作无法再读取提交的表单数据

参考

¥Reference

useFormState(action, initialState, permalink?)

在组件的顶层调用 useFormState 以创建更新 当调用表单操作时 的组件状态。你向 useFormState 传递一个现有的表单操作函数以及一个初始状态，它会返回你在表单中使用的新操作以及最新的表单状态。最新的表单状态也会传递给你提供的函数。

¥Call useFormState at the top level of your component to create component state that is updated when a form action is invoked. You pass useFormState an existing form action function as well as an initial state, and it returns a new action that you use in your form, along with the latest form state. The latest form state is also passed to the function that you provided.

import { useFormState } from "react-dom";

async function increment(previousState, formData) {
  return previousState + 1;
}

function StatefulForm({}) {
  const [state, formAction] = useFormState(increment, 0);
  return (
    <form>
      {state}
      <button formAction={formAction}>Increment</button>
    </form>
  )
}

表单状态是上次提交表单时操作返回的值。如果表单尚未提交，则为你通过的初始状态。

¥The form state is the value returned by the action when the form was last submitted. If the form has not yet been submitted, it is the initial state that you pass.

如果与服务器操作一起使用，useFormState 甚至允许在 Hydration 完成之前显示服务器提交表单的响应。

¥If used with a Server Action, useFormState allows the server’s response from submitting the form to be shown even before hydration has completed.

请参阅下面的更多示例。

¥See more examples below.

参数

¥Parameters

• fn：提交表单或按下按钮时要调用的函数。调用该函数时，它将接收表单的先前状态（最初是你传递的 initialState，随后是其先前的返回值）作为其初始参数，后面是表单操作通常接收的参数。

  ¥fn: The function to be called when the form is submitted or button pressed. When the function is called, it will receive the previous state of the form (initially the initialState that you pass, subsequently its previous return value) as its initial argument, followed by the arguments that a form action normally receives.

• initialState：你希望状态的初始值。它可以是任何可序列化的值。首次调用操作后，该参数将被忽略。

  ¥initialState: The value you want the state to be initially. It can be any serializable value. This argument is ignored after the action is first invoked.

• 可选 permalink：包含此表单修改的唯一页面 URL 的字符串。用于具有动态内容（例如：提要）的页面以及渐进增强：如果 fn 是 服务器动作 并且表单在 JavaScript 包加载之前提交，浏览器将导航到指定的永久链接 URL，而不是当前页面的 URL。确保在目标页面上渲染相同的表单组件（包括相同的操作 fn 和 permalink），以便 React 知道如何传递状态。一旦形态被水合，该参数就不再起作用。

  ¥optional permalink: A string containing the unique page URL that this form modifies. For use on pages with dynamic content (eg: feeds) in conjunction with progressive enhancement: if fn is a server action and the form is submitted before the JavaScript bundle loads, the browser will navigate to the specified permalink URL, rather than the current page’s URL. Ensure that the same form component is rendered on the destination page (including the same action fn and permalink) so that React knows how to pass the state through. Once the form has been hydrated, this parameter has no effect.

返回

¥Returns

useFormState 返回一个恰好包含两个值的数组：

¥useFormState returns an array with exactly two values:

1. 当前状态。在第一次渲染期间，它将与你传递的 initialState 相匹配。调用操作后，它将匹配操作返回的值。

   ¥The current state. During the first render, it will match the initialState you have passed. After the action is invoked, it will match the value returned by the action.

2. 一个新操作，你可以将其作为 action 属性传递给 form 组件，或者将 formAction 属性传递给表单中的任何 button 组件。

   ¥A new action that you can pass as the action prop to your form component or formAction prop to any button component within the form.

注意事项

¥Caveats

• 当与支持 React 服务器组件的框架一起使用时，useFormState 允许你在 JavaScript 在客户端上执行之前使表单交互。当不使用服务器组件时，它相当于组件本地状态。

  ¥When used with a framework that supports React Server Components, useFormState lets you make forms interactive before JavaScript has executed on the client. When used without Server Components, it is equivalent to component local state.

• 传递给 useFormState 的函数接收一个额外的参数，即先前或初始状态，作为其第一个参数。这使得它的签名与不使用 useFormState 直接用作表单操作的签名不同。

  ¥The function passed to useFormState receives an extra argument, the previous or initial state, as its first argument. This makes its signature different than if it were used directly as a form action without using useFormState.

用法

¥Usage

使用表单操作返回的信息

¥Using information returned by a form action

在组件的顶层调用 useFormState 以访问上次提交表单时操作的返回值。

¥Call useFormState at the top level of your component to access the return value of an action from the last time a form was submitted.

import { useFormState } from 'react-dom';
import { action } from './actions.js';

function MyComponent() {
  const [state, formAction] = useFormState(action, null);
  // ...
  return (
    <form action={formAction}>
      {/* ... */}
    </form>
  );
}

useFormState 返回一个恰好包含两项的数组：

¥useFormState returns an array with exactly two items:

1. 表单的当前状态，初始设置为你提供的初始状态，表单提交后设置为返回值 你提供的action。

   ¥The current state of the form, which is initially set to the initial state you provided, and after the form is submitted is set to the return value of the action you provided.

2. 一个新操作，你将其传递给 <form> 作为其 action 属性。

   ¥A new action that you pass to <form> as its action prop.

提交表单后，你提供的 action 函数将被调用。它的返回值将成为表单的新当前状态。

¥When the form is submitted, the action function that you provided will be called. Its return value will become the new current state of the form.

你提供的 action 还将收到一个新的第一个参数，即表单的 当前状态。第一次提交表单时，这将是你提供的初始状态，而在后续提交中，这将是上次调用操作时的返回值。其余参数与未使用 useFormState 时相同。

¥The action that you provide will also receive a new first argument, namely the current state of the form. The first time the form is submitted, this will be the initial state you provided, while with subsequent submissions, it will be the return value from the last time the action was called. The rest of the arguments are the same as if useFormState had not been used.

function action(currentState, formData) {
  // ...
  return 'next state';
}

故障排除

¥Troubleshooting

我的操作无法再读取提交的表单数据

¥My action can no longer read the submitted form data

当你使用 useFormState 封装一个操作时，它会获得一个额外的参数作为其第一个参数。因此，提交的表单数据是其第二个参数，而不是通常的第一个参数。添加的新的第一个参数是表单的当前状态。

¥When you wrap an action with useFormState, it gets an extra argument as its first argument. The submitted form data is therefore its second argument instead of its first as it would usually be. The new first argument that gets added is the current state of the form.

function action(currentState, formData) {
  // ...
}