深入掌握 TanStack Form Solid 数组字段Index 渲染、子字段路径与完整的数组操作 API【免费下载链接】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/solid-form的数组Array表单能力展开讲解如何以modearray声明数组字段、借助 Solid 的Index与路径式子字段如people[0].name渲染列表以及pushValue、removeValue、swapValues等数组操作 API 的完整用法。读完本文你将掌握在 Solid 应用中构建可增删、可编辑、可提交的嵌套数组表单的完整方案并理解底层源码对数组渲染性能所做的重要优化。TanStack Form 原生支持将数组作为表单值包括数组内嵌对象子值sub-object values的场景。这份能力在 Solid 适配层由tanstack/solid-form提供示例代码同时存在于官方示例工程与单元测试中可放心落地到实际项目。基础用法modearray字段与Index渲染要使用数组字段首先在createForm的defaultValues中声明一个数组然后通过form.Field配合modearray声明数组字段并读取field().state.value作为数据源function App() { const form createForm(() ({ defaultValues: { people: [], }, })) return ( form.Field namepeople modearray {(field) ( Show when{field().state.value.length 0} {/* Do not change this to For or things will not work as-expected */} Index each{field().state.value} { (_, i) null // ... } /Index /Show )} /form.Field ) }mode属性在类型层面对应value | array两种取值见 packages/solid-form/src/types.ts其中array用于数组字段。外层用Show判断数组非空内层用Index遍历每一项。为什么必须用Index而不是For这是 Solid 数组表单最容易踩的坑官方文档明确强调必须使用solid-js的Index而不是For因为For会在数组每次变化时重新渲染内部组件导致字段丢失其值进而删除子字段的值。背后的原因是For通过 key 来追踪列表项当数组增删导致索引位移时Solid 会复用并重建组件而Index按索引位置追踪数组变化时同一索引位上的组件会被原位保留。对于 TanStack Form 这种「每个子字段持有独立状态实例」的模型Index可以保证people[i]对应的字段状态在数组操作后仍然与正确的 DOM 节点绑定输入框中的值不会因列表抖动而丢失。添加元素pushValue与动态 JSX 重映射在Index结构就位后每次调用数组字段的pushValue都会触发映射 JSX 的重新生成从而把新元素渲染出来button onClick{() field().pushValue({ name: , age: 0 })} typebutton Add person /buttonpushValue接收一个与数组元素类型一致的值这里是{ name: , age: 0 }对象将其追加到数组末尾。从源码看FieldApi.pushValue会调用表单层的pushFieldValue并触发该字段的onChange监听器见 packages/form-core/src/FieldApi.ts#L1105-L1118因此新元素加入后订阅了数组字段的视图会自动更新。渲染子字段people[${i}].name路径访问数组内元素是对象时可以用「数组路径 对象属性」的下标语法声明子字段。i来自Index的索引回调参数拼接出的字符串路径就是 TanStack Form 的深层字段定位form.Field name{people[${i}].name} {(subField) ( input value{subField().state.value} onInput{(e) { subField().handleChange(e.currentTarget.value) }} / )} /form.Field每个子字段都是独立的FieldApi实例拥有自己的值、校验状态与元数据因此你可以像对待普通字段一样使用handleChange、handleBlur以及validators校验。由于Index保证组件按索引复用i在列表重排后依然指向正确的子字段路径people[0].name与第 0 个输入框始终对应。完整示例一个可增删、可提交的人员列表表单将上述能力组合起来就得到一个完整可运行的人员列表表单——这也是官方文档的 Full Example同样出现在仓库示例工程中见 examples/solid/array/src/index.tsxfunction App() { const form createForm(() ({ defaultValues: { people: [], }, onSubmit: ({ value }) alert(JSON.stringify(value)), })) return ( div form onSubmit{(e) { e.preventDefault() e.stopPropagation() form.handleSubmit() }} form.Field namepeople modearray {(field) ( div Show when{field().state.value.length 0} {/* Do not change this to For or the test will fail */} Index each{field().state.value} {(_, i) ( form.Field name{people[${i}].name} {(subField) ( div label divName for person {i}/div input value{subField().state.value} onInput{(e) { subField().handleChange(e.currentTarget.value) }} / /label /div )} /form.Field )} /Index /Show button onClick{() field().pushValue({ name: , age: 0 })} typebutton Add person /button /div )} /form.Field button typesubmitSubmit/button /form /div ) }要点回顾form.handleSubmit()在表单原生onSubmit中手动触发配合e.preventDefault()/e.stopPropagation()阻止浏览器默认行为数组字段的值由子字段的输入自动组装提交时onSubmit的value即为完整的people数组typebutton防止「Add person」按钮意外触发表单提交。示例工程使用 Vite 构建见 examples/solid/array/package.json依赖tanstack/solid-form与solid-js在示例目录下执行npm run dev即可在浏览器中体验。数组操作 API 全景七种方法一次讲清除了pushValue数组字段还提供了一套完整的增删改查方法。官方基础概念文档见 docs/framework/solid/guides/basic-concepts.md与源码 packages/form-core/src/FieldApi.ts#L1105-L1223 共同确认了以下 API方法签名要点作用pushValue(value)追加到数组末尾新增一条记录示例中的 Add personinsertValue(index, value)在指定索引插入将后续元素向右平移replaceValue(index, value)替换指定索引的值原地覆盖该位置的元素removeValue(index)删除指定索引的元素移除记录后续索引自动前移swapValues(aIndex, bIndex)交换两个索引的值位置互换moveValue(aIndex, bIndex)把 aIndex 的值移动到 bIndex支持列表拖拽排序等场景clearValues()清空整个数组一键重置列表例如给完整示例补充删除按钮只需要一行调用button typebutton onClick{() field().removeValue(i)} Remove person {i} /button从源码实现看这七种方法都遵循同一模式委托给表单层的pushFieldValue/insertFieldValue/replaceFieldValue/removeFieldValue/swapFieldValues/moveFieldValues/clearFieldValues完成状态更新随后触发onChange监听器以驱动视图刷新同时支持传入UpdateMetaOptions如dontRunListeners来控制是否连带触发监听逻辑。源码级的性能设计数组字段只追踪_arrayVersionIndex 子字段模式能够高效运行背后还有一层源码级的优化。在 packages/solid-form/src/createField.tsx#L170-L178 的makeFieldReactive中const reactiveStateValue useSelector(fieldApi.store, (state) mode array ? state.meta._arrayVersion || 0 : state.value, )注释与代码表明对于普通字段订阅state.value值一变就触发重新渲染对于array 模式字段只追踪内部元数据state.meta._arrayVersion数组版本号不追踪整个数组引用。这样做的好处是当数组内某个子字段如people[0].name的值变化时数组本身的结构版本并没有变数组字段的外层组件不会因为子属性变化而无谓重渲染只有真正发生了 push/remove/swap 等结构性操作版本号递增时才会触发外层更新。这正好与Index的按索引复用机制配合把重渲染范围控制在最小。如何验证官方测试与示例如果你希望对这套行为有 100% 的把握仓库提供了可直接验证的证据可运行示例examples/solid/array/src/index.tsx 与官方文档的 Full Example 几乎一致是最直观的参考实现单元测试packages/solid-form/tests/createField.test.tsx#L474-L539 中的「should handle arrays with subvalues」用例完整复刻了Index渲染、pushValue({ name: , age: 0 })添加、removeValue(i)删除并断言最终提交结果为{ people: [John] }基础概念文档docs/framework/solid/guides/basic-concepts.md 的「Array Fields」小节还提供了一个带hobbies[${i}].name与hobbies[${i}].description两个子字段、并支持删除的 hobbies 列表示例可作为多子字段场景的补充练习。综上TanStack Form 的 Solid 数组字段以「modearrayIndex 路径式子字段」为骨架配合七种数组操作方法足以覆盖从简单字符串列表到嵌套对象列表的全部业务形态而_arrayVersion的细粒度订阅设计则保证了列表在频繁编辑时依然保持流畅。【免费下载链接】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），仅供参考