Fabric.js Document Engine

搜索文档

查找页面或章节

EN

问题排查

查看 Markdown

常见问题、原因,以及每个问题的解决办法。

这份 Fabric.js 问题排查指南汇总了大家最常遇到的问题,按通常出现的顺序排列。

撤销没有记录我的改动

Fabric.js 只在鼠标交互、添加和删除对象、文本编辑时触发事件。你的代码用 object.set() 或 canvas.bringObjectForward() 做的改动不会触发任何事件。把它们包起来:

engine.transaction("Recolor", () => shape.set("fill", "teal"));

撤销后对象引用失效了

撤销和重做会重建改动过的对象,所以它们是 id 不变的新实例。保存 id,再用 engine.getObjectById(id) 查找对象。

加载后自定义属性丢了

用普通的 toJSON 和 loadFromJSON 时,Fabric.js 只保存它认识的属性。把类和它的自定义属性注册一下:

engine.registerObject({ fabricClass: Sticker, properties: ["label"] });

加载以 UNKNOWN_OBJECT_TYPE 失败

文档里有当前页面没注册的类。通过 customObjects 传入,或在加载前调用 registerObject。这个类需要一个和保存的 type 一致的静态 type。在普通 Fabric.js 里,同样的问题会表现为 klass.fromObject is not a function。

打包结果里有两份 Fabric.js

在一份里注册的类另一份不认识,加载会以 UNKNOWN_OBJECT_TYPE 失败。请确认只安装了一份 fabric。在 Vite 里使用链接的包时,加上 resolve: { dedupe: ["fabric"] }。

加载以 MISSING_ASSETS 失败

error.missingAssets 列出了每张没加载成功的图片。用 assets.resolveUrl 修正地址,用 assets.replaceMissingImage 提供替代图片,或者之后调用 engine.replaceImage(oldUrl, newUrl)。每一项都有 failure.reason(NOT_FOUND、HTTP_ERROR、CORS、NETWORK、TIMEOUT 或 DECODE),说明该修什么;服务器慢时,调大 assets.imageTimeout。

重新打开后文字显示不一样

创建文字时字体还没加载,所以 Fabric.js 用后备字体测量了它。在 assets.loadFont 里加载网络字体,并留意 FONT_UNAVAILABLE 警告。

导出时画布被污染

有一张来自其他网站的图片没用 CORS 加载,浏览器因此拦截 PNG、JPEG 和 WebP 导出。从返回 Access-Control-Allow-Origin 的服务器,用 crossOrigin: "anonymous" 加载它。运行 engine.preflightExport({ format }),可以在用户点击导出前提示这个问题。

SVG 里的曲线文字和画布不一样

检查文字是不是在开启了对象缓存的编组里。这时 Fabric.js 会在画布上裁掉高出路径的字母,而 SVG 会完整显示它们;给这个编组设置 objectCaching: false。缺少的字体用 svg.embedFonts 传入。详见 SVG 导出。

SVG 在 Illustrator 或浏览器里打不开

Fabric.js 6 和 7 会把含空格的路径文字写成无效的 XML。engine.export({ format: "svg" }) 会修复它,直接调用 canvas.toSVG() 则不会。

在别处打开 SVG 时图片不见了

导出时设置 svg: { embedImages: true }。来自其他网站、没有 CORS 的图片会保留为链接,并给出 IMAGE_NOT_EMBEDDED 警告。

导入的 SVG 位置不对

util.groupSVGElements 按绘制的内容确定编组大小,所以 viewBox 之外的元素会让整体移动。改用 engine.importSvg(svg),见 SVG 导入。

PDF 导出以 PDF_UNAVAILABLE 失败

用 npm install jspdf svg2pdf.js 安装可选的包。PDF 导出也需要浏览器。

PDF 里的文字是图片,或字体不对

在 fonts 里为每个字体族传入 TrueType(.ttf)文件,每种字重和样式一个。WOFF 和 WOFF2 文件会以 PDF_FAILED 被拒绝。详见 PDF 导出。

批量渲染时内存耗尽

用 renderDocuments 代替每份文档一个画布,保持较低的 concurrency,每个结果到达后就上传。详见批量渲染。

只开一个标签页也报 SAVE_CONFLICT

你的适配器没有返回新的修订号。在 saveDocument 里返回 { revision },或者保存 document.revision。

恢复提示一直不出现

传入 recovery: { store: createIndexedDbRecovery() }。只有存在未保存改动时才会写副本;隐私浏览模式可能在关闭窗口时清空存储。

加载时报 LOAD_CONFLICT

文档打开期间画布被修改了,这些修改被保留了下来。先询问用户,再用 discardUnsavedChanges: true 重新加载,见 保存和加载。

Textbox 比设定的宽度更宽

Fabric 会把 Textbox 撑到最长单词的宽度。改用 BoundedTextbox,见 文本框宽度。

在 Android 上输入时字母或样式位置错误

在开始编辑之前调用 attachMobileTextInput(canvas),见 手机上的文字输入。

有几千个对象时拖动很慢

用 enableDirtyRegionRendering(canvas) 开启脏区域渲染,见 渲染大量对象。

应用滤镜时页面卡住

用 createFilterWorker() 运行滤镜,见 图片滤镜。

React:开发环境里有两个引擎

StrictMode 会把 effect 挂载两次。useDocumentEngine 会销毁第一个引擎,所以只有一个在运行。始终使用 hook 返回的引擎。

Vue:加载后画布不渲染

Vue 把 Fabric.js 画布包成了响应式代理。把它放在 shallowRef 里,或者传入 toRaw(canvas)。详见 Vue。

Next.js:"window is not defined"

Fabric.js 在服务端运行了。用 dynamic(() => import("./editor"), { ssr: false }) 加载编辑器。详见 Next.js。

如果这份 Fabric.js 问题排查清单没有覆盖你的问题,请带上错误 code、Fabric.js 版本和浏览器信息,提交一个 issue。