Menu

<Form>

<Form> 组件扩展了 HTML 的 <form> 元素,提供了客户端导航提交以及渐进式增强功能。

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

基本用法:

/ui/search.js
TypeScript
import Form from 'next/form'
 
export default function Page() {
  return (
    <Form action="/search">
      {/* 提交时,输入值将附加到 URL 中,
          例如:/search?query=abc */}
      <input name="query" />
      <button type="submit">提交</button>
    </Form>
  )
}

参考

<Form> 组件的行为取决于 action 属性是传入字符串还是函数。

  • action字符串时,<Form> 的行为类似于使用 GET 方法的原生 HTML 表单。表单数据会被编码到 URL 的搜索参数中,当表单提交时,会导航到指定的 URL。此外,Next.js 还会:
    • 在表单提交时执行客户端导航而不是完整的页面刷新。这样可以保留共享 UI 和客户端状态。

action (字符串) 属性

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

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

注意事项

  • onSubmit:可以用来处理表单提交逻辑。但是,调用 event.preventDefault() 会覆盖 <Form> 的行为,比如导航到指定的 URL。
  • methodencTypetarget:不支持这些属性,因为它们会覆盖 <Form> 的行为。
    • 同样,formMethodformEncTypeformTarget 可以用来覆盖 methodencTypetarget 属性,使用它们将回退到浏览器原生行为。
    • 如果你需要使用这些属性,请使用 HTML 的 <form> 元素。
  • <input type="file">:当 action 是字符串时使用这种输入类型,将匹配浏览器的行为,提交文件名而不是文件对象。