迁移

大多数编辑器已经有一批用普通 Fabric.js JSON 保存的项目。做 Fabric.js 迁移通常意味着要写一个转换器。在这里，旧文件可以直接打开，并在打开时自动升级。

打开普通 Fabric.js JSON

Fabric 5、Fabric.js 6 或 Fabric.js 7 的 canvas.toJSON() 普通输出，都可以直接打开：

await engine.importFabricJson(savedJsonText, {
  id: "plan-42",
  metadata: { source: "old editor" },
});

loadDocument 和 load(id) 也能识别普通 Fabric.js JSON，所以你现有应用保存的项目不需要单独导入就能打开。用 load(id) 打开的文档会保留这个 id，下一次保存时存成新格式。

从 Fabric 5 升级到 Fabric.js 6 或 7

这个包需要 Fabric.js 6 或 7。保存的数据不会阻碍升级：

• Fabric 5 保存的 JSON 会经过迁移步骤打开。Fabric.js 6 和 7 仍然接受 Fabric 5 的旧类型名。
• Fabric 6 和 Fabric.js 7 的默认原点不同。文档总是保存 originX 和 originY，所以用一个版本保存的文件，在另一个版本里也能正确打开。

你自己的代码请按官方的 Fabric.js 升级指南修改。存下来的文件不需要任何 Fabric.js 迁移脚本。

格式版本

每份文档都记录了它的 schemaVersion。将来某个大版本改变格式时，旧文档会在打开时一步步升级。

• 发生升级时，load:success 会带上 migratedFrom。
• 某一步失败会以 MIGRATION_FAILED 拒绝，error.migrationFrom 给出起始版本。
• 更新版本的包保存的文档会以 UNSUPPORTED_SCHEMA 拒绝，而不是被错误读取。

在服务器上升级文件

migrateDocument 和 detectSchemaVersion 在 Node 里无需画布即可运行，适合批量任务：

import { detectSchemaVersion, migrateDocument } from "fabricjs-document-engine";
 
if (detectSchemaVersion(stored) === 0) {
  const { document } = migrateDocument(stored, {
    canvasWidth: 1200,
    canvasHeight: 800,
  });
  await saveUpgraded(document);
}

detectSchemaVersion 对文档返回 1，对普通 Fabric.js JSON 返回 0，其他情况返回 undefined。测试过的版本见兼容性。