Vue Form API

Form의 Vue 컴포넌트, prop, slot, 이벤트, 함수와 공개 타입을 확인합니다.

Vue 폼 안내로 돌아가기

API

Vue 패키지: @sectile/vue/form

컴포넌트

• FormRoot
• FormSelector
• FormFieldSelector
• FormField
• FormLabel
• FormDescription
• FormMessage
• FormSummary
• FormReset
• FormSubmit

고급 컨트롤 프리셋

• compositeControlCapabilities
• hiddenInputSubmissionCapabilities
• hiddenSelectSubmissionCapabilities
• hiddenValueSubmissionCapabilities
• nativeInputControlCapabilities

함수

defineFormSubmission

function defineFormSubmission<const Schema extends FormSchema<object, object>>(definition: FormSchemaSubmissionDefinition<Schema>): FormSchemaSubmissionDefinition<Schema>

useFormSelector

function useFormSelector<Selected>(selector: FormSelectorFunction<Selected>, options: FormSubscribeOptions<Selected> = {}): Readonly<ShallowRef<Selected>>

useFormFieldSelector

function useFormFieldSelector<Selected>(id: string, selector: FormFieldSelectorFunction<Selected>, options: FormSubscribeOptions<Selected> = {}): Readonly<ShallowRef<Selected>>

useFormFieldController

function useFormFieldController(id: string): FormFieldController

provideFormControlOwner

function provideFormControlOwner(): void

useCompositeFormControl

function useCompositeFormControl(options: {
  readonly root: FormElementSource;
  readonly focusTarget?: FormElementSource;
  readonly validationTarget?: FormElementSource;
  readonly submissions?: FormSubmissionSource;
  readonly labelMode?: FormLabelMode;
  readonly reset?: () => void;
  readonly getValue?: () => unknown;
  readonly isValueEqual?: (current: unknown, baseline: unknown) => boolean;
}): FormControlParticipation

useFormControl

function useFormControl(registration: FormControlRegistration): FormControlParticipation

useNativeInputFormControl

function useNativeInputFormControl(element: Readonly<ShallowRef<HTMLInputElement | HTMLTextAreaElement | null | undefined>>, options: {
    readonly reset?: () => void;
    readonly getValue?: () => unknown;
    readonly isValueEqual?: (current: unknown, baseline: unknown) => boolean;
  } = {}): FormControlParticipation

Props

FormRootProps

issues

타입readonly FormIssueInput[] | undefined기본값[]

애플리케이션이 제공하는 검증 이슈입니다.

mapSubmitError

타입FormSubmitErrorMapper | undefined기본값undefined

제출 중 throw 또는 reject된 오류를 사용자에게 노출해도 되는 failure로 변환하는 함수입니다.

onSubmit

타입FormSubmitHandler<Output> | undefined기본값undefined

검증을 통과한 네이티브 제출을 처리하고 성공, 제출 failure 또는 서버 이슈를 반환하는 함수입니다.

revalidateOn

타입readonly FormInteractionValidationTrigger[] | undefined기본값['input']

검증 실패 후 기존 검증 의도를 다시 수행할 사용자 조작 이벤트입니다.

schema

타입FormSchema<Input, Output> | undefined기본값undefined

최종 제출 검증과 출력 변환에 사용할 Standard Schema입니다.

validate

타입FormValidateHandler<Input> | undefined기본값undefined

현재 필드를 검증하고 애플리케이션 이슈를 반환하는 함수입니다.

validateOn

타입readonly FormInteractionValidationTrigger[] | undefined기본값[]

첫 제출 전 검증을 수행할 사용자 조작 이벤트입니다.

FormFieldProps

as

타입PrimitiveAs | undefined기본값undefined

이 파트가 렌더링할 요소 또는 컴포넌트입니다.

asChild

타입boolean | undefined기본값undefined

하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.

disabled

타입boolean | undefined기본값undefined

사용자 조작을 막을지 여부입니다.

form

타입string | undefined기본값undefined

컨트롤을 연결할 네이티브 form 요소의 ID입니다.

id

타입string | undefined기본값undefined

관련 파트를 연결하는 안정적인 ID입니다.

name

타입FormFieldPath | undefined기본값undefined

네이티브 폼 제출에 사용할 이름입니다.

readonly

타입boolean | undefined기본값undefined

값 확인만 허용하는 읽기 전용 상태 여부입니다.

required

타입boolean | undefined기본값undefined

제출 전에 올바른 값이 반드시 있어야 하는지 여부입니다.

FormSelectorProps

equals

타입((previous: Selected, next: Selected) => boolean) | undefined기본값undefined

선택한 두 상태 스냅샷이 같은지 판정하는 함수입니다.

select

타입FormSelectorFunction<Selected>기본값필수

슬롯에 노출할 폼 또는 필드 상태를 선택하는 함수입니다.

FormFieldSelectorProps

equals

타입((previous: Selected, next: Selected) => boolean) | undefined기본값undefined

선택한 두 상태 스냅샷이 같은지 판정하는 함수입니다.

id

타입string기본값필수

관련 파트를 연결하는 안정적인 ID입니다.

select

타입FormFieldSelectorFunction<Selected>기본값필수

슬롯에 노출할 폼 또는 필드 상태를 선택하는 함수입니다.

FormPartProps

as

타입PrimitiveAs | undefined기본값파트별로 다름

이 파트가 렌더링할 요소 또는 컴포넌트입니다.

asChild

타입boolean | undefined기본값false

하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.

슬롯

FormRootSlotProps

dirty

타입boolean

현재 값이 기준값과 다른지 여부입니다.

reinitialize

타입FormReinitializeAction

현재 값을 새 변경 기준으로 삼고, 유지하도록 지정하지 않은 폼 상태를 초기화하는 함수입니다.

replaceIssues

타입FormReplaceIssuesAction

한 출처의 검증 이슈를 바꾸는 함수입니다.

reset

타입FormResetAction

네이티브 form reset을 실행하고 Form 상태를 비웁니다. 제어 값은 계속 애플리케이션이 관리합니다.

state

타입FormState

현재 전체 폼 상태입니다.

submission

타입FormSubmissionState

현재 제출 생명주기 스냅샷입니다.

submitCount

타입number

submission.count에서 계산한 제출 시도 횟수입니다.

submitFailed

타입FormSubmitFailedAction

식별한 제출을 실패로 기록하는 함수입니다.

submitStarted

타입FormSubmitStartedAction

제출을 시작하고 generation 토큰을 반환하는 함수입니다.

submitSucceeded

타입FormSubmitSucceededAction

식별한 제출을 성공으로 기록하는 함수입니다.

submitted

타입boolean

제출을 시도했는지 여부입니다.

touched

타입boolean

사용자가 필드를 조작했는지 여부입니다.

valid

타입boolean

현재 입력의 검증 통과 여부입니다.

validation

타입FormValidationState

현재 검증 생명주기 스냅샷입니다.

FormFieldSlotProps

clearIssues

타입(source?: FormIssueSource) => boolean

현재 필드의 검증 이슈를 비우는 함수입니다.

controlId

타입string

시맨틱 컨트롤에 지정한 ID입니다.

describedBy

타입string

컨트롤을 설명하는 공백 구분 ID입니다.

descriptionId

타입string

필드 도움말에 지정한 ID입니다.

dirty

타입boolean

현재 값이 기준값과 다른지 여부입니다.

id

타입string

현재 필드 또는 항목의 안정적인 ID입니다.

issues

타입readonly FormIssue[]

현재 canonical 검증 이슈입니다.

labelId

타입string

필드 레이블에 지정한 ID입니다.

messageId

타입string

필드 오류 메시지에 지정한 ID입니다.

relatedIssues

타입readonly FormIssue[]

다른 필드가 소유하지만 현재 필드도 무효로 만드는 이슈입니다.

removeIssue

타입(issueId: string | number) => boolean

ID로 필드 이슈 하나를 제거하는 함수입니다.

replaceIssues

타입(source: FormIssueSource, issues: readonly FormIssue[]) => boolean

한 출처의 검증 이슈를 바꾸는 함수입니다.

setMeta

타입(meta: FormFieldMetaInput) => boolean

현재 필드의 수정 가능한 메타 상태를 갱신하는 함수입니다.

touched

타입boolean

사용자가 필드를 조작했는지 여부입니다.

upsertIssue

타입(issue: FormIssue) => boolean

필드 이슈 하나를 추가하거나 교체하는 함수입니다.

valid

타입boolean

현재 입력의 검증 통과 여부입니다.

FormSummarySlotProps

firstIssue

타입FormIssue | null

첫 canonical 이슈이며 없으면 null입니다.

issues

타입readonly FormIssue[]

현재 canonical 검증 이슈입니다.

serverIssues

타입readonly FormIssue[]

현재 canonical 서버 이슈입니다.

submission

타입FormSubmissionState

현재 제출 생명주기 스냅샷입니다.

valid

타입boolean

현재 입력의 검증 통과 여부입니다.

validation

타입FormValidationState

현재 검증 생명주기 스냅샷입니다.

FormSubmitSlotProps

canSubmit

타입boolean

폼이 유효하고 제출 중이 아닌지 여부입니다.

submission

타입FormSubmissionState

현재 제출 생명주기 스냅샷입니다.

submitting

타입boolean

폼 제출이 진행 중인지 여부입니다.

valid

타입boolean

현재 입력의 검증 통과 여부입니다.

이벤트

FormSubmitEvent

이름	타입	필수
formData	FormData	필수
values	Readonly<Values>	필수
submitter	HTMLElement | null	필수
state	FormState	필수
reinitialize	(options?: FormReinitializeOptions) => void	필수
nativeEvent	SubmitEvent	필수
defaultPrevented	boolean	필수
preventDefault	() => void	필수
stopPropagation	() => void	필수
stopImmediatePropagation	() => void	필수

기타 타입

FormState

이름	타입	필수
validation	FormValidationState	필수
submission	FormSubmissionState	필수
touched	boolean	필수
dirty	boolean	필수
valid	boolean	필수
fields	readonly FormFieldState<string>[]	필수
issues	readonly FormIssue<string>[]	필수
allIssues	readonly FormIssue<string>[]	필수

FormFieldState

이름	타입	필수
id	string	필수
name	string | null	필수
touched	boolean	필수
dirty	boolean	필수
valid	boolean	필수
issues	readonly FormIssue<string>[]	필수
relatedIssues	readonly FormIssue<string>[]	필수

FormFieldMetaInput

이름	타입	필수
name	string | null | undefined	—
touched	boolean | undefined	—
dirty	boolean | undefined	—

FormSubscribeOptions

이름	타입	필수
equals	((previous: Selected, next: Selected) => boolean) | undefined	—

FormSelectorFunction

type FormSelectorFunction<Selected> = (state: FormState) => Selected

FormFieldSelectorFunction

type FormFieldSelectorFunction<Selected> = (field: FormFieldState | null) => Selected

FormIssue

이름	타입	필수
id	StableID	필수
message	string	필수
source	FormIssueSource	필수
fieldId	string | undefined	—
relatedFieldIds	readonly string[] | undefined	—

FormIssueSource

type FormIssueSource = 'native' | 'field' | 'form' | 'validate' | 'schema' | 'server'

FormReinitializeOptions

이름	타입	필수
preserve	{ readonly touched?: boolean; readonly validation?: boolean; readonly submission?: boolean; } | undefined	—

FormValues

type FormValues<Shape extends object = Record<string, unknown>> = Readonly<Shape>

FormSchema

type FormSchema<Input extends object = Record<string, unknown>, Output extends object = Input> = StandardSchemaV1<FormValues<Input>, FormValues<Output>>

FormSchemaInput

type FormSchemaInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>

FormSchemaOutput

type FormSchemaOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>

FormIssueInput

이름	타입	필수
id	string | undefined	—
message	string	필수
path	FormFieldPath | undefined	—
relatedPaths	readonly FormFieldPath[] | undefined	—

FormSubmitIssue

type FormSubmitIssue = FormIssueInput

FormSubmitResult

type FormSubmitResult =
| void
  | { readonly ok: true }
  | {
      readonly ok: false;
      readonly failure?: FormSubmissionFailure;
      readonly issues?: readonly FormSubmitIssue[];
    }

FormSubmitHandler

type FormSubmitHandler<Values extends object = Record<string, unknown>> = (event: FormSubmitEvent<Values>) => FormSubmitResult | PromiseLike<FormSubmitResult>

FormSubmissionDefinition

이름	타입	필수
schema	undefined	—
onSubmit	FormSubmitHandler<Record<string, unknown>>	필수

FormSchemaSubmissionDefinition

이름	타입	필수
schema	Schema	필수
onSubmit	FormSubmitHandler<FormSchemaOutput<Schema>>	필수

FormSubmitErrorMapper

type FormSubmitErrorMapper =
(
  reason: unknown,
) => FormSubmissionFailure | undefined

FormResetHandler

type FormResetHandler = () => void

FormStateChangeHandler

type FormStateChangeHandler = (state: FormState) => void

FormInteractionValidationTrigger

type FormInteractionValidationTrigger = Exclude<FormValidationTrigger, 'submit'>

FormValidateContext

이름	타입	필수
trigger	FormValidationTrigger	필수
intent	FormValidationIntent	필수
changedFieldId	string | null	필수
signal	AbortSignal	필수

FormValidationIssue

이름	타입	필수
message	string	필수
path	FormFieldPath | undefined	—
relatedPaths	readonly FormFieldPath[] | undefined	—

FormValidationResult

이름	타입	필수
issues	readonly FormValidationIssue[] | undefined	—

FormValidateHandler

type FormValidateHandler<Values extends object = Record<string, unknown>> =
(
  values: FormValues<Values>,
  context: FormValidateContext,
) => FormValidationResult | PromiseLike<FormValidationResult>

FormSubmitStartedAction

type FormSubmitStartedAction = () => number | null

FormSubmitSucceededAction

type FormSubmitSucceededAction = (generation: number) => boolean

FormSubmitFailedAction

type FormSubmitFailedAction =
(
  generation: number,
  result: {
    readonly failure?: FormSubmissionFailure;
    readonly issues?: readonly FormIssue[];
  },
) => boolean

FormReplaceIssuesAction

type FormReplaceIssuesAction =
(
  source: FormIssueSource,
  issues: readonly FormIssue[],
) => boolean

FormResetAction

type FormResetAction = () => void

FormReinitializeAction

type FormReinitializeAction = (options?: FormReinitializeOptions) => void

FormRootComponent

interface FormRootComponent {
  new <Input extends object = Record<string, unknown>, Output extends object = Input>(props: FormRootPublicProps<Input, Output>): {
    $props: FormRootPublicProps<Input, Output>;
    $slots: {
      default?: (props: FormRootSlotProps) => VNodeChild;
    };
    submitStarted: FormSubmitStartedAction;
    submitSucceeded: FormSubmitSucceededAction;
    submitFailed: FormSubmitFailedAction;
    replaceIssues: FormReplaceIssuesAction;
    reinitialize: FormReinitializeAction;
    reset: FormResetAction;
  };
}

FormFieldController

이름	타입	필수
state	Readonly<ShallowRef<FormFieldState | null>>	필수
setMeta	(meta: FormFieldMetaInput) => boolean	필수
replaceIssues	(source: FormIssueSource, issues: readonly FormIssue[]) => boolean	필수
upsertIssue	(issue: FormIssue) => boolean	필수
removeIssue	(issueId: string | number) => boolean	필수
clearIssues	(source?: FormIssueSource) => boolean	필수

FormSelectorComponent

interface FormSelectorComponent {
  new <Selected>(props: FormSelectorProps<Selected>): {
    $props: FormSelectorProps<Selected>;
    $slots: { default?: (props: { readonly selected: Selected }) => VNodeChild };
  };
}

FormFieldSelectorComponent

interface FormFieldSelectorComponent {
  new <Selected>(props: FormFieldSelectorProps<Selected>): {
    $props: FormFieldSelectorProps<Selected>;
    $slots: { default?: (props: { readonly selected: Selected }) => VNodeChild };
  };
}

FormControlCapabilities

이름	타입	필수
id	boolean | undefined	—
describedBy	boolean | undefined	—
invalid	boolean | undefined	—
labelledBy	boolean | undefined	—
required	boolean | undefined	—
disabled	boolean | undefined	—
readonly	boolean | undefined	—

FormControlParticipation

이름	타입	필수
participating	boolean	필수
controlProps	ComputedRef<Readonly<Record<string, unknown>>>	필수

FormControlRegistration

이름	타입	필수
element	FormElementSource<HTMLElement>	필수
semanticControl	FormElementSource<HTMLElement> | undefined	—
focusTarget	FormElementSource<HTMLElement> | undefined	—
validationTarget	FormElementSource<HTMLElement> | undefined	—
submissions	FormSubmissionSource | undefined	—
labelMode	FormLabelMode | undefined	—
capabilities	FormControlCapabilities | undefined	—
explicit	readonly FormMetadataAttribute[] | undefined	—
reset	(() => void) | undefined	—
getValue	(() => unknown) | undefined	—
isValueEqual	((current: unknown, baseline: unknown) => boolean) | undefined	—

FormElementSource

type FormElementSource<ElementType extends HTMLElement = HTMLElement> =
| Readonly<ShallowRef<ElementType | null | undefined>>
  | (() => ElementType | null)

FormLabelMode

type FormLabelMode = 'for' | 'labelledby' | 'legend'

FormMetadataAttribute

type FormMetadataAttribute =
| 'id'
  | 'name'
  | 'form'
  | 'required'
  | 'disabled'
  | 'readonly'
  | 'aria-describedby'
  | 'aria-errormessage'
  | 'aria-invalid'
  | 'aria-labelledby'
  | 'aria-disabled'
  | 'aria-required'
  | 'aria-readonly'

FormSubmissionCapabilities

이름	타입	필수
name	boolean | undefined	—
form	boolean | undefined	—
required	boolean | undefined	—
disabled	boolean | undefined	—
readonly	boolean | undefined	—

FormSubmissionRegistration

이름	타입	필수
element	FormElementSource<FormControlSubmissionElement>	필수
relativeName	FormControlRelativePath | undefined	—
capabilities	FormSubmissionCapabilities | undefined	—
explicit	readonly FormMetadataAttribute[] | undefined	—

FormSubmissionSource

type FormSubmissionSource =
| readonly FormSubmissionRegistration[]
  | (() => readonly FormSubmissionRegistration[])