Form

<Form> 组件扩展了 HTML <form> 元素，以提供预取加载 UI 的功能，提交时的客户端导航，以及渐进增强。

对于更新 URL 搜索参数的表单，它非常有用，因为它减少了实现上述功能所需的样板代码。

基本用法

/app/ui/search.tsx

import Form from 'next/form'
 
export default function Page() {
  return (
    <Form action="/search">
      {/* On submission, the input value will be appended to 
          the URL, e.g. /search?query=abc */}
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}

参考

<Form> 组件的行为取决于 action 属性传递的是 string 还是 function。

当 action 是 string 时，<Form> 的行为类似于使用 GET 方法的原生 HTML 表单。表单数据被编码到 URL 中作为搜索参数，并且当表单提交时，它会导航到指定的 URL。此外，Next.js
- 预取表单变为可见时的路径，这会预加载共享 UI（例如 layout.js 和 loading.js），从而加快导航速度。
- 执行客户端导航而不是在表单提交时进行完整的页面重新加载。这保留了共享 UI 和客户端状态。
当 action 是 function (服务端 Action) 时，<Form> 的行为类似于 React 表单，在表单提交时执行 action。

`action` (string) 属性

当 action 是 string 时，<Form> 组件支持以下属性

属性	示例	类型	必需
`action`	`action="/search"`	`string` (URL 或相对路径)	是
`replace`	`replace={false}`	`boolean`	-
`scroll`	`scroll={true}`	`boolean`	-
`prefetch`	`prefetch={true}`	`boolean`	-

action：表单提交时导航到的 URL 或路径。
- 空字符串 "" 将导航到具有更新搜索参数的同一路由。
replace：替换当前历史记录状态，而不是向浏览器的历史记录堆栈推送新的状态。默认为 false。
scroll：控制导航期间的滚动行为。默认为 true，这意味着它将滚动到新路由的顶部，并为后退和前进导航保持滚动位置。
prefetch：控制当表单在用户视口中变为可见时是否应预取路径。默认为 true。

`action` (function) 属性

当 action 是 function 时，<Form> 组件支持以下属性

属性	示例	类型	必需
`action`	`action={myAction}`	`function` (服务端 Action)	是

action：表单提交时要调用的服务端 Action。有关更多信息，请参阅 React 文档。

须知：当 action 是 function 时，replace 和 scroll 属性将被忽略。

注意事项

formAction：可用于 <button> 或 <input type="submit"> 字段以覆盖 action 属性。Next.js 将执行客户端导航，但是，此方法不支持预取。
- 当使用 basePath 时，你还必须将其包含在 formAction 路径中。例如 formAction="/base-path/search"。
key：不支持将 key 属性传递给 string action。如果你想触发重新渲染或执行 mutation，请考虑使用 function action 代替。

onSubmit：可用于处理表单提交逻辑。但是，调用 event.preventDefault() 将覆盖 <Form> 行为，例如导航到指定的 URL。
method、 encType、 target：不受支持，因为它们会覆盖 <Form> 行为。
- 同样，formMethod、formEncType 和 formTarget 可用于分别覆盖 method、encType 和 target 属性，使用它们将回退到原生浏览器行为。
- 如果你需要使用这些属性，请改用 HTML <form> 元素。
<input type="file">：当 action 是 string 时，使用此输入类型将匹配浏览器行为，方法是提交文件名而不是文件对象。

示例

你可以通过将路径作为 action 传递来创建一个导航到搜索结果页面的搜索表单

/app/page.tsx

import Form from 'next/form'
 
export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}

当用户更新查询输入字段并提交表单时，表单数据将被编码到 URL 中作为搜索参数，例如 /search?query=abc。

须知：如果你将空字符串 "" 传递给 action，则表单将导航到具有更新搜索参数的同一路由。

在结果页面上，你可以使用 searchParams page.js 属性访问查询，并使用它从外部源获取数据。

/app/search/page.tsx

import { getSearchResults } from '@/lib/search'
 
export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const results = await getSearchResults((await searchParams).query)
 
  return <div>...</div>
}

当 <Form> 在用户视口中变为可见时，/search 页面上的共享 UI（例如 layout.js 和 loading.js）将被预取。提交时，表单将立即导航到新路由，并在获取结果时显示加载 UI。你可以使用 loading.js 设计回退 UI

/app/search/loading.tsx

export default function Loading() {
  return <div>Loading...</div>
}

为了覆盖共享 UI 尚未加载的情况，你可以使用 useFormStatus 向用户显示即时反馈。

首先，创建一个组件，在表单处于 pending 状态时显示加载状态

/app/ui/search-button.tsx

'use client'
import { useFormStatus } from 'react-dom'
 
export default function SearchButton() {
  const status = useFormStatus()
  return (
    <button type="submit">{status.pending ? 'Searching...' : 'Search'}</button>
  )
}

然后，更新搜索表单页面以使用 SearchButton 组件

/app/page.tsx

import Form from 'next/form'
import { SearchButton } from '@/ui/search-button'
 
export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <SearchButton />
    </Form>
  )
}

使用服务端 Actions 进行 Mutations

你可以通过将 function 传递给 action 属性来执行 mutations。

/app/posts/create/page.tsx

import Form from 'next/form'
import { createPost } from '@/posts/actions'
 
export default function Page() {
  return (
    <Form action={createPost}>
      <input name="title" />
      {/* ... */}
      <button type="submit">Create Post</button>
    </Form>
  )
}

在 mutation 之后，通常会重定向到新资源。你可以使用 next/navigation 中的 redirect 函数导航到新帖子页面。

须知：由于表单提交的“目的地”在 action 执行之前是未知的，因此 <Form> 无法自动预取共享 UI。

/app/posts/actions.ts

'use server'
import { redirect } from 'next/navigation'
 
export async function createPost(formData: FormData) {
  // Create a new post
  // ...
 
  // Redirect to the new post
  redirect(`/posts/${data.id}`)
}

然后，在新页面中，你可以使用 params 属性获取数据

/app/posts/[id]/page.tsx

import { getPost } from '@/posts/data'
 
export default async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const data = await getPost((await params).id)
 
  return (
    <div>
      <h1>{data.title}</h1>
      {/* ... */}
    </div>
  )
}

有关更多示例，请参阅服务端 Actions 文档。

Form

参考

action (string) 属性

action (function) 属性

注意事项

示例

搜索表单，导向搜索结果页

使用服务端 Actions 进行 Mutations

`action` (string) 属性

`action` (function) 属性