TanStack Form Preact 提交处理指南onSubmitMeta 元数据传递与 Standard Schema 数据转换【免费下载链接】form Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, and Lit.项目地址: https://gitcode.com/GitHub_Trending/form/form本文围绕 TanStack FormPreact 适配器的提交处理机制展开深入讲解两个核心能力通过onSubmitMeta与form.handleSubmit()向提交回调传递附加数据例如区分“继续填写”与“返回菜单”等不同提交意图以及如何在 Standard Schema 校验之外获得 schema 转换后的输出数据。读完本文你将掌握提交生命周期中meta参数的完整传递链路并能在onSubmit中正确解析 schema 输出类型写出类型安全、可区分多场景提交行为的表单。TanStack Form 是一个 Headless、高性能、类型安全的表单状态管理库支持 TS/JS、React、Vue、Angular、Solid 与 Preact。本文所有示例均基于tanstack/preact-form其底层表单核心由tanstack/form-core提供。提交处理概览handleSubmit 到底做了什么在 Preact 中useForm返回的表单实例直接暴露了form.handleSubmit()。调用它之后底层FormApi._handleSubmit会执行一整套提交流程见 packages/form-core/src/FormApi.ts将isSubmitted重置为false、submissionAttempts加一、isSubmitSuccessful重置为false批量将所有未 touch 的字段标记为已 touch组装submitMetaArg详见下文元数据传递若canSubmit为false且不是开发工具覆盖则触发onSubmitInvalid并中止设置isSubmitting: true依次执行validateAllFields(submit)与validate(submit)任一阶段校验失败都会回调onSubmitInvalid校验通过后触发字段的onSubmit监听器与表单级listeners.onSubmit执行options.onSubmit成功则置isSubmitted: true、isSubmitSuccessful: true失败则抛出错误并保持isSubmitSuccessful: false。一个 Preact 表单的典型接线方式如下参考 examples/preact/simple/src/index.tsxconst form useForm({ defaultValues: { firstName: , lastName: }, onSubmit: async ({ value }) { console.log(value) }, }) return ( form onSubmit{(e) { e.preventDefault() e.stopPropagation() void form.handleSubmit() }} {/* form.Field ... */} button typesubmitSubmit/button /form )注意e.preventDefault()与e.stopPropagation()必不可少它们阻止浏览器原生的表单提交行为将提交控制权完全交给 TanStack Form。向提交处理传递附加数据onSubmitMeta 与 handleSubmit 参数真实业务中同一个表单往往需要多种提交行为例如“保存并继续”与“保存并返回菜单”。TanStack Form 通过onSubmitMeta支持这一场景它定义提交元数据的期望类型与默认值该元数据最终会被传递给onSubmit函数。定义 onSubmitMeta在useForm配置中声明onSubmitMeta即可完整示例见 docs/framework/preact/guides/submission-handling.mdimport { useForm } from tanstack/preact-form type FormMeta { submitAction: continue | backToMenu | null } // Metadata is not required to call form.handleSubmit(). // Specify what values to use as default if no meta is passed const defaultMeta: FormMeta { submitAction: null, } function App() { const form useForm({ defaultValues: { data: , }, // Define what meta values to expect on submission onSubmitMeta: defaultMeta, onSubmit: async ({ value, meta }) { // Do something with the values passed via handleSubmit console.log(Selected action - ${meta.submitAction}, value) }, }) return ( form onSubmit{(e) { e.preventDefault() e.stopPropagation() }} {/* ... */} button typesubmit // Overwrites the default specified in onSubmitMeta onClick{() form.handleSubmit({ submitAction: continue })} Submit and continue /button button typesubmit onClick{() form.handleSubmit({ submitAction: backToMenu })} Submit and back to menu /button /form ) }关键行为onSubmitMeta的类型参数TSubmitMeta是表单泛型的一部分会贯穿useForm→FormApi→onSubmit的整个类型链保证类型安全当form.handleSubmit()不传参时会使用onSubmitMeta提供的默认值调用form.handleSubmit(meta)传入的元数据会覆盖默认值。源码视角meta 的传递链路从源码结构看onSubmitMeta定义在BaseFormOptions中packages/form-core/src/FormApi.tsexport interface BaseFormOptionsin out TFormData, in out TSubmitMeta never { /** * Set initial values for your form. */ defaultValues?: TFormData /** * onSubmitMeta, the data passed from the handleSubmit handler, to the onSubmit function props */ onSubmitMeta?: TSubmitMeta }handleSubmit提供了两个重载无参与带参内部统一转发给_handleSubmitpackages/form-core/src/FormApi.tshandleSubmit(): Promisevoid handleSubmit(submitMeta: TSubmitMeta): Promisevoid handleSubmit(submitMeta?: TSubmitMeta): Promisevoid { return this._handleSubmit(submitMeta) }而元数据的合并逻辑位于_handleSubmit开头packages/form-core/src/FormApi.tsconst submitMetaArg submitMeta ?? (this.options.onSubmitMeta as TSubmitMeta)即显式传入的submitMeta优先否则回退到onSubmitMeta默认值。submitMetaArg随后被一致地传给onSubmitInvalid、listeners.onSubmit与onSubmit回调见_handleSubmit内 L2453、L2522、L2529 等处因此不仅是onSubmit校验失败回调同样能拿到 meta可用于区分失败后的跳转或提示逻辑。Preact 适配器这边useForm返回的扩展 API 中handleSubmit被代理到核心的_handleSubmitpackages/preact-form/src/useForm.tsx保证 meta 原样透传。用 Standard Schema 转换数据在 onSubmit 中解析输出TanStack Form 原生支持 Standard Schema。但有一点必须注意TanStack Form 只使用 Schema 做校验不保留 Schema 转换后的输出数据。为什么 onSubmit 收到的是输入数据在 packages/form-core/src/standardSchemaValidator.ts 中standardSchemaValidators的同步/异步校验只调用schema[~standard].validate(value)并消费result.issues错误信息成功路径下的result.value输出数据并不会被回写export const standardSchemaValidators { validate(...) { const result schema[~standard].validate(value) // ... if (!result.issues) return // 只关心错误不取 result.value // ... }, // validateAsync 同理 }因此onSubmit收到的value永远是输入数据input。若你的 schema 使用了transform等转换能力必须在onSubmit中手动执行一次schema.parse()才能拿到转换后的输出。在 onSubmit 中解析 schema 输出const schema z.object({ age: z.string().transform((age) Number(age)), }) // TanStack Form uses the input type of Standard Schemas const defaultValues: z.inputtypeof schema { age: 13, } const form useForm({ defaultValues, validators: { onChange: schema, }, onSubmit: ({ value }) { const inputAge: string value.age // Pass it through the schema to get the transformed value const result schema.parse(value) const outputAge: number result.age }, })要点拆解defaultValues使用z.inputtypeof schema因为表单值对应 schema 的输入类型这里age是stringonChange: schemaschema 直接用作校验器校验失败时错误会传播到字段级底层会按字段路径把 issues 映射成fieldMeta错误见 standardSchemaValidator.ts 的prefixSchemaToErrors路径前缀逻辑schema.parse(value)在onSubmit中重新解析输入值得到z.outputtypeof schema此时age已被转换为number。校验与转换分离的设计权衡这一设计意味着校验与数据转换是解耦的校验器负责“这个值合不合法”而数据变换发生在提交边界。对大多数场景这种分离是干净的——表单内部始终维护原始输入只有真正提交时才做类型收窄与转换例如把字符串数字转成number、去掉多余字段、应用默认值等。若需要更复杂的输出结构还可以结合form.Subscribe订阅canSubmit/isSubmitting状态参考 examples/preact/simple/src/index.tsx在isSubmitting期间禁用提交按钮并配合aria-disabled提升可访问性。小结提交入口是form.handleSubmit(meta?)内部会依次执行字段 touch、canSubmit检查、全量校验、监听器与onSubmit回调并通过onSubmitInvalid处理失败分支onSubmitMeta定义提交元数据的类型与默认值handleSubmit(meta)传入的实参会覆盖默认值且 meta 会一致地到达onSubmit、onSubmitInvalid与listeners.onSubmitStandard Schema 只做校验不产出转换值onSubmit拿到的永远是输入数据需要转换时在onSubmit内调用schema.parse()并配合z.input/z.output保证类型安全相关深入阅读表单与字段校验指南含异步校验、防抖与canSubmit详情、核心实现 FormApi、Preact 适配器 useForm、Preact 简单示例。【免费下载链接】form Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, and Lit.项目地址: https://gitcode.com/GitHub_Trending/form/form创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
