表单

¥Form

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

¥The <Form> component extends the HTML <form> element to provide client-side navigation on submission, and progressive enhancement.

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

¥It's useful for forms that update URL search params as it reduces the boilerplate code needed to achieve the above.

基本用法：

¥Basic usage:

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>
  )
}

参考

¥Reference

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

¥The behavior of the <Form> component depends on whether the action prop is passed a string or function.

• 当 action 为字符串时，<Form> 的行为类似于使用 GET 方法的原生 HTML 表单。表单数据作为搜索参数编码到 URL 中，提交表单时，会导航到指定的 URL。此外，Next.js：

  ¥When action is a string, the <Form> behaves like a native HTML form that uses a GET method. The form data is encoded into the URL as search params, and when the form is submitted, it navigates to the specified URL. In addition, Next.js:

  • 提交表单时执行 客户端导航 而不是整个页面重新加载。这保留了共享的 UI 和客户端状态。

    ¥Performs a client-side navigation instead of a full page reload when the form is submitted. This retains shared UI and client-side state.

action（字符串）属性

¥action (string) Props

当 action 是字符串时，<Form> 组件支持以下 props：

¥When action is a string, the <Form> component supports the following props:

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

• action：提交表单时要导航到的 URL 或路径。

  ¥action: The URL or path to navigate to when the form is submitted.

  • 空字符串​​ "" 将导航到具有更新的搜索参数的相同路由。

    ¥An empty string "" will navigate to the same route with updated search params.

• replace：替换当前历史状态，而不是将新状态推送到 浏览器的历史 堆栈。默认为 false。

  ¥replace: Replaces the current history state instead of pushing a new one to the browser's history stack. Default is false.

• scroll：控制导航期间的滚动行为。默认为 true，这意味着它将滚动到新路由的顶部，并保持滚动位置以进行前后导航。

  ¥scroll: Controls the scroll behavior during navigation. Defaults to true, this means it will scroll to the top of the new route, and maintain the scroll position for backwards and forwards navigation.

注意事项

¥Caveats

• onSubmit：可用于处理表单提交逻辑。但是，调用 event.preventDefault() 将覆盖 <Form> 行为，例如导航到指定的 URL。

  ¥onSubmit: Can be used to handle form submission logic. However, calling event.preventDefault() will override <Form> behavior such as navigating to the specified URL.

• method, encType, target:不受支持，因为它们会覆盖 <Form> 行为。

  ¥method, encType, target: Are not supported as they override <Form> behavior.

  • 类似地，formMethod、formEncType 和 formTarget 可分别用于覆盖 method、encType 和 target 属性，使用它们将恢复到原生浏览器行为。

    ¥Similarly, formMethod, formEncType, and formTarget can be used to override the method, encType, and target props respectively, and using them will fallback to native browser behavior.

  • 如果你需要使用这些属性，请改用 HTML <form> 元素。

    ¥If you need to use these props, use the HTML <form> element instead.

• <input type="file">：当 action 是字符串时，使用此输入类型将通过提交文件名而不是文件对象来匹配浏览器行为。

  ¥<input type="file">: Using this input type when the action is a string will match browser behavior by submitting the filename instead of the file object.