NNext.js 中文网 GitHub

Form 组件

了解如何使用 <Form> 组件处理表单提交和通过客户端导航更新 search params。

<Form> 组件扩展了 HTML <form> 元素,提供 loading UI的预取、提交时的客户端导航以及渐进式增强。

它适用于更新 URL search params 的表单,因为它减少了实现上述功能所需的样板代码。

基本用法:

/app/ui/search.tsx
import Form from 'next/form'

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

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

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

export default function Search() {
  return (
    <Form action="/search">
      
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}

参考#

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

  • 当 action 是字符串时,<Form> 的行为类似于使用 GET 方法的原生 HTML 表单。表单数据被编码为 URL 中的 search params,提交表单时,它会导航到指定的 URL。此外,Next.js:
    • 当表单变得可见时预取路径,这会预加载共享 UI(例如 layout.js 和 loading.js),从而加快导航速度。
    • 提交表单时执行客户端导航而不是整页重新加载。这保留了共享 UI 和客户端状态。
  • 当 action 是函数(Server Action)时,<Form> 的行为类似于 React form,在提交表单时执行该 action。
  • 当 action 是字符串时,<Form> 的行为类似于使用 GET 方法的原生 HTML 表单。表单数据被编码为 URL 中的 search params,提交表单时,它会导航到指定的 URL。此外,Next.js:
    • 提交表单时执行客户端导航而不是整页重新加载。这保留了共享 UI 和客户端状态。

action(字符串)属性#

当 action 是字符串时,<Form> 组件支持以下属性:

属性示例类型必填
actionaction="/search"string(URL 或相对路径)是
replacereplace={false}boolean-
scrollscroll={true}boolean-
  • action:提交表单时要导航到的 URL 或路径。
    • 空字符串 "" 将导航到同一路由并更新 search params。
  • replace:替换当前历史记录状态,而不是向浏览器历史记录栈中压入新状态。默认值为 false。
  • scroll:控制导航期间的滚动行为。默认值为 true,这意味着它将滚动到新路由的顶部,并在前进和后退导航时保持滚动位置。

当 action 是字符串时,<Form> 组件支持以下属性:

属性示例类型必填
actionaction="/search"string(URL 或相对路径)是
replacereplace={false}boolean-
scrollscroll={true}boolean-
prefetchprefetch={true}boolean-
  • action:提交表单时要导航到的 URL 或路径。
    • 空字符串 "" 将导航到同一路由并更新 search params。
  • replace:替换当前历史记录状态,而不是向浏览器历史记录栈中压入新状态。默认值为 false。
  • scroll:控制导航期间的滚动行为。默认值为 true,这意味着它将滚动到新路由的顶部,并在前进和后退导航时保持滚动位置。
  • prefetch:控制当表单在用户视口中变得可见时是否应预取该路径。默认值为 true。

action(函数)属性#

当 action 是函数时,<Form> 组件支持以下属性:

属性示例类型必填
actionaction={myAction}function(Server Action)是
  • action:提交表单时要调用的 Server Action。有关更多信息,请参阅 React 文档。

小知识:当 action 是函数时,replace 和 scroll 属性会被忽略。

注意事项#

  • formAction:可在 <button> 或 <input type="submit"> 字段中使用,以覆盖 action 属性。Next.js 将执行客户端导航,但此方法不支持预取。
    • 使用 basePath 时,还必须在 formAction 路径中包含它。例如 formAction="/base-path/search"。
  • key:不支持向字符串 action 传递 key 属性。如果你想触发重新渲染或执行 mutation,请考虑改用函数 action。
  • onSubmit:可用于处理表单提交逻辑。但是,调用 event.preventDefault() 将覆盖 <Form> 的行为,例如导航到指定的 URL。
  • method、encType、target:不受支持,因为它们会覆盖 <Form> 的行为。
    • 类似地,formMethod、formEncType 和 formTarget 可分别用于覆盖 method、encType 和 target 属性,使用它们将回退到原生浏览器行为。
    • 如果你需要使用这些属性,请改用 HTML <form> 元素。
  • <input type="file">:当 action 是字符串时,使用此输入类型将匹配浏览器行为,提交文件名而不是文件对象。

示例#

导向搜索结果页的搜索表单#

你可以通过将路径作为 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>
  )
}
/app/page.js
import Form from 'next/form'

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

当用户更新查询输入字段并提交表单时,表单数据将被编码为 URL 中的 search params,例如 /search?query=abc。

小知识:如果你向 action 传递空字符串 "",表单将导航到同一路由并更新 search params。

在结果页上,你可以使用 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>
}
/app/search/page.js
import { getSearchResults } from '@/lib/search'

export default async function SearchPage({ searchParams }) {
  const results = await getSearchResults((await searchParams).query)

  return <div>...</div>
}

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

/app/search/loading.tsx
export default function Loading() {
  return <div>Loading...</div>
}
/app/search/loading.js
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>
  )
}
/app/ui/search-button.js
'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>
  )
}
/app/page.js
import Form from 'next/form'
import SearchButton from '@/ui/search-button'

export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <SearchButton />
    </Form>
  )
}

使用 Server Actions 执行 mutation#

你可以通过向 action 属性传递函数来执行 mutation。

/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>
  )
}
/app/posts/create/page.js
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) {
  // 创建新文章
  // ...

  // 重定向到新文章
  redirect(`/posts/${data.id}`)
}
/app/posts/actions.js
'use server'
import { redirect } from 'next/navigation'

export async function createPost(formData) {
  // 创建新文章
  // ...

  // 重定向到新文章
  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 { id } = await params
  const data = await getPost(id)

  return (
    <div>
      <h1>{data.title}</h1>
      
    </div>
  )
}
/app/posts/[id]/page.js
import { getPost } from '@/posts/data'

export default async function PostPage({ params }) {
  const { id } = await params
  const data = await getPost(id)

  return (
    <div>
      <h1>{data.title}</h1>
      
    </div>
  )
}

有关更多示例,请参阅变更数据。

Next.js 中文网