From e5a5f6b90a4bbd1d5377368451803c81ea8d4f46 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 28 May 2026 00:52:06 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20GitHub=20Models=20API=20=EC=9E=90?= =?UTF-8?q?=EB=8F=99=20=EB=B2=88=EC=97=AD=20(2026-05-28)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/content/docs/usecontroller/controller.mdx | 1 + src/content/docs/useform.mdx | 35 +++++++++++++++++++ src/content/docs/useform/clearerrors.mdx | 4 +-- src/content/docs/useform/handlesubmit.mdx | 9 ----- src/content/docs/useform/register.mdx | 30 +++++++--------- src/content/docs/useform/reset.mdx | 22 ++---------- src/content/docs/useform/seterror.mdx | 10 +++--- src/content/docs/useform/setvalue.mdx | 16 --------- src/content/docs/useform/subscribe.mdx | 9 +---- src/content/docs/useformstate.mdx | 6 +++- .../docs/useformstate/formstatesubscribe.mdx | 19 +++++----- src/content/docs/usewatch.mdx | 8 +++++ 12 files changed, 80 insertions(+), 89 deletions(-) diff --git a/src/content/docs/usecontroller/controller.mdx b/src/content/docs/usecontroller/controller.mdx index 74ddb7360..c761466d9 100644 --- a/src/content/docs/usecontroller/controller.mdx +++ b/src/content/docs/usecontroller/controller.mdx @@ -23,6 +23,7 @@ React Hook Form은 비제어 컴포넌트와 기본 입력 요소를 지향하 | `shouldUnregister` | boolean = false` | | 입력 값은 언마운트 후에 등록이 해제(unregistered)되며, 기본값도 제거됩니다.

**참고:** 이 prop은 `useFieldArray`와 함께 사용하지 않아야 합니다. 입력 값이 언마운트/리마운트 및 재정렬된 후에 `unregister`함수가 호출되기 때문입니다. | | `disabled` | boolean = false` | | `disabled` prop은 `field` prop에서 반환됩니다. 제어 입력 필드는 비활성화되며, 그 값은 제출 데이터에서 제외됩니다. | | `defaultValue` | unknown | | **중요:** `useForm`의 `defaultValues` 또는 `defaultValue`에 `undefined`를 적용할 수 없습니다. | +| `exact` | boolean = false | | 이 속성(prop)은 인풋 이름 구독에 대한 정확한 일치를 활성화하며, 기본값은 true입니다. | `exact` | boolean = false | | 이 속성은 인풋 이름 구독에 대해 정확한 일치를 활성화합니다. 기본값은 `true`입니다. | ### Return diff --git a/src/content/docs/useform.mdx b/src/content/docs/useform.mdx index 99c076eff..151e798cd 100644 --- a/src/content/docs/useform.mdx +++ b/src/content/docs/useform.mdx @@ -94,8 +94,10 @@ sidebar: apiLinks | [criteriaMode](#criteriaMode) | 모든 유효성 검사 에러를 한 번에 노출하거나 하나씩 노출. | | [shouldFocusError](#shouldFocusError) | 내장된 포커스 관리를 활성화하거나 비활성화. | | [delayError](#delayError) | 에러가 즉시 나타나는 것을 지연. | +| [validate](#validate) | 폼 수준 검증은 내장 검증 메서드로 제한됩니다. | | [shouldUseNativeValidation](#shouldUseNativeValidation) | 브라우저 내장 폼 제약 조건 API 사용. | | [shouldUnregister](#shouldUnregister) | 언마운트 후 입력의 등록 취소(unregister)를 활성화하거나 비활성화. | +| [progressive](/docs/useform/form) | `Form` 컴포넌트를 사용할 때 네이티브 폼 제출에 대한 점진적 개선을 활성화합니다. | | [disabled](#disabled) | 전체 폼과 해당 폼에 포함된 모든 입력을 비활성화합니다. | **스키마 유효성 검사 속성:** @@ -277,6 +279,39 @@ useForm({ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | 이 설정은 에러 상태가 사용자에게 표시되는 것을 지정된 밀리초만큼 지연시킵니다. 만약 사용자가 에러가 발생한 입력을 수정하면 에러는 즉시 제거되며, 지연이 적용되지 않습니다. | | +#### validate: Function {#validate} + +--- + +이 예제는 **새로운 `validate` API**를 `useForm`과 결합하여 **폼 수준 검증**을 React 애플리케이션에서 수행하는 방법을 보여줍니다. + +`validate` 함수는 전체 폼 객체를 수신하며, `formState.errors`와 통합되는 **구조화된 에러**를 반환할 수 있습니다. + +**Examples:** + +--- + +```javascript copy +const { + register, + formState: { errors }, +} = useForm({ + validate: async ({ formValues }: FormValidateResult) => { + if (formValues.test1.length > formValues.test.length) { + return { + type: "formError", + message: "무언가 잘못되었습니다.", + } + } + + if (formValue.test === "test") { + return "직접적인 에러 메시지" + } + + return true + }, +}) + #### shouldUnregister: boolean = false {#shouldUnregister} --- diff --git a/src/content/docs/useform/clearerrors.mdx b/src/content/docs/useform/clearerrors.mdx index 656695d11..28c2ddb93 100644 --- a/src/content/docs/useform/clearerrors.mdx +++ b/src/content/docs/useform/clearerrors.mdx @@ -32,8 +32,8 @@ sidebar: apiLinks -- 이 메서드는 각 입력 필드에 연결된 유효성 검사 규칙에는 영향을 주지 않습니다. -- 이 메서드는 유효성 검사 규칙이나 `isValid` formState에는 영향을 미치지 않습니다. +- 이 메서드는 인풋에 연결된 검증 규칙에 영향을 주지 않으며, formState.isValid에 영향을 미치지 않습니다. + diff --git a/src/content/docs/useform/handlesubmit.mdx b/src/content/docs/useform/handlesubmit.mdx index 4d2b9e043..49852112c 100644 --- a/src/content/docs/useform/handlesubmit.mdx +++ b/src/content/docs/useform/handlesubmit.mdx @@ -19,15 +19,6 @@ sidebar: apiLinks -- handleSubmit을 사용하면 폼을 비동기적으로 쉽게 제출할 수 있습니다. - - ```javascript copy - handleSubmit(onSubmit)() - - // 비동기 유효성 검사를 위해 async 함수를 전달할 수 있습니다. - handleSubmit(async (data) => await fetchAPI(data)) - ``` - - `disabled`된 입력은 폼 값에서 `undefined`로 나타납니다. 입력을 사용자가 수정하지 못하게 하면서 값을 유지하려면, `readOnly`를 사용하거나 전체 <fieldset />을 disabled할 수 있습니다. [예시](https://codesandbox.io/s/react-hook-form-disabled-inputs-oihxx)를 참고하세요. - `handleSubmit` 함수는 onSubmit 콜백 내부에서 발생한 에러를 처리하지 않으므로, 비동기 요청에서 에러를 처리할 때는 try-catch를 사용하여 유저에게 에러를 친절하게 처리해 주는 것을 권장합니다. diff --git a/src/content/docs/useform/register.mdx b/src/content/docs/useform/register.mdx index e2f4f7a79..7e4c14730 100644 --- a/src/content/docs/useform/register.mdx +++ b/src/content/docs/useform/register.mdx @@ -102,32 +102,28 @@ By selecting the register option, the API table below will get updated.
  • - 이름은 **필수**이며 **고유**해야 합니다(기본 라디오 및 체크박스 제외). - 입력 이름은 점과 대괄호 구문을 모두 지원하므로 중첩된 폼 필드를 쉽게 만들 수 있습니다. -
    • +Name은 필수이며 고유해야 합니다 +(네이티브 라디오 및 체크박스 인풋을 제외하고).
  • 이름은 은 숫자로 시작하거나 키 이름으로 숫자를 사용할 수 없습니다. 특수 문자의 사용도 피해야 합니다. -
    • -
  • - TypeScript 사용 시 일관성을 위해 점 구문만을 사용하고 있으므로, 배열 폼 값에는 대괄호 `[]` 를 사용할 수 없습니다. - -```javascript -register('test.0.firstName'); // ✅ -register('test[0]firstName'); // ❌ -``` +이름은 숫자로 시작하거나 숫자를 단독 키로 사용할 수 없으며, 특수 문자는 피해야 합니다. +TypeScript의 일관성을 위해 점(dot) 구문만 지원되며, 대괄호 구문([])은 배열 폼 값에 대해 작동하지 않습니다. -
    • +``` +register("test.0.firstName") // ✅ +register("test[0].firstName") // ❌
  • 비활성화된 입력은 undefined 폼 값을 결과로 제공합니다. 사용자가 입력을 업데이트하지 못하도록 하려면 `readOnly`를 사용하거나 전체 `fieldset`을 비활성화할 수 있습니다. 다음은 [예제](https://codesandbox.io/s/react-hook-form-disabled-inputs-oihxx)입니다.
  • 필드 배열을 생성하려면 입력 이름 뒤에 점과 숫자를 붙여야 합니다. 예: `test.0.data`
    • - -
  • 렌더링할 때마다 이름을 변경하면 새로운 입력이 등록(registered)됩니다. 따라서 각 등록된(registered) 입력에 대해 고정된 이름을 사용하는 것이 좋습니다.
    • - +
  • 비활성화된 인풋은 폼 값으로 undefined를 반환합니다. + 값은 유지하면서 사용자 수정을 방지해야 할 경우, readOnly를 사용하거나 전체 fieldset을 비활성화하세요. [예제](https://codesandbox.io/s/react-hook-form-disabled-inputs-oihxx)가 있습니다.
    • +
  • 각 렌더링에서 인풋의 name을 변경하면 새로운 필드로 다시 등록됩니다.
  • 언마운트에 따라 입력 값과 참조는 더 이상 제거되지 않습니다. 해당 값과 참조를 제거하려면 unregister를 호출할 수 있습니다.
    • - + 일관된 동작을 보장하기 위해 렌더링 간 입력 이름을 안정적으로 유지하세요. +
  • 인풋 값과 참조는 언마운트 시 자동으로 제거되지 않습니다.
  • - 개별 register 옵션은 `undefined`나 `{}`로 제거할 수 없습니다. 대신 개별 속성을 업데이트할 수 있습니다. + 필요할 경우 명시적으로 제거하기 위해 unregister를 사용하세요.
    • ```javascript register('test', { required: true }); diff --git a/src/content/docs/useform/reset.mdx b/src/content/docs/useform/reset.mdx index bec0c18f3..2b9fcb67c 100644 --- a/src/content/docs/useform/reset.mdx +++ b/src/content/docs/useform/reset.mdx @@ -29,26 +29,8 @@ sidebar: apiLinks -- 제어 컴포넌트의 경우 `defaultValues`를 `useForm`에 전달해야 `Controller` 컴포넌트의 값을 `reset`할 수 있습니다. -- `reset` API에 `defaultValues`가 제공되지 않으면, HTML 기본 [reset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reset) API가 호출되어 폼이 복원됩니다. -- `useForm`의 `useEffect`가 호출되기 전에 `reset`을 호출하는 것을 피하세요. 이는 `useForm`의 구독이 준비된 후에만 `reset`이 신호를 보내 폼 상태 업데이트를 flush할 수 있기 때문입니다. -- submission 후 `useEffect` 내부에서 `reset`을 호출하는 것이 좋습니다. - ```javascript - useEffect(() => { - reset({ - data: "test", - }) - }, [isSubmitSuccessful]) - ``` -- `defaultValues`를 useForm에 제공한 경우, 인자 없이 `reset`을 실행하는 것도 가능합니다. - - ```javascript - reset() // 폼을 기본값으로 다시 업데이트 - - reset({ test: "test" }) // 기본값과 폼 값을 업데이트 - - reset(undefined, { keepDirtyValues: true }) // 다른 폼 상태를 초기화하지만 기본값과 폼 값을 유지 - ``` +- 폼을 초기화할 때는 항상 defaultValues를 제공하는 것이 권장됩니다. + 이렇게 하면 모든 인풋, 특히 제어 컴포넌트가 올바르게 복원됩니다. diff --git a/src/content/docs/useform/seterror.mdx b/src/content/docs/useform/seterror.mdx index a06e1de9a..99cdccdaa 100644 --- a/src/content/docs/useform/seterror.mdx +++ b/src/content/docs/useform/seterror.mdx @@ -36,14 +36,12 @@ sidebar: apiLinks setError("root.serverError", { type: "400", }) - setError("root.random", { - type: "random", - }) ``` -- 이 메서드는 비동기 유효성 검사 후, 사용자에게 에러 피드백을 제공하려는 경우, `handleSubmit` 메서드에서 유용할 수 있습니다. (예: API에서 유효성 검사 에러 반환 시) - `shouldFocus`는 입력 필드가 비활성화된 경우 작동하지 않습니다. -- 이 메서드는 `isValid` 폼 상태를 `false`로 강제 설정합니다. 그러나 `isValid`는 항상 입력 등록 규칙 또는 스키마 결과의 유효성 검사 결과에서 파생된다는 점에 유의해야 합니다. -- 타입 검사를 방해하지 않기 위해 `type`과 `types`라는 키워드는 피해야 합니다. +- 이 메서드는 formState.isValid를 false로 강제 설정합니다. + 그러나 isValid는 항상 등록된 인풋 또는 스키마의 검증 결과에서 파생됩니다. + +- 타입 체크와의 충돌을 방지하기 위해 피해야 할 특정 키워드가 있습니다. diff --git a/src/content/docs/useform/setvalue.mdx b/src/content/docs/useform/setvalue.mdx index a022a8645..401bd10db 100644 --- a/src/content/docs/useform/setvalue.mdx +++ b/src/content/docs/useform/setvalue.mdx @@ -35,22 +35,6 @@ sidebar: apiLinks setValue("array.0.test2", "2") ``` -- 존재하지 않는 필드를 대상으로 지정하면 이 메서드는 새 필드를 생성하지 않습니다. - - ```javascript - const { replace } = useFieldArray({ name: "test" }) - - // ❌ 새로운 입력 필드를 생성하지 않음 - setValue("test.101.data") - - // ✅ 전체 필드 배열을 새로 고침 - replace([{ data: "test" }]) - ``` - -- 다음 조건에서만 리렌더링이 트리거됩니다: - - - 값 업데이트로 인해 에러가 발생하거나 수정된 경우. - - `setValue`가 dirty나 touched와 같은 상태 업데이트를 유발하는 경우. - 두 번째 인자를 중첩된 객체로 만드는 것보다 필드 이름을 대상으로 설정하는 것이 좋습니다. diff --git a/src/content/docs/useform/subscribe.mdx b/src/content/docs/useform/subscribe.mdx index a52caa577..28de94e62 100644 --- a/src/content/docs/useform/subscribe.mdx +++ b/src/content/docs/useform/subscribe.mdx @@ -6,7 +6,7 @@ sidebar: apiLinks ## `subscribe:` `UseFormSubscribe` -[`formState`](/docs/useform/formState) 변경사항과 값 업데이트를 구독합니다. 개별 필드나 전체 폼을 구독할 수 있으며, 폼 변경으로 인한 불필요한 리렌더링을 방지할 수 있습니다. +[`formState`](/docs/useform/formstate) 변화 및 값 업데이트를 구독할 수 있습니다. 개별 필드 또는 전체 폼에 구독할 수 있으며, 폼 변화로 인한 불필요한 리렌더링을 피할 수 있습니다. ### Props @@ -23,13 +23,6 @@ sidebar: apiLinks
      -
    • -

      - 이 함수는 변경사항 구독만을 위한 것이며, 상태 업데이트 dispatch나 리렌더링 - 트리거는 허용되지 않습니다. 예: `setValue` 또는 `reset` -

      -
      • -

    • 이 함수는 createFormControl.subscribe와 동일한 기능을 공유합니다. 다만 [createFormControl](/docs/createFormControl)은 React diff --git a/src/content/docs/useformstate.mdx b/src/content/docs/useformstate.mdx index dbda9c9fa..4ca9c7a31 100644 --- a/src/content/docs/useformstate.mdx +++ b/src/content/docs/useformstate.mdx @@ -7,9 +7,13 @@ sidebar: apiLinks `FormStateSubscribe:` Component -`useFormState`와 동일한 기능을 컴포넌트 형태로 제공하는 React Hook Form 컴포넌트입니다. 다른 컴포넌트 내부에서 훅을 사용하는 대신, ``를 JSX에서 직접 사용하여 폼 상태를 구독하고 렌더링할 수 있습니다. +React Hook Form 컴포넌트로, `useFormState`와 동일한 기능을 제공하지만 컴포넌트 형태로 제공됩니다. 다른 컴포넌트 안에서 훅을 사용하는 대신, JSX에서 ``를 직접 사용하여 폼 상태에 구독하고 렌더링할 수 있습니다. ### Props --- -| Name | Type | Description | -| ---------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `control` | Object | `useForm`에서 제공하는 [`control`](/docs/useform/control) 객체입니다. `FormProvider`를 사용하는 경우 선택 사항입니다. | -| `name` | string \| string[] | 단일 인풋 이름, 인풋 이름 배열을 제공하거나, 모든 인풋의 formState 업데이트를 구독합니다. | -| `disabled` | boolean = false | 구독을 비활성화하는 옵션입니다. | -| `exact` | boolean = false | 이 속성은 인풋 이름 구독에 대해 정확한 일치를 활성화합니다. | -| `render` | Function | 지정된 폼 필드의 폼 상태를 구독하고, 폼 상태가 변경될 때마다 자식 함수를 리렌더링합니다. 이를 통해 상태를 수동으로 연결하지 않고도 JSX에서 선언적으로 폼 상태를 사용할 수 있습니다. | +| Name | Type | Description | +| ---------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `control` | Object | [`control`](/docs/useform/control) 객체로, `useForm`에서 제공됩니다. `FormProvider`를 사용하고 있다면 선택 사항입니다. | +| `name` | string \| string[] | 단일 인풋 이름, 배열 또는 모든 인풋의 formState 업데이트에 구독할 수 있습니다. | +| `disabled` | boolean = false | 구독 기능을 비활성화할 옵션입니다. | +| `exact` | boolean = false | 이 속성은 인풋 이름 구독에 대한 정확한 일치를 활성화합니다. | +| `render` | Function | 지정된 폼 필드의 폼 상태에 구독하고, 폼 상태가 변경될 때마다 자식 함수를 리렌더링합니다. 이를 통해 상태를 수동으로 연결하지 않고 JSX에서 선언적으로 폼 상태를 사용할 수 있습니다. | **Examples:** @@ -45,4 +45,3 @@ const App = () => { ) } -``` diff --git a/src/content/docs/usewatch.mdx b/src/content/docs/usewatch.mdx index ed61ce9a4..244bd4075 100644 --- a/src/content/docs/usewatch.mdx +++ b/src/content/docs/usewatch.mdx @@ -4,6 +4,14 @@ description: 입력의 변경을 구독하기 위한 React 훅 sidebar: apiLinks --- + ## \ `useWatch:` `({ control?: Control, name?: string, defaultValue?: unknown, disabled?: boolean }) => object` `watch` API와 유사하게 동작하지만, 이 훅은 리렌더링을 커스텀 훅 레벨에서 격리하여 애플리케이션의 성능을 향상시킬 수 있습니다.