JavaScript structuredClone 怎么复制表单状态：可克隆类型与 transfer 陷阱

编辑表单时，用户切换预览、撤销修改或暂存草稿，最容易踩的是“看起来复制了，嵌套字段却还在互相影响”。structuredClone()适合复制可结构化克隆的表单状态，能保留嵌套对象和循环引用；但它不是 JSON.stringify 的升级版，遇到函数、DOM 节点，或者误用 transfer，结果会完全不同。

表单草稿为什么需要真正的深拷贝

假设页面同时维护 savedState 和 editingState。用展开运算符只复制第一层时，profile.address、items 仍然指向同一个嵌套对象。用户在预览页改城市，编辑页的原始值也跟着变，撤销自然失效。

const savedState = {
  profile: { name: "林川", address: { city: "杭州" } },
  items: [{ sku: "A-17", quantity: 2 }]
};

const editingState = structuredClone(savedState);
editingState.profile.address.city = "宁波";
editingState.items[0].quantity = 3;

console.log(savedState.profile.address.city); // 杭州
console.log(savedState.items[0].quantity);   // 2

这里的关键不是“复制得更深”这句口号，而是每一层可克隆数据都获得了新的对象身份。Map、Set、Date、RegExp 等可结构化克隆的值也不必先转成字符串。

从 JSON 深拷贝迁移到 structuredClone

旧项目常见的写法是 JSON.parse(JSON.stringify(state))。它会丢掉 undefined、函数和部分特殊对象，还会把 Date 变成字符串；循环引用则直接抛异常。迁移时先确认表单状态里保存的是数据，而不是页面控制器。

表单里的校验器、事件回调、HTMLElement 引用都不该放进可持久化草稿。可以把它们挂在单独的运行时对象上，草稿只保留字符串、数字、布尔值、数组和业务对象。

transfer 为什么会让原始附件突然不可用

第二个参数不是复制选项的别名。下面的代码把 ArrayBuffer 的底层内存转交给克隆结果，原始 buffer 不再拥有可读内容：

const attachment = new Uint8Array([10, 20, 30]);
const snapshot = structuredClone(
  { bytes: attachment },
  { transfer: [attachment.buffer] }
);

console.log(snapshot.bytes.byteLength); // 3
console.log(attachment.byteLength);     // 0
// attachment.buffer 已被转移，不要再把它交给上传函数

这对把大块二进制交给 Worker 处理很有用，可以避免再复制一份内存；对“保存草稿后还要继续上传原文件”的表单流程却很危险。除非你明确完成所有权切换，否则不要在普通快照函数里传 transfer。

一次可验证的表单快照写法

把快照函数限制在纯数据上，失败时给出字段范围，保存和撤销逻辑会更容易测：

function makeDraftSnapshot(formState) {
  try {
    return structuredClone(formState);
  } catch (error) {
    if (error?.name === "DataCloneError") {
      throw new TypeError("表单状态包含不可克隆值，请移除函数或 DOM 引用");
    }
    throw error;
  }
}

const draft = makeDraftSnapshot({
  fields: { title: "周报", tags: ["前端"] },
  dirty: true
});
draft.fields.tags.push("性能");
console.log(draft.fields.tags); // ["前端", "性能"]

回归检查至少覆盖三件事：修改副本后原状态不变；嵌套数组和对象的身份不同；错误状态能定位到不可克隆值。若状态包含 File、Blob 或 ArrayBuffer，还要单独验证浏览器目标和上传时序，不要只看快照对象能否打印出来。

常见问题

structuredClone 能复制函数吗？

不能。函数属于不可结构化克隆值，会触发 DataCloneError。把函数放到运行时配置，把纯参数放进表单状态即可。

structuredClone 会保留对象的原型和 getter 吗？

不要把它当作完整对象元数据复制器。属性描述符、setter、getter 等信息不会按原样保留，类实例也应通过业务字段重新构造。

什么时候应该使用 transfer？

当你明确要把 ArrayBuffer 等可转移对象的所有权交给 Worker 或下一阶段处理时再用。普通撤销、预览和草稿保存通常只需要克隆，不需要转移。

为什么 structuredClone 比 JSON 方法更适合表单草稿？

它能处理循环引用，并保留更多结构化数据类型；但它仍然不负责序列化函数、DOM 节点或完整类实例。先把状态模型收敛为纯数据，收益才稳定。

迁移前的最后核对

• 撤销快照是否只包含业务数据，没有回调和 DOM 引用。
• 是否对 DataCloneError 做了明确处理，而不是吞掉异常。
• 是否把 transfer 限定在真正的所有权转移场景。
• 是否用嵌套对象、数组和附件状态做过一次保存、修改、撤销回归。