TanStack
Form v1
自动
框架
版本
菜单
入门
指南
API 参考
社区资源
示例

FormApi

类: FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

定义于: packages/form-core/src/FormApi.ts:860

一个代表 Form API 的类。它处理表单状态的逻辑和交互。

通常情况下，您不需要直接创建新的 FormApi 实例。相反，您将使用 useForm 或 createForm 等框架钩子/函数为您创建一个新的实例，该实例使用您框架的响应式模型。但是，如果您需要手动创建新实例，可以通过调用 new FormApi 构造函数来实现。

类型参数

• TFormData

• TOnMount 扩展 undefined | FormValidateOrFn<TFormData>

• TOnChange 扩展 undefined | FormValidateOrFn<TFormData>

• TOnChangeAsync 扩展 undefined | FormAsyncValidateOrFn<TFormData>

• TOnBlur 扩展 undefined | FormValidateOrFn<TFormData>

• TOnBlurAsync 扩展 undefined | FormAsyncValidateOrFn<TFormData>

• TOnSubmit 扩展 undefined | FormValidateOrFn<TFormData>

• TOnSubmitAsync 扩展 undefined | FormAsyncValidateOrFn<TFormData>

• TOnDynamic 扩展 undefined | FormValidateOrFn<TFormData>

• TOnDynamicAsync 扩展 undefined | FormAsyncValidateOrFn<TFormData>

• TOnServer 扩展 undefined | FormAsyncValidateOrFn<TFormData>

• TSubmitMeta = never

实现
  • FieldManipulator<TFormData, TSubmitMeta>

构造函数

new FormApi()

ts
new FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>(opts?): FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

new FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>(opts?): FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

定义于: packages/form-core/src/FormApi.ts:940

使用给定的表单选项构造一个新的 FormApi 实例。

参数
opts?

FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

Returns (返回)

FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

属性

baseStore

ts
baseStore: Store<BaseFormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>>;

baseStore: Store<BaseFormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>>;

定义于: packages/form-core/src/FormApi.ts:892

fieldInfo
ts
fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>>;

fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>>;

定义于: packages/form-core/src/FormApi.ts:926

表单中每个字段的信息记录。

fieldMetaDerived
ts
fieldMetaDerived: Derived<Record<DeepKeys<TFormData>, AnyFieldMeta>>;

fieldMetaDerived: Derived<Record<DeepKeys<TFormData>, AnyFieldMeta>>;

定义于: packages/form-core/src/FormApi.ts:907

options
ts
options: FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> = {};

options: FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> = {};

定义于: packages/form-core/src/FormApi.ts:878

表单的选项。

store
ts
store: Derived<FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>>;

store: Derived<FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>>;

定义于: packages/form-core/src/FormApi.ts:908

访问器

formId

获取签名

ts
get formId(): undefined | string

get formId(): undefined | string

定义于: packages/form-core/src/FormApi.ts:1249

Returns (返回)

undefined | string

state

获取签名

ts
get state(): FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>

get state(): FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>

定义于: packages/form-core/src/FormApi.ts:928

Returns (返回)

FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>

方法

clearFieldValues()

ts
clearFieldValues<TField>(field, opts?): void

clearFieldValues<TField>(field, opts?): void

定义于: packages/form-core/src/FormApi.ts:2291

清除数组字段中的所有值。

类型参数

• TField 扩展 string

参数
field

TField

opts?

UpdateMetaOptions

Returns (返回)

void

实现自
ts
FieldManipulator.clearFieldValues

FieldManipulator.clearFieldValues

deleteField()
ts
deleteField<TField>(field): void

deleteField<TField>(field): void

定义于: packages/form-core/src/FormApi.ts:2099

类型参数

• TField 扩展 string

参数
field

TField

Returns (返回)

void

实现自
ts
FieldManipulator.deleteField

FieldManipulator.deleteField

getAllErrors()
ts
getAllErrors(): object

getAllErrors(): object

定义于: packages/form-core/src/FormApi.ts:2399

返回表单和字段级别的错误

Returns (返回)

object

fields
ts
fields: Record<DeepKeys<TFormData>, {
  errorMap: ValidationErrorMap;
  errors: unknown[];
}>;

fields: Record<DeepKeys<TFormData>, {
  errorMap: ValidationErrorMap;
  errors: unknown[];
}>;
form
ts
form: object;

form: object;
form.errorMap
ts
errorMap: ValidationErrorMap<UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormValidateOrFn<TOnDynamic>, UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>;

errorMap: ValidationErrorMap<UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormValidateOrFn<TOnDynamic>, UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>;
form.errors
ts
errors: (
  | UnwrapFormValidateOrFn<TOnMount>
  | UnwrapFormValidateOrFn<TOnChange>
  | UnwrapFormAsyncValidateOrFn<TOnChangeAsync>
  | UnwrapFormValidateOrFn<TOnBlur>
  | UnwrapFormAsyncValidateOrFn<TOnBlurAsync>
  | UnwrapFormValidateOrFn<TOnSubmit>
  | UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>
  | UnwrapFormValidateOrFn<TOnDynamic>
  | UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>
  | UnwrapFormAsyncValidateOrFn<TOnServer>)[];

errors: (
  | UnwrapFormValidateOrFn<TOnMount>
  | UnwrapFormValidateOrFn<TOnChange>
  | UnwrapFormAsyncValidateOrFn<TOnChangeAsync>
  | UnwrapFormValidateOrFn<TOnBlur>
  | UnwrapFormAsyncValidateOrFn<TOnBlurAsync>
  | UnwrapFormValidateOrFn<TOnSubmit>
  | UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>
  | UnwrapFormValidateOrFn<TOnDynamic>
  | UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>
  | UnwrapFormAsyncValidateOrFn<TOnServer>)[];

getFieldInfo()
ts
getFieldInfo<TField>(field): FieldInfo<TFormData>

getFieldInfo<TField>(field): FieldInfo<TFormData>

定义于: packages/form-core/src/FormApi.ts:2012

获取指定字段的字段信息。

类型参数

• TField 扩展 string

参数
field

TField

Returns (返回)

FieldInfo<TFormData>

getFieldMeta()
ts
getFieldMeta<TField>(field): undefined | AnyFieldMeta

getFieldMeta<TField>(field): undefined | AnyFieldMeta

定义于: packages/form-core/src/FormApi.ts:2003

获取指定字段的元数据。

类型参数

• TField 扩展 string

参数
field

TField

Returns (返回)

undefined | AnyFieldMeta

实现自
ts
FieldManipulator.getFieldMeta

FieldManipulator.getFieldMeta

getFieldValue()
ts
getFieldValue<TField>(field): DeepValue<TFormData, TField>

getFieldValue<TField>(field): DeepValue<TFormData, TField>

定义于: packages/form-core/src/FormApi.ts:1996

获取指定字段的值。

类型参数

• TField 扩展 string

参数
field

TField

Returns (返回)

DeepValue<TFormData, TField>

实现自
ts
FieldManipulator.getFieldValue

FieldManipulator.getFieldValue

handleSubmit()

调用签名

ts
handleSubmit(): Promise<void>

handleSubmit(): Promise<void>

定义于: packages/form-core/src/FormApi.ts:1893

处理表单提交，执行验证，并调用相应的 onSubmit 或 onSubmitInvalid 回调。

Returns (返回)

Promise<void>

实现自
ts
FieldManipulator.handleSubmit

FieldManipulator.handleSubmit

调用签名
ts
handleSubmit(submitMeta): Promise<void>

handleSubmit(submitMeta): Promise<void>

定义于: packages/form-core/src/FormApi.ts:1894

处理表单提交，执行验证，并调用相应的 onSubmit 或 onSubmitInvalid 回调。

参数
submitMeta

TSubmitMeta

Returns (返回)

Promise<void>

实现自
ts
FieldManipulator.handleSubmit

FieldManipulator.handleSubmit

insertFieldValue()
ts
insertFieldValue<TField>(
   field, 
   index, 
   value, 
opts?): Promise<void>

insertFieldValue<TField>(
   field, 
   index, 
   value, 
opts?): Promise<void>

定义于: packages/form-core/src/FormApi.ts:2138

类型参数

• TField 扩展 string

参数
field

TField

index

number

value

DeepValue<TFormData, TField> 扩展 any[] ? any[] & DeepValue<TFormData, TField>[number] : never

opts?

UpdateMetaOptions

Returns (返回)

Promise<void>

实现自
ts
FieldManipulator.insertFieldValue

FieldManipulator.insertFieldValue

mount()
ts
mount(): () => void

mount(): () => void

定义于: packages/form-core/src/FormApi.ts:1278

Returns (返回)

Function

Returns (返回)

void

moveFieldValues()
ts
moveFieldValues<TField>(
   field, 
   index1, 
   index2, 
   opts?): void

moveFieldValues<TField>(
   field, 
   index1, 
   index2, 
   opts?): void

定义于: packages/form-core/src/FormApi.ts:2262

将第一个指定索引的值移动到数组字段中的第二个指定索引。

类型参数

• TField 扩展 string

参数
field

TField

index1

number

index2

number

opts?

UpdateMetaOptions

Returns (返回)

void

实现自
ts
FieldManipulator.moveFieldValues

FieldManipulator.moveFieldValues

parseValuesWithSchema()
ts
parseValuesWithSchema(schema): 
  | undefined
  | {
  fields: Record<string, StandardSchemaV1Issue[]>;
  form: Record<string, StandardSchemaV1Issue[]>;
}

parseValuesWithSchema(schema): 
  | undefined
  | {
  fields: Record<string, StandardSchemaV1Issue[]>;
  form: Record<string, StandardSchemaV1Issue[]>;
}

定义于: packages/form-core/src/FormApi.ts:2463

使用给定的标准模式解析表单值，并返回问题（如果有）。此方法不设置任何内部错误。

参数
schema

StandardSchemaV1<TFormData, unknown>

用于解析表单值的标准模式。

Returns (返回)

| undefined | { fields: Record<string, StandardSchemaV1Issue[]>; form: Record<string, StandardSchemaV1Issue[]>; }

parseValuesWithSchemaAsync()
ts
parseValuesWithSchemaAsync(schema): Promise<
  | undefined
  | {
  fields: Record<string, StandardSchemaV1Issue[]>;
  form: Record<string, StandardSchemaV1Issue[]>;
}>

parseValuesWithSchemaAsync(schema): Promise<
  | undefined
  | {
  fields: Record<string, StandardSchemaV1Issue[]>;
  form: Record<string, StandardSchemaV1Issue[]>;
}>

定义于: packages/form-core/src/FormApi.ts:2475

使用给定的标准模式解析表单值，并返回问题（如果有）。此方法不设置任何内部错误。

参数
schema

StandardSchemaV1<TFormData, unknown>

用于解析表单值的标准模式。

Returns (返回)

Promise<| undefined | { fields: Record<string, StandardSchemaV1Issue[]>; form: Record<string, StandardSchemaV1Issue[]>; }>

pushFieldValue()
ts
pushFieldValue<TField>(
   field, 
   value, 
   opts?): void

pushFieldValue<TField>(
   field, 
   value, 
   opts?): void

定义于: packages/form-core/src/FormApi.ts:2123

将一个值推入数组字段。

类型参数

• TField 扩展 string

参数
field

TField

value

DeepValue<TFormData, TField> 扩展 any[] ? any[] & DeepValue<TFormData, TField>[number] : never

opts?

UpdateMetaOptions

Returns (返回)

void

实现自
ts
FieldManipulator.pushFieldValue

FieldManipulator.pushFieldValue

removeFieldValue()
ts
removeFieldValue<TField>(
   field, 
   index, 
opts?): Promise<void>

removeFieldValue<TField>(
   field, 
   index, 
opts?): Promise<void>

定义于: packages/form-core/src/FormApi.ts:2196

在指定索引处从数组字段中移除一个值。

类型参数

• TField 扩展 string

参数
field

TField

index

number

opts?

UpdateMetaOptions

Returns (返回)

Promise<void>

实现自
ts
FieldManipulator.removeFieldValue

FieldManipulator.removeFieldValue

replaceFieldValue()
ts
replaceFieldValue<TField>(
   field, 
   index, 
   value, 
opts?): Promise<void>

replaceFieldValue<TField>(
   field, 
   index, 
   value, 
opts?): Promise<void>

定义于: packages/form-core/src/FormApi.ts:2170

将一个值替换到数组字段的指定索引处。

类型参数

• TField 扩展 string

参数
field

TField

index

number

value

DeepValue<TFormData, TField> 扩展 any[] ? any[] & DeepValue<TFormData, TField>[number] : never

opts?

UpdateMetaOptions

Returns (返回)

Promise<void>

实现自
ts
FieldManipulator.replaceFieldValue

FieldManipulator.replaceFieldValue

reset()
ts
reset(values?, opts?): void

reset(values?, opts?): void

定义于: packages/form-core/src/FormApi.ts:1368

将表单状态重置为默认值。如果提供了值，则表单将重置为这些值，并且默认值将被更新。

参数
values?

TFormData

用于重置表单的可选值。

opts?

用于控制重置行为的可选选项。

keepDefaultValues?

boolean

Returns (返回)

void

resetField()
ts
resetField<TField>(field): void

resetField<TField>(field): void

定义于: packages/form-core/src/FormApi.ts:2317

重置字段值和元数据为默认状态

类型参数

• TField 扩展 string

参数
field

TField

Returns (返回)

void

实现自
ts
FieldManipulator.resetField

FieldManipulator.resetField

resetFieldMeta()
ts
resetFieldMeta<TField>(fieldMeta): Record<TField, AnyFieldMeta>

resetFieldMeta<TField>(fieldMeta): Record<TField, AnyFieldMeta>

定义于: packages/form-core/src/FormApi.ts:2053

重置每个字段的元数据

类型参数

• TField 扩展 string

参数
fieldMeta

Record<TField, AnyFieldMeta>

Returns (返回)

Record<TField, AnyFieldMeta>

setErrorMap()
ts
setErrorMap(errorMap): void

setErrorMap(errorMap): void

定义于: packages/form-core/src/FormApi.ts:2335

更新表单的 errorMap

参数
errorMap

FormValidationErrorMap<TFormData, UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormValidateOrFn<TOnDynamic>, UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>

Returns (返回)

void

setFieldMeta()
ts
setFieldMeta<TField>(field, updater): void

setFieldMeta<TField>(field, updater): void

定义于: packages/form-core/src/FormApi.ts:2032

更新指定字段的元数据。

类型参数

• TField 扩展 string

参数
field

TField

updater

Updater<AnyFieldMetaBase>

Returns (返回)

void

实现自
ts
FieldManipulator.setFieldMeta

FieldManipulator.setFieldMeta

setFieldValue()
ts
setFieldValue<TField>(
   field, 
   updater, 
   opts?): void

setFieldValue<TField>(
   field, 
   updater, 
   opts?): void

定义于: packages/form-core/src/FormApi.ts:2069

设置指定字段的值，并可选择更新已触碰状态。

类型参数

• TField 扩展 string

参数
field

TField

updater

Updater<DeepValue<TFormData, TField>>

opts?

UpdateMetaOptions

Returns (返回)

void

实现自
ts
FieldManipulator.setFieldValue

FieldManipulator.setFieldValue

swapFieldValues()
ts
swapFieldValues<TField>(
   field, 
   index1, 
   index2, 
   opts?): void

swapFieldValues<TField>(
   field, 
   index1, 
   index2, 
   opts?): void

定义于: packages/form-core/src/FormApi.ts:2233

交换数组字段中指定索引处的值。

类型参数

• TField 扩展 string

参数
field

TField

index1

number

index2

number

opts?

UpdateMetaOptions

Returns (返回)

void

实现自
ts
FieldManipulator.swapFieldValues

FieldManipulator.swapFieldValues

update()
ts
update(options?): void

update(options?): void

定义于: packages/form-core/src/FormApi.ts:1298

更新表单选项和表单状态。

参数
options?

FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

Returns (返回)

void

validateAllFields()
ts
validateAllFields(cause): Promise<unknown[]>

validateAllFields(cause): Promise<unknown[]>

定义于: packages/form-core/src/FormApi.ts:1394

使用给定的验证原因，通过正确的处理程序验证所有字段。

参数
cause

ValidationCause

Returns (返回)

Promise<unknown[]>

实现自
ts
FieldManipulator.validateAllFields

FieldManipulator.validateAllFields

validateArrayFieldsStartingFrom()
ts
validateArrayFieldsStartingFrom<TField>(
   field, 
   index, 
cause): Promise<unknown[]>

validateArrayFieldsStartingFrom<TField>(
   field, 
   index, 
cause): Promise<unknown[]>

定义于: packages/form-core/src/FormApi.ts:1424

使用给定的验证类型，通过正确的处理程序验证表单中指定数组的子项，从给定索引开始直到结束。

类型参数

• TField 扩展 string

参数
field

TField

index

number

cause

ValidationCause

Returns (返回)

Promise<unknown[]>

实现自
ts
FieldManipulator.validateArrayFieldsStartingFrom

FieldManipulator.validateArrayFieldsStartingFrom

validateField()
ts
validateField<TField>(field, cause): unknown[] | Promise<unknown[]>

validateField<TField>(field, cause): unknown[] | Promise<unknown[]>

定义于: packages/form-core/src/FormApi.ts:1465

使用给定的验证类型，通过正确的处理程序验证表单中指定的字段。

类型参数

• TField 扩展 string

参数
field

TField

cause

ValidationCause

Returns (返回)

unknown[] | Promise<unknown[]>

实现自
ts
FieldManipulator.validateField

FieldManipulator.validateField
在 GitHub 上编辑
类 / FieldApi
函数 / formOptions
我们的合作伙伴
Code Rabbit
订阅 Bytes

您的每周 JavaScript 资讯。每周一免费发送给超过 10 万开发者。

Bytes

无垃圾邮件。您可以随时取消订阅。

订阅 Bytes

您的每周 JavaScript 资讯。每周一免费发送给超过 10 万开发者。

Bytes

无垃圾邮件。您可以随时取消订阅。