<Form>

渐进增强的 HTML <form>，通过 fetch 向操作提交数据，激活 useNavigation 中的待处理状态，从而支持超越基本 HTML 表单的高级用户界面。表单操作完成后，页面上的所有数据都会自动从服务器重新验证，以确保 UI 与数据同步。

¥A progressively enhanced HTML <form> that submits data to actions via fetch, activating pending states in useNavigation which enables advanced user interfaces beyond a basic HTML form. After a form's action completes, all data on the page is automatically revalidated from the server to keep the UI in sync with the data.

由于使用 HTML 表单 API，因此服务器渲染的页面在 JavaScript 加载之前就具有基本的交互性。Remix 不再管理提交，而是浏览器管理提交以及待处理状态（例如旋转的图标）。JavaScript 加载后，Remix 将接管并提升 Web 应用的用户体验。

¥Because it uses the HTML form API, server-rendered pages are interactive at a basic level before JavaScript loads. Instead of Remix managing the submission, the browser manages the submission as well as the pending states (like the spinning favicon). After JavaScript loads, Remix takes over enabling web application user experiences.

表单对于需要更改 URL 或以其他方式向浏览器历史记录堆栈添加条目的提交非常有用。对于不应操作浏览器历史记录堆栈的表单，请使用 <fetcher.Form>。

¥Form is most useful for submissions that should also change the URL or otherwise add an entry to the browser history stack. For forms that shouldn't manipulate the browser history stack, use <fetcher.Form>.

import { Form } from "@remix-run/react";

function NewEvent() {
  return (
    <Form action="/events" method="post">
      <input name="title" type="text" />
      <input name="description" type="text" />
    </Form>
  );
}

属性

¥Props

action

提交表单数据的 URL。

¥The URL to submit the form data to.

如果是 undefined，则默认为上下文中最接近的路由。如果父路由渲染了 <Form>，但 URL 与更深层的子路由匹配，则表单将提交到父路由。同样，子路由内的表单也会提交到子路由。这与始终指向完整 URL 的原生 <form> 不同。

¥If undefined, this defaults to the closest route in context. If a parent route renders a <Form> but the URL matches deeper child routes, the form will post to the parent route. Likewise, a form inside the child route will post to the child route. This differs from a native <form> that will always point to the full URL.

请参阅 useResolvedPath 文档中的 Splat 路径 部分，了解 future.v3_relativeSplatPath 未来标志在 splat 路由中相对于 <Form action> 行为的行为

method

这将决定要使用的 HTTP 动词：DELETE、GET、PATCH、POST 和 PUT。默认为 GET。

¥This determines the HTTP verb to be used: DELETE, GET, PATCH, POST, and PUT. The default is GET.

<Form method="post" />

原生 <form> 仅支持 GET 和 POST，因此如果你想支持 渐进增强，则应避免使用其他动词。

¥Native <form> only supports GET and POST, so you should avoid the other verbs if you'd like to support progressive enhancement

encType

用于表单提交的编码类型。

¥The encoding type to use for the form submission.

<Form encType="multipart/form-data" />

默认为 application/x-www-form-urlencoded，使用 multipart/form-data 进行文件上传。

¥Defaults to application/x-www-form-urlencoded, use multipart/form-data for file uploads.

navigate

你可以通过指定 <Form navigate={false}> 来让表单跳过导航并在内部使用 fetcher。这本质上是 useFetcher() + <fetcher.Form> 的简写，在这种情况下，你不关心结果数据，只想启动提交并通过 useFetchers() 访问待处理状态。

¥You can tell the form to skip the navigation and use a fetcher internally by specifying <Form navigate={false}>. This is essentially a shorthand for useFetcher() + <fetcher.Form> where you don't care about the resulting data and only want to kick off a submission and access the pending state via useFetchers().

<Form method="post" navigate={false} />

fetcherKey

使用非导航式 Form 时，你也可以选择指定要使用的自定义 fetcher key。

¥When using a non-navigating Form, you may also optionally specify your own fetcher key to use.

<Form method="post" navigate={false} fetcherKey="my-key" />

preventScrollReset

如果你使用 <ScrollRestoration>，这可以防止在提交表单时将滚动位置重置到窗口顶部。

¥If you are using <ScrollRestoration>, this lets you prevent the scroll position from being reset to the top of the window when the form is submitted.

<Form preventScrollReset />

replace

替换历史记录堆栈中的当前条目，而不是推送新条目。

¥Replaces the current entry in the history stack instead of pushing the new entry.

<Form replace />

reloadDocument

如果为 true，它将使用浏览器提交表单，而不是客户端路由。与原生 <form> 相同。

¥If true, it will submit the form with the browser instead of client side routing. The same as a native <form>.

<Form reloadDocument />

建议使用此方法，而不是 <form>。当省略 action 属性时，<Form> 和 <form> 有时会根据当前 URL 调用不同的操作，因为 <form> 使用当前 URL 作为默认 URL，而 <Form> 使用表单渲染路由的 URL。

¥This is recommended over <form>. When the action prop is omitted, <Form> and <form> will sometimes call different actions depending on what the current URL is since <form> uses the current URL as the default, but <Form> uses the URL for the route the form is rendered in.

viewTransition

viewTransition 属性通过将最终状态更新封装在 document.startViewTransition() 中，为本次导航启用 查看 Transition。如果你需要为此视图转换应用特定样式，你还需要利用 useViewTransitionState()。

¥The viewTransition prop enables a View Transition for this navigation by wrapping the final state update in document.startViewTransition(). If you need to apply specific styles for this view transition, you will also need to leverage the useViewTransitionState().

注意

¥Notes

?index

由于索引路由及其父路由共享相同的 URL，因此使用 ?index 参数来区分它们。

¥Because index routes and their parent route share the same URL, the ?index param is used to differentiate between them.

<Form action="/accounts?index" method="post" />

另请参阅：

¥See also:

• ?index 查询参数

  ¥?index query param

其他资源

¥Additional Resources

视频：

¥Videos:

• 使用表单 + 操作的数据变更

  ¥Data Mutations with Form + action

• 多表单和单按钮突变

  ¥Multiple Forms and Single Button Mutations

• 表单提交后清除输入

  ¥Clearing Inputs After Form Submissions

相关讨论：

¥Related Discussions:

• 全栈数据流

  ¥Fullstack Data Flow

• 待处理 UI

  ¥Pending UI

• 表单 vs. 获取器

  ¥Form vs. Fetcher

相关 API：

¥Related APIs:

• useActionData

• useNavigation

• useSubmit