mirror of
https://github.com/vercel/next.js.git
synced 2026-09-20 02:25:18 +08:00
Janka Uryga
4db8f30667
## What
This PR introduces `<Form>`, a form component integrated with the
Next.js router.
Form has two modes of operation.
### When `action` is a path/url
```jsx
<Form action="/search">
```
In essence, this is a progressively enhanced GET form.
- it will prefetch the target route (or, more commonly in this case, its
loading state)
- when submitted, it will perform a **client navigation** to the target
URL, encoding input fields from the form into the URL as search params.
### When `action` is a function
```jsx
<Form action={myReactAction}>
```
This is a progressively enhanced POST form. In this case, `<Form>` will
act just like `<form>` (i.e. execute the action function when
submitted). This is mostly here for convenience/consistency with React.
## Notes
### Notable props (or lack thereof)
- `replace` - same as Link, call `router.replace` instead of
`router.push` when navigating. This only works in "GET mode".
- `scroll` - same as Link, control the `scroll` option of router when
navigating. This only works in "GET mode".
- `onSubmit` - same as the usual, but notably, **calling
`event.preventDefault()` inside it will prevent Next from navigating**
(this matches how Link's `onClick` works)
We disallow passing certain form props (`method`, `encType`, `target`)
because both the GET and POST cases have specific requirements for these
that can't be overridden.
There is currently no way to control/disable the prefetching behavior
(like `<Link prefetch={false}>`) or render a custom component instead of
`<form>` (like Link's `passHref` behavior). These may be added in the
future.
### Submitter overrides
We have partial support for overriding the `action` via
```jsx
<button type="submit" formAction="/other-search">
```
It will also client-navigate, but can't be prefetched (because we don't
know the route to prefetch until a submit occurs), so this isn't really
recommended (unless the prefetch is triggered in some other way).
Unfortunately, just like `formAction`, all of the "banned" props
mentioned in the previous section (`method`, `encType`, `target`) are
overridable by the submitting element (the
["submitter"](https://developer.mozilla.org/en-US/docs/Web/API/SubmitEvent/submitter))
via `formMethod` , `formEncType` and `formTarget` respectively. We don't
have a good way of banning these within a `<Form>`, because we don't
have control over `<button>` props. So in this case the best we can do
is just warn and fall back to native browser behavior (because this is
what'd happen before hydration). Which means that **if the submitter
specifies a `formMethod` , `formEncType` and `formTarget` that Form
don't support, we will not client-navigate.**
### handling `<input type="file">`
Surprisingly, this works in a url-encoded form, even if it makes very
little sense. But same as submitter props, we have no good way of
banning it, so we match the browser behavior and submit _the filename_
instead of the file object.
2 lines
47 B
JavaScript
2 lines
47 B
JavaScript
module.exports = require('./dist/client/form')
|