Fabric.js 编辑器上线

这篇指南把所有功能组合在一起，帮你完成 Fabric.js 编辑器上线：存储、自动保存、恢复、版本、限制和资源，以及每种失败的错误处理。

引擎

import {
  bindKeyboardShortcuts,
  bindUnsavedChangesWarning,
  createDocumentEngine,
} from "fabricjs-document-engine";
import { createIndexedDbRecovery } from "fabricjs-document-engine/recovery";
 
export function createEditor(canvas: Canvas) {
  const engine = createDocumentEngine({
    canvas,
    storage: restStorage,
    customObjects: [{ fabricClass: Sticker, properties: ["label"] }],
    autosave: { delay: 1500, maxWait: 15000 },
    saveRetry: { attempts: 4, baseDelay: 800, maxDelay: 10000 },
    recovery: { store: createIndexedDbRecovery(), interval: 3000 },
    versions: { autoEvery: 20, keepAuto: 30 },
    history: { limit: 150, maxBytes: 48 * 1024 * 1024 },
    limits: {
      maxObjects: 20000,
      isAllowedUrl: (url) =>
        url.startsWith("https://cdn.example.com/") || url.startsWith("blob:"),
    },
    assets: {
      resolveUrl: (url) => signCdnUrl(url),
      upload: async ({ blob }) => uploadToBucket(blob),
      replaceMissingImage: () =>
        "https://cdn.example.com/placeholders/missing.png",
    },
  });
 
  const unbindShortcuts = bindKeyboardShortcuts(engine);
  const unbindWarning = bindUnsavedChangesWarning(engine);
 
  return {
    engine,
    dispose() {
      unbindShortcuts();
      unbindWarning();
      engine.destroy();
    },
  };
}

打开文档

打开之前，先检查是否有中断的加载和恢复副本：

async function openDocument(engine: DocumentEngine, id: string) {
  const interrupted = await engine.getInterruptedLoad();
  if (
    interrupted?.documentId === id &&
    !(await confirmUser("This document failed to open last time. Try again?"))
  ) {
    return;
  }
 
  const copy = await engine.getRecovery(id);
  if (copy && (await confirmUser("Restore unsaved work?"))) {
    await engine.restoreRecovery(id, { discardUnsavedChanges: true });
    return;
  }
  if (copy) await engine.discardRecovery(id);
 
  await engine.load(id);
}

错误处理

每种失败都是带稳定 code 的 DocumentEngineError。按 code 判断，不要按消息文字判断：

engine.on("load:error", ({ error }) => {
  switch (error.code) {
    case "LOAD_ABORTED":
      return;
    case "MISSING_ASSETS":
      return showMissingImages(error.missingAssets);
    case "UNKNOWN_OBJECT_TYPE":
      return showMessage("This document needs a newer version of the editor.");
    case "UNSUPPORTED_SCHEMA":
      return showMessage(
        "This document was made with a newer version of the editor."
      );
    case "UNSAFE_DOCUMENT":
      return showMessage("This file was blocked for safety reasons.");
    default:
      return showMessage(`The document could not be opened: ${error.message}`);
  }
});
 
engine.on("save:error", ({ error }) => {
  if (error.code === "SAVE_CONFLICT") return askConflict();
  if (error.code !== "SAVE_CANCELLED") {
    showMessage("Saving failed. Your work is kept on this device.");
  }
});

所有错误码都列在错误码里。

离开编辑器

async function closeEditor(editor: ReturnType<typeof createEditor>) {
  if (editor.engine.isDirty())
    await editor.engine.save().catch(() => undefined);
  editor.dispose();
}

destroy() 还会为未保存的内容写一份恢复副本，所以即使最后这次保存失败，也不会丢内容。

在 Node.js 服务器上

文档相关的辅助函数在 Node.js 里无需画布就能运行。存储之前检查每个上传，做法见安全。

清单

Fabric.js 编辑器上线之前，逐项过一遍这份清单：

verifyStorageAdapter(yourStorage) 通过。见检查适配器。
服务器在同一条查询里比较修订号并写入。
所有打开文档的地方都注册了自定义类。
网络字体通过 assets.loadFont 加载。
图片带 CORS 和 crossOrigin: "anonymous" 加载，导出才能成功。
为 SAVE_CONFLICT、MISSING_ASSETS、恢复提示和 UNSAVED_CHANGES 准备了界面。
工具栏遵循了无障碍指南。

通过这份清单，你的 Fabric.js 编辑器上线后就能处理用户真正会遇到的失败。

上线清单

引擎

打开文档

错误处理

离开编辑器

在 Node.js 服务器上

清单