name属性是FormData的键名,input元素必须有name才能被包含;多个同名控件生成多条独立键值对,get()仅返回首个值,getAll()获取全部;特殊控件如file、radio、checkbox的值是否收录取决于其状态。

FormData 构建时 name 属性就是键名
表单提交或手动构造 FormData 时,input 元素的 name 属性值会直接成为 FormData 的键(key),对应值是用户输入或 value 属性内容。没有 name 的 input 不会被包含——哪怕它有 value 或已填写。
-
<input name="username" value="alice">→formData.get("username")返回"alice" -
<input name="tags" value="js,ts">→ 键为"tags",不是"tags[]"或自动转数组 -
<input value="ignored">(无name)→ 完全不会出现在FormData中
多个同名 input 生成多个键值对,不是数组
浏览器原生行为中,多个 input 共享同一 name(比如多选 checkbox),FormData 会为每个选中的项分别添加一条记录,而不是合并成一个数组。调用 get() 只返回第一个匹配值;要用 getAll() 才能拿到全部。
<input type="checkbox" name="role" value="admin"><input type="checkbox" name="role" value="editor" checked><input type="checkbox" name="role" value="viewer" checked>-
formData.get("role")→"editor"(首个选中项) -
formData.getAll("role")→["editor", "viewer"]
特殊 input 类型对 value 的影响
name 决定键名,但最终值是否被收录、取什么值,取决于控件类型和状态:
-
<input type="file">:只有选中文件时才加入FormData,值是File对象;未选中则不出现该键 -
<input type="checkbox" checked>:默认值是"on",除非显式设置value -
<select multiple></select>:每个选中<option></option>单独生成一条记录,键为select的name -
<textarea name="desc"></textarea>:换行符保留,不自动 trim,空格和回车都算有效内容
常见坑:name 值含空格、点号或中文时的兼容性
虽然 HTML 允许 name 出现空格、点(.)、中文甚至 emoji,但后端解析可能出问题。尤其 Node.js 的 body-parser 或 PHP 的 $_POST 默认不支持点号键名,部分框架会静默丢弃或转义。
-
<input name="user.name">→ 在 Express 中可能变成req.body["user.name"],但某些中间件会把它当对象路径处理 -
<input name="用户ID">→ 多数服务端语言能接收,但 JSON schema 校验或日志系统可能报编码警告 - 推荐只用 ASCII 字母、数字、下划线和短横线:
user_id、is_active
真正容易被忽略的是:表单提交时浏览器按 DOM 顺序插入键值对,但 FormData 本身不保证遍历顺序;依赖顺序取值(如用 entries() 遍历)在不同浏览器或版本中可能不一致。

















