内置浏览器 <form> 组件 让你可以创建用于提交信息的交互式控件。

🌐 The built-in browser <form> component lets you create interactive controls for submitting information.

<form action={search}>
    <input name="query" />
    <button type="submit">Search</button>
</form>

参考

🌐 Reference

<form>

要创建用于提交信息的交互式控件，请渲染内置浏览器 <form> 组件。

🌐 To create interactive controls for submitting information, render the built-in browser <form> component.

<form action={search}>
    <input name="query" />
    <button type="submit">Search</button>
</form>

查看更多示例。

属性

🌐 Props

<form> 支持所有 常用元素属性

action：一个 URL 或函数。当将 URL 传递给 action 时，表单的行为将像 HTML 表单组件。当将函数传递给 action 时，该函数将在遵循 Action prop 模式 的 Transition 中处理表单提交。传递给 action 的函数可以是异步的，并且会以一个包含已提交表单的 表单数据 的参数调用。action 属性可以被 <button>、<input type="submit"> 或 <input type="image"> 组件上的 formAction 属性覆盖。

注意事项

🌐 Caveats

  • 当一个函数传递给 action 或 formAction 时，无论 method 属性的值如何，HTTP 方法都将是 POST。

用法

🌐 Usage

在客户端处理表单提交

🌐 Handle form submission on the client

将一个函数传递给表单的 action 属性，以便在表单提交时运行该函数。formData 将作为参数传递给该函数，因此你可以访问表单提交的数据。这不同于传统的 HTML action，后者仅接受 URL。在 action 函数成功执行后，表单中所有非受控的字段元素都会被重置。

🌐 Pass a function to the action prop of form to run the function when the form is submitted. formData will be passed to the function as an argument so you can access the data submitted by the form. This differs from the conventional HTML action, which only accepts URLs. After the action function succeeds, all uncontrolled field elements in the form are reset.

export default function Search() {
  function search(formData) {
    const query = formData.get("query");
    alert(`You searched for '${query}'`);
  }
  return (
    <form action={search}>
      <input name="query" />
      <button type="submit">Search</button>
    </form>
  );
}

使用服务器函数处理表单提交

🌐 Handle form submission with a Server Function

渲染一个带有输入框和提交按钮的 <form>。将一个服务器函数（一个用 'use server' 标记的函数）传递给表单的 action 属性，以便在表单提交时运行该函数。

🌐 Render a <form> with an input and submit button. Pass a Server Function (a function marked with 'use server') to the action prop of form to run the function when the form is submitted.

将服务器函数传递给 <form action> 允许用户在未启用 JavaScript 或代码尚未加载时提交表单。这对网络连接慢、设备性能低或禁用 JavaScript 的用户非常有利，并且类似于将 URL 传递给 action 属性时表单的工作方式。

🌐 Passing a Server Function to <form action> allow users to submit forms without JavaScript enabled or before the code has loaded. This is beneficial to users who have a slow connection, device, or have JavaScript disabled and is similar to the way forms work when a URL is passed to the action prop.

你可以使用隐藏表单字段向 <form> 的操作提供数据。服务器功能将以隐藏表单字段数据作为 FormData 的实例被调用。

🌐 You can use hidden form fields to provide data to the <form>’s action. The Server Function will be called with the hidden form field data as an instance of FormData.

import { updateCart } from './lib.js';

function AddToCart({productId}) {
  async function addToCart(formData) {
    'use server'
    const productId = formData.get('productId')
    await updateCart(productId)
  }
  return (
    <form action={addToCart}>
        <input type="hidden" name="productId" value={productId} />
        <button type="submit">Add to Cart</button>
    </form>

  );
}

为了替代使用隐藏表单字段向 <form> 的 action 提供数据，你可以调用 bind 方法来为其提供额外的参数。这将为函数绑定一个新的参数 (productId)，除此之外还有作为参数传递给函数的 formData 。

🌐 In lieu of using hidden form fields to provide data to the <form>’s action, you can call the bind method to supply it with extra arguments. This will bind a new argument (productId) to the function in addition to the formData that is passed as an argument to the function.

import { updateCart } from './lib.js';

function AddToCart({productId}) {
  async function addToCart(productId, formData) {
    "use server";
    await updateCart(productId)
  }
  const addProductToCart = addToCart.bind(null, productId);
  return (
    <form action={addProductToCart}>
      <button type="submit">Add to Cart</button>
    </form>
  );
}

当 <form> 由 服务器组件 渲染，并且 服务器函数 被传递给 <form> 的 action 属性时，该表单会被 逐步增强。

🌐 When <form> is rendered by a Server Component, and a Server Function is passed to the <form>’s action prop, the form is progressively enhanced.

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

🌐 Display a pending state during form submission

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

🌐 To display a pending state when a form is being submitted, 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 钩子的内容，请参见参考文档。

🌐 To learn more about the useFormStatus Hook see the reference documentation.

乐观地更新表单数据

🌐 Optimistically updating form data

useOptimistic Hook 提供了一种在后台操作（例如网络请求）完成之前乐观地更新用户界面的方法。在表单的上下文中，这种技术有助于使应用感觉更具响应性。当用户提交表单时，界面会立即根据预期结果进行更新，而不必等待服务器的响应来反映更改。

🌐 The useOptimistic Hook provides a way to optimistically update the user interface before a background operation, like a network request, completes. In the context of forms, this technique helps to make apps feel more responsive. When a user submits a form, instead of waiting for the server’s response to reflect the changes, the interface is immediately updated with the expected outcome.

例如，当用户在表单中输入消息并点击“发送”按钮时，useOptimistic Hook 允许消息立即出现在列表中，并带有“发送中…”的标签，即使消息实际上尚未发送到服务器。这种“乐观”方式给人一种快速和响应灵敏的印象。然后，表单会尝试在后台真正发送消息。一旦服务器确认消息已收到，“发送中…”的标签就会被移除。

🌐 For example, when a user types a message into the form and hits the “Send” button, the useOptimistic Hook allows the message to immediately appear in the list with a “Sending…” label, even before the message is actually sent to a server. This “optimistic” approach gives the impression of speed and responsiveness. The form then attempts to truly send the message in the background. Once the server confirms the message has been received, the “Sending…” label is removed.

import { useOptimistic, useState, useRef } from "react";
import { deliverMessage } from "./actions.js";

function Thread({ messages, sendMessage }) {
  const formRef = useRef();
  async function formAction(formData) {
    addOptimisticMessage(formData.get("message"));
    formRef.current.reset();
    await sendMessage(formData);
  }
  const [optimisticMessages, addOptimisticMessage] = useOptimistic(
    messages,
    (state, newMessage) => [
      ...state,
      {
        text: newMessage,
        sending: true
      }
    ]
  );

  return (
    <>
      {optimisticMessages.map((message, index) => (
        <div key={index}>
          {message.text}
          {!!message.sending && <small> (Sending...)</small>}
        </div>
      ))}
      <form action={formAction} ref={formRef}>
        <input type="text" name="message" placeholder="Hello!" />
        <button type="submit">Send</button>
      </form>
    </>
  );
}

export default function App() {
  const [messages, setMessages] = useState([
    { text: "Hello there!", sending: false, key: 1 }
  ]);
  async function sendMessage(formData) {
    const sentMessage = await deliverMessage(formData.get("message"));
    setMessages((messages) => [...messages, { text: sentMessage }]);
  }
  return <Thread messages={messages} sendMessage={sendMessage} />;
}

处理表单提交错误

🌐 Handling form submission errors

在某些情况下，由 <form> 的 action 属性调用的函数会抛出错误。你可以通过将 <form> 封装在错误边界中来处理这些错误。如果由 <form> 的 action 属性调用的函数抛出错误，将显示错误边界的回退内容。

🌐 In some cases the function called by a <form>’s action prop throws an error. You can handle these errors by wrapping <form> in an Error Boundary. If the function called by a <form>’s action prop throws an error, the fallback for the error boundary will be displayed.

import { ErrorBoundary } from "react-error-boundary";

export default function Search() {
  function search() {
    throw new Error("search error");
  }
  return (
    <ErrorBoundary
      fallback={<p>There was an error while submitting the form</p>}
    >
      <form action={search}>
        <input name="query" />
        <button type="submit">Search</button>
      </form>
    </ErrorBoundary>
  );
}

不使用 JavaScript 显示表单提交错误

🌐 Display a form submission error without JavaScript

在加载 JavaScript 包以进行渐进增强之前显示表单提交错误消息需要：

🌐 Displaying a form submission error message before the JavaScript bundle loads for progressive enhancement requires that:

  1. <form> 可由 客户端组件 渲染
  2. 传递给 <form> 的 action 属性的函数应该是一个 服务器函数
  3. useActionState 钩子用于显示错误信息

useActionState 接受两个参数：一个 服务器函数 和一个初始状态。useActionState 返回两个值，一个状态变量和一个动作。useActionState 返回的动作应传递给表单的 action 属性。useActionState 返回的状态变量可用于显示错误信息。传递给 useActionState 的服务器函数返回的值将用于更新状态变量。

import { useActionState } from "react";
import { signUpNewUser } from "./api";

export default function Page() {
  async function signup(prevState, formData) {
    "use server";
    const email = formData.get("email");
    try {
      await signUpNewUser(email);
      alert(`Added "${email}"`);
    } catch (err) {
      return err.toString();
    }
  }
  const [message, signupAction] = useActionState(signup, null);
  return (
    <>
      <h1>Signup for my newsletter</h1>
      <p>Signup with the same email twice to see an error</p>
      <form action={signupAction} id="signup-form">
        <label htmlFor="email">Email: </label>
        <input name="email" id="email" placeholder="react@example.com" />
        <button>Sign up</button>
        {!!message && <p>{message}</p>}
      </form>
    </>
  );
}

了解更多关于通过表单操作使用 useActionState 更新状态的信息

🌐 Learn more about updating state from a form action with the useActionState docs

处理多种提交类型

🌐 Handling multiple submission types

表单可以设计为根据用户点击的按钮处理多种提交操作。通过设置 formAction 属性，表单内的每个按钮都可以与不同的动作或行为关联。

🌐 Forms can be designed to handle multiple submission actions based on the button pressed by the user. Each button inside a form can be associated with a distinct action or behavior by setting the formAction prop.

当用户点击特定按钮时，表单会被提交，并执行由该按钮的属性和动作定义的相应操作。例如，表单可能默认提交文章以供审核，但有一个单独的按钮，其 formAction 设置为将文章保存为草稿。

🌐 When a user taps a specific button, the form is submitted, and a corresponding action, defined by that button’s attributes and action, is executed. For instance, a form might submit an article for review by default but have a separate button with formAction set to save the article as a draft.

export default function Search() {
  function publish(formData) {
    const content = formData.get("content");
    const button = formData.get("button");
    alert(`'${content}' was published with the '${button}' button`);
  }

  function save(formData) {
    const content = formData.get("content");
    alert(`Your draft of '${content}' has been saved!`);
  }

  return (
    <form action={publish}>
      <textarea name="content" rows={4} cols={40} />
      <br />
      <button type="submit" name="button" value="submit">Publish</button>
      <button formAction={save}>Save draft</button>
    </form>
  );
}
上一章常用（例如 <div>）
下一章<input>