企业官网建设流程全解析

form2js 快速入门教程：3步把HTML表单字段变成结构化JS对象

【免费下载链接】form2jsParse browser forms into structured JavaScript objects. Six adapters — React hooks, vanilla DOM, jQuery, FormData, and more. One coherent API.项目地址: https://gitcode.com/gh_mirrors/fo/form2js

form2js 是一个轻量级表单解析工具，专门把 HTML 表单字段自动转换成结构化的 JS 对象。你只需要在字段名里写好person.name.first这样的路径语法，提交表单时就能直接拿到嵌套对象——不用手写遍历、不用逐个拼接键值对。本快速入门教程带你在 3 步内完成一次「表单变 JS 对象」的转换。

为什么手动处理 HTML 表单这么麻烦

传统方式处理表单提交，你要做三件事：

1. 遍历表单里每一个input、select、textarea；
2. 逐个读取字段的name和value；
3. 遇到person.name.first这类嵌套命名，还得自己拆分路径、一层层建好嵌套结构。

form2js 把这一步反过来：把结构直接写进字段名，解析引擎替你生成对象。

项目最初发布于 2010 年，如今已针对现代 JavaScript、TypeScript 和 ESM 全面重写，支持 React、jQuery 与服务端环境，且六个包共享同一套一致的 API。

全家福：6 个适配器，一套 API

按需安装即可，互不捆绑。

3 步把表单变成 JS 对象

第一步：安装需要的包

原生浏览器项目一行搞定：

npm install @form2js/dom

React 项目用npm install @form2js/react react，jQuery 项目用npm install @form2js/jquery jquery。

第二步：给字段起「路径名」

把嵌套结构和数组直接写进name，三种最常用的写法：

完整的路径解析规则（包括稀疏下标自动压缩等边缘情况）见 docs/api-index.md。

第三步：调用一个函数

import { formToObject } from "@form2js/dom"; const form = document.getElementById("profileForm"); const data = formToObject(form); // { person: { name: { first: "Sam", last: "Vimes" }, roles: ["captain"] } }

就这么多——没有任何 DOM 遍历代码，拿到的对象可以直接交给JSON.stringify或后端 API。formToObject的实现在 packages/dom/src/index.ts。

React 版：一个 Hook 搞定提交、校验与状态

在 React 中，useForm2js把「解析表单 + 提交 + 错误处理」压缩成一次 Hook 调用：

const { onSubmit, isSubmitting, isError, error, isSuccess, reset } = useForm2js(async (data) => await sendFormData(data), { schema: MySchema });

• onSubmit：直接挂到<form>上，自动解析并拦截默认提交；
• isSubmitting / isError / isSuccess：禁用按钮、展示提示的状态开箱即用；
• schema：可选传入校验 schema（任何带parse()的库都可以，如 Zod），校验通过后拿到的data类型自动推导。

Hook 完整实现在 packages/react/src/index.ts。

默认行为：3 个容易踩坑的点

form2js 默认遵循浏览器原生表单提交语义，提前了解这 3 点能省不少调试时间：

1. 空值自动跳过—— 空字符串和null不会出现在结果里（默认skipEmpty: true）；
2. 禁用控件不采集——disabled的字段以及disabledfieldset 内的控件都会被忽略，可用getDisabled: true显式包含；
3. 危险路径被拦截—— 字段名中出现__proto__、prototype、constructor会被默认拒绝，防止原型污染。

未勾选的复选框不占数组坑位等其余规则，完整文档在 docs/api-index.md。

进阶：js2form 反向回填表单

「编辑记录」场景需要把对象填回表单。@form2js/js2form的objectToForm(formElement, data)会按路径把对象中的值逐一写回对应字段，与解析方向构成一条对称的管线。用法与细节见 docs/api-js2form.md。

更多学习资源

• 项目总览与安装说明：README.md
• 六个包的 API 总目录：docs/api-index.md
• DOM 适配器（含extractPairs、nodeCallback等进阶能力）：docs/api-dom.md
• 服务端 FormData 解析：docs/api-form-data.md
• 核心引擎源码（路径解析与对象合并）：packages/core/src/index.ts
• 从旧版 form2js 迁移过来？先看：docs/migrate.md

【免费下载链接】form2jsParse browser forms into structured JavaScript objects. Six adapters — React hooks, vanilla DOM, jQuery, FormData, and more. One coherent API.项目地址: https://gitcode.com/gh_mirrors/fo/form2js