From 5e085ec0e3bec61d0898e11e4f4e5d715a2b748a Mon Sep 17 00:00:00 2001 From: moshyfawn Date: 2023年2月26日 15:12:29 -0500 Subject: [PATCH 1/3] =?UTF-8?q?WIP=20=F0=9F=93=9D=20docs(useForm):=20add?= =?UTF-8?q?=20md=20description=20of=20values=20option?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Related: #739 --- src/markdown/useForm.md | 166 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 src/markdown/useForm.md diff --git a/src/markdown/useForm.md b/src/markdown/useForm.md new file mode 100644 index 000000000..756025524 --- /dev/null +++ b/src/markdown/useForm.md @@ -0,0 +1,166 @@ +# `useForm` + +[`useForm`](#useform) is the core hook that let's you pass in your form's default values, configure validation behavior and rules and sync your client form values with remote data. + +```js +const form = useForm(options) +``` + +## Reference + +### `useForm(options)` + +Call [`useForm`](#useform) at the top level of your component to create a form instance. + +```js +import { useForm } from 'react-hook-form' + +const options = { + // ... +} + +function Form() { + const form = useForm(options) + // ... +} +``` + +### Options + +#### `values` + +Available since: [`v7.41.0`](https://github.com/react-hook-form/react-hook-form/releases/tag/v7.41.0) + +An object containing values of a remote source. This is useful when you have data that can change while the user is filling out the form and you want to keep your client-side form values in sync with the remote data. + +```js +const { data } = useQuery({ + queryKey: ['user'], + queryFn: () => fetch('/api/user') +}) + +useForm({ + values: data +}) +``` + +> **Note** +> You can provide [`resetOptions`](#values-resetoptions) to the [`useForm`](#useform) hook to determine what form values and states should be updated when the [`values`](#values) change. + +#### `values` + `resetOptions` + +Available since: [`v7.41.0`](https://github.com/react-hook-form/react-hook-form/releases/tag/v7.41.0) + +When [`values`](#values) **is provided**, you can also provide [`resetOptions`](#values-resetoptions) to determine what form values and states should be updated when the `values` change. + +Currently, [`resetOptions`](#values-resetoptions) is an object of `boolean` properties that correspond to the [`reset`](#reset) method's options. + +> **Developer commentary**: The [`resetOptions`](#values-resetoptions) description can potentially be moved to the [`reset`](#reset) method's description and linked to from here. I'll will leave it here for now to emphasis the [`values` + `resetOptions`](#values-resetoptions) usage. + +##### keepDirtyValues + +When `true`, only the form values that weren't changed will be updated. This is useful when you want to update the form values with new data but you don't want to overwrite current user input. + +> **Warning** +> The checks for the [`keepDirtyValues`](#keepdirtyvalues) and [`keepDefaultValues`](#keepdefaultvalues) options are mutually exclusive. If both are `true`, the [`keepDirtyValues`](#keepdirtyvalues) option will take precedence. + +##### keepErrors + +When `true`, all form values will be updated with the new [`values`](#values) but [`formState.errors`](#errors) will be kept the same despite the new [`values`](#values). This is useful when you want to update the form values with new data but you don't want to reset the current form errors. + +##### keepDirty + +When `true`, all form values will be updated with the new [`values`](#values) but [`formState.isDirty`](#isdirty) will remain the same despite the new [`values`](#values). This is useful when you want to update the form values with new data but you don't want to reset the form's dirtiness state. + +##### keepValues + +When `true`, all form values will be kept the same despite the new [`values`](#values). Only [`formState.defaultValues`](#defaultvalues) will be updated. This is useful when you want to reflect that the remote data has changed but you don't want to overwrite the current user input. + +> **Warning** +> The checks for the [`keepValues`](#keepvalues) and [`keepDefaultValues`](#keepdefaultvalues) options are mutually exclusive. If both are `true`, the [`keepValues`](#keepvalues) option will take precedence. + +##### keepDefaultValues + +When `true`, all form values will be updated with the new [`values`](#values) but [`formState.defaultValues`](#) will remain the same despite the new [`values`](#values). This is useful when you want to update the form values with new data and sync form dirtiness states according to the new values. + +> **Note** +> The input's dirtiness will be checked upon the [`values`](#values) update and the input will be marked as dirty if the new value is different from the default value. This will update both the [`formState.dirtyFields`](#dirtyfields) and [`formState.isDirty`](#isdirty) states accordingly. + +> **Warning** +> The checks for the [`keepDirtyValues`](#keepdirtyvalues) and [`keepDefaultValues`](#keepdefaultvalues) options are mutually exclusive. If both are `true`, the [`keepDirtyValues`](#keepdirtyvalues) option will take precedence. + +##### keepIsSubmitted + +When `true`, all form values will be updated with the new [`values`](#values) but [`formState.keepIsSubmitted`](#keepissubmitted) will remain the same despite the new [`values`](#values). This is useful when you want to update the form values with new data but you don't want to reset the form's submitted state. + +##### keepTouched + +When `true`, all form values will be updated with the new [`values`](#values) but [`formState.isTouched`](#istouched) will remain the same despite the new [`values`](#values). This is useful when you want to update the form values with new data but you don't want to reset the form's touched state. + +##### keepIsValid + +When `true`, all form values will be updated with the new [`values`](#values) but [`formState.isValid`](#isvalid) will remain the same despite the new [`values`](#values) validity and the [`keepErrors`](#keeperrors) option. This is useful when you want to update the form values with new data but you don't want to reset the form's validity state. + +##### keepSubmitCount: + +When `true`, all form values will be updated with the new [`values`](#values) but [`formState.submitCount`](#submitcount) will remain the same. This is useful when you want to update the form values with new data but you don't want to reset the form's submit count. + +```js +// This config will persist current user input, dirtiness, validity and submission form states, +// updating only the form values that weren't changed +// when the `values` change +const resetOptions = { + keepDirtyValues: true + keepErrors: true + keepDirty: true + keepIsValid: true + keepSubmitCount: true + keepIsSubmitted: true +} + +useForm({ + values: { + // ... + }, + resetOptions +}) +``` + +> **Warning** +> The [`resetOptions`](#values-resetoptions) API is a subject to change in the next major release. + +> **Developer commentary**: This is also related to [`defaultValues` + `resetOptions`](#defaultvalues-resetoptions) usage which is not covered in this iteration of the documentation. + +### Returns + +`useForm` returns a form instance containing the following properties: + +#### `watch` + +#### `getValues` + +#### `getFieldState` + +#### `setError` + +#### `clearErrors` + +#### `setValue` + +#### `trigger` + +#### `formState` + +#### `resetField` + +#### `reset` + +#### `handleSubmit` + +#### `unregister` + +#### `control` + +#### `register` + +#### `setFocus` \ No newline at end of file From 319fd5304828c63f748a117e699c141fe65fefa7 Mon Sep 17 00:00:00 2001 From: moshyfawn Date: 2023年2月26日 22:10:14 -0500 Subject: [PATCH 2/3] =?UTF-8?q?WIP=20=F0=9F=93=9D=20docs(useForm):=20add?= =?UTF-8?q?=20useForm=20return=20methods=20nav=20list?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/markdown/useForm.md | 42 ++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/src/markdown/useForm.md b/src/markdown/useForm.md index 756025524..bbf16e72e 100644 --- a/src/markdown/useForm.md +++ b/src/markdown/useForm.md @@ -31,7 +31,7 @@ function Form() { Available since: [`v7.41.0`](https://github.com/react-hook-form/react-hook-form/releases/tag/v7.41.0) -An object containing values of a remote source. This is useful when you have data that can change while the user is filling out the form and you want to keep your client-side form values in sync with the remote data. +An `object` containing values of a remote source. This is useful when you have data that can change while the user is filling out the form and you want to keep your client-side form values in sync with the remote data. ```js const { data } = useQuery({ @@ -53,7 +53,7 @@ Available since: [`v7.41.0`](https://github.com/react-hook-form/react-hook-form/ When [`values`](#values) **is provided**, you can also provide [`resetOptions`](#values-resetoptions) to determine what form values and states should be updated when the `values` change. -Currently, [`resetOptions`](#values-resetoptions) is an object of `boolean` properties that correspond to the [`reset`](#reset) method's options. +Currently, [`resetOptions`](#values-resetoptions) is an `object` of `boolean` properties that correspond to the [`reset`](#reset) method's options. > **Developer commentary**: The [`resetOptions`](#values-resetoptions) description can potentially be moved to the [`reset`](#reset) method's description and linked to from here. I'll will leave it here for now to emphasis the [`values` + `resetOptions`](#values-resetoptions) usage. @@ -81,7 +81,7 @@ When `true`, all form values will be kept the same despite the new [`values`](#v ##### keepDefaultValues -When `true`, all form values will be updated with the new [`values`](#values) but [`formState.defaultValues`](#) will remain the same despite the new [`values`](#values). This is useful when you want to update the form values with new data and sync form dirtiness states according to the new values. +When `true`, all form values will be updated with the new [`values`](#values) but [`formState.defaultValues`](#defaultvalues) will remain the same despite the new [`values`](#values). This is useful when you want to update the form values with new data and sync form dirtiness states according to the new values. > **Note** > The input's dirtiness will be checked upon the [`values`](#values) update and the input will be marked as dirty if the new value is different from the default value. This will update both the [`formState.dirtyFields`](#dirtyfields) and [`formState.isDirty`](#isdirty) states accordingly. @@ -135,32 +135,32 @@ useForm({ `useForm` returns a form instance containing the following properties: -#### `watch` +- [`handleSubmit`](handlesubmit) -#### `getValues` +- [`register`](register) -#### `getFieldState` +- `control` - An `object` containing **internal** library methods and properties. You **should not** use this property directly at this time. -#### `setError` +- [`formState`](formstate) -#### `clearErrors` +- [`watch`](watch) -#### `setValue` +- [`reset`](reset) + +- [`getValues`](getvalues) -#### `trigger` +- [`setValue`](setvalue) -#### `formState` +- [`trigger`](trigger) + +- [`setError`](seterror) + +- [`clearErrors`](clearerrors) -#### `resetField` +- [`getFieldState`](getfieldstate) -#### `reset` +- [`resetField`](resetfield) -#### `handleSubmit` +- [`unregister`](unregister) -#### `unregister` - -#### `control` - -#### `register` - -#### `setFocus` \ No newline at end of file +- [`setFocus`](setFocus) \ No newline at end of file From 1b33b30a1a3aadbd13e6853524b441aac6a3e501 Mon Sep 17 00:00:00 2001 From: moshyfawn Date: 2023年2月26日 22:10:51 -0500 Subject: [PATCH 3/3] =?UTF-8?q?WIP=20=F0=9F=93=9D=20docs(handleSubmit):=20?= =?UTF-8?q?add=20desc=20skeleton?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/markdown/handleSubmit.md | 76 ++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 src/markdown/handleSubmit.md diff --git a/src/markdown/handleSubmit.md b/src/markdown/handleSubmit.md new file mode 100644 index 000000000..6373a7399 --- /dev/null +++ b/src/markdown/handleSubmit.md @@ -0,0 +1,76 @@ +# `handleSubmit` + +`handleSubmit` is a `function` that validates form values and triggers form submission. + +```js +handleSubmit(onValid, onInvalid) +``` + +## Reference + +### `handleSubmit(onValid, onInvalid)` + +`handleSubmit` execution will trigger a chain of form submission events. + +```jsx +import { useForm } from 'react-hook-form' + +function Form () { + const { handleSubmit } = useForm() + + const onSubmit = (data, event) => { + // ... + } + + const onError = (errors, event) => { + // ... + } + + return ( +
+ {/* ... */} +
+ ) +} +``` + + + +> **Note** +> `handleSubmit` can be called on events other than `submit`. For example, you can call it on `onClick` or `onTouchEnd` events. +> ```jsx +> return +> ``` + +### Options + +#### `onValid` + +[`onValid`](#onvalid) is a callback `function` that will be invoked when the form is submitted and there are no validation [`errors`](errors). It receives the form values as the first argument and the propagated `event` as the second argument. + +```jsx +const onSubmit = (data, event) => { + // ... +} +``` + +`onValid` can also be an `async` function. + +```jsx +const onSubmit = async (data, event) => { + await fetch('/api/user', { + method: 'POST', + body: JSON.stringify(data) + }) +} +``` + +#### `onInvalid` + +[`onInvalid`](#oninvalid) is a callback `function` that will be invoked when the form is submitted and there are validation errors. It receives the form [`errors`](errors) as the first argument and the propagated `event` as the second argument. + +```jsx +const onError = (errors, event) => { + // ... +} +```

AltStyle によって変換されたページ (->オリジナル) /