API 参考
钩子

useFormStatus

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

¥useFormStatus is a Hook that gives you status information of the last form submission.

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

参考

¥Reference

useFormStatus()

useFormStatus 钩子提供上次表单提交的状态信息。

¥The useFormStatus Hook provides status information of the last form submission.

import { useFormStatus } from "react-dom";
import action from './actions';

function Submit() {
  const status = useFormStatus();
  return <button disabled={status.pending}>Submit</button>
}

export default function App() {
  return (
    <form action={action}>
      <Submit />
    </form>
  );
}

要获取状态信息，必须在 <form> 中渲染 Submit 组件。Hook 返回诸如 pending 属性之类的信息，该属性告诉你表单是否正在主动提交。

¥To get status information, the Submit component must be rendered within a <form>. The Hook returns information like the pending property which tells you if the form is actively submitting.

在上面的示例中，Submit 在提交表单时使用此信息禁用 <button> 按键。

¥In the above example, Submit uses this information to disable <button> presses while the form is submitting.

请参阅下面的更多示例。

¥See more examples below.

参数

¥Parameters

useFormStatus 没有参数。

¥useFormStatus does not take any parameters.

返回

¥Returns

具有以下属性的 status 对象：

¥A status object with the following properties:

  • pending：一个布尔值。如果是 true，这意味着父级 <form> 正在等待提交。否则，false。

    ¥pending: A boolean. If true, this means the parent <form> is pending submission. Otherwise, false.

  • data：实现 FormData interface 的对象，其中包含父 <form> 正在提交的数据。如果没有主动提交或没有父 <form>，则为 null。

    ¥data: An object implementing the FormData interface that contains the data the parent <form> is submitting. If there is no active submission or no parent <form>, it will be null.

  • method：字符串值 'get' 或 'post'。这表示父级 <form> 是否使用 GET 或 POST HTTP 方式 提交。默认情况下，<form> 将使用 GET 方法，并且可以通过 method 属性指定。

    ¥method: A string value of either 'get' or 'post'. This represents whether the parent <form> is submitting with either a GET or POST HTTP method. By default, a <form> will use the GET method and can be specified by the method property.

  • action：对传递给父级 <form> 上的 action 属性的函数的引用。如果没有父代 <form>，则属性为 null。如果为 action 属性提供了 URI 值，或者未指定 action 属性，则 status.action 将是 null。

    ¥action: A reference to the function passed to the action prop on the parent <form>. If there is no parent <form>, the property is null. If there is a URI value provided to the action prop, or no action prop specified, status.action will be null.

注意事项

¥Caveats

  • useFormStatus 钩子必须从在 <form> 内渲染的组件调用。

    ¥The useFormStatus Hook must be called from a component that is rendered inside a <form>.

  • useFormStatus 将仅返回父级 <form> 的状态信息。它不会返回在同一组件或子组件中渲染的任何 <form> 的状态信息。

    ¥useFormStatus will only return status information for a parent <form>. It will not return status information for any <form> rendered in that same component or children components.

用法

¥Usage

表单提交期间显示待处理状态

¥Display a pending state during form submission

要在提交表单时显示待处理状态，你可以在 <form> 中渲染的组件中调用 useFormStatus 钩子并读取返回的 pending 属性。

¥To display a pending state while a form is submitting, you can call the useFormStatus Hook in a component rendered in a <form> and read the pending property returned.

在这里，我们使用 pending 属性来指示表单正在提交。

¥Here, we use the pending property to indicate the form is submitting.

import { useFormStatus } from "react-dom";
import { submitForm } from "./actions.js";

function Submit() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Submitting..." : "Submit"}
    </button>
  );
}

function Form({ action }) {
  return (
    <form action={action}>
      <Submit />
    </form>
  );
}

export default function App() {
  return <Form action={submitForm} />;
}

易犯错误

useFormStatus 不会返回在同一组件中渲染的 <form> 的状态信息。

¥useFormStatus will not return status information for a <form> rendered in the same component.

useFormStatus 钩子仅返回父 <form> 的状态信息，而不返回调用钩子的同一组件或子组件中渲染的任何 <form> 的状态信息。

¥The useFormStatus Hook only returns status information for a parent <form> and not for any <form> rendered in the same component calling the Hook, or child components.

function Form() {
  // 🚩 `pending` will never be true
  // useFormStatus does not track the form rendered in this component
  const { pending } = useFormStatus();
  return <form action={submit}></form>;
}

而是从位于 <form> 内部的组件内部调用 useFormStatus。

¥Instead call useFormStatus from inside a component that is located inside <form>.

function Submit() {
  // ✅ `pending` will be derived from the form that wraps the Submit component
  const { pending } = useFormStatus(); 
  return <button disabled={pending}>...</button>;
}

function Form() {
  // This is the <form> `useFormStatus` tracks
  return (
    <form action={submit}>
      <Submit />
    </form>
  );
}

读取正在提交的表单数据

¥Read the form data being submitted

你可以使用从 useFormStatus 返回的状态信息的 data 属性来显示用户正在提交哪些数据。

¥You can use the data property of the status information returned from useFormStatus to display what data is being submitted by the user.

在这里，我们有一个表单，用户可以在其中请求用户名。我们可以使用 useFormStatus 显示临时状态消息，确认他们请求的用户名。

¥Here, we have a form where users can request a username. We can use useFormStatus to display a temporary status message confirming what username they have requested.

import {useState, useMemo, useRef} from 'react';
import {useFormStatus} from 'react-dom';

export default function UsernameForm() {
  const {pending, data} = useFormStatus();

  return (
    <div>
      <h3>Request a Username: </h3>
      <input type="text" name="username" disabled={pending}/>
      <button type="submit" disabled={pending}>
        Submit
      </button>
      <br />
      <p>{data ? `Requesting ${data?.get("username")}...`: ''}</p>
    </div>
  );
}

故障排除

¥Troubleshooting

status.pending 绝不是 true

¥status.pending is never true

useFormStatus 将仅返回父级 <form> 的状态信息。

¥useFormStatus will only return status information for a parent <form>.

如果调用 useFormStatus 的组件未嵌套在 <form> 中，则 status.pending 将始终返回 false。验证 useFormStatus 在作为 <form> 元素的子元素的组件中被调用。

¥If the component that calls useFormStatus is not nested in a <form>, status.pending will always return false. Verify useFormStatus is called in a component that is a child of a <form> element.

useFormStatus 不会跟踪同一组件中渲染的 <form> 的状态。详细信息请参见 陷阱。

¥useFormStatus will not track the status of a <form> rendered in the same component. See Pitfall for more details.

上一章钩子
下一章组件