Fabric.js Document Engine

搜索文档

查找页面或章节

EN

DocumentEngine

查看 Markdown

createDocumentEngine 返回的对象。

createDocumentEngine 返回一个 DocumentEngine。下表列出所有 DocumentEngine 方法和属性。会访问存储或画布的方法都返回 promise。

成员

NameTypeDefaultDescription
canvas*StaticCanvas—The canvas you passed in.
getDocumentInfo*(): DocumentInfo—{ id, createdAt, updatedAt, metadata } of the current document.
updateMetadata*(changes: Record<string, unknown>): void—Merges changes into the metadata and marks the document as unsaved.
newDocument*(options?: NewDocumentRequest): void—Clears the canvas and starts a new document.
toDocument*(): FabricDocument—Serializes the canvas into a FabricDocument. Every object gets an id.
loadDocument*(document: unknown, options?: LoadOptions): Promise<FabricDocument>—Validates, migrates and checks the assets of a document, then loads it. A failed load leaves the canvas untouched.
load*(documentId: string, options?: LoadOptions): Promise<FabricDocument>—Loads a document from storage. It keeps documentId even if it was stored as plain Fabric JSON.
importFabricJson*(json: string | Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument>—Opens plain Fabric JSON, such as canvas.toJSON() output, as text or as an object.
importSvg*(svg: string, options?: SvgImportOptions): Promise<SvgImportResult>—Adds an SVG file to the canvas where its viewport puts it, as one undo step. Scripts and links to other files are removed first.
createVersion*(name?: string): Promise<VersionSummary>—Keeps a named version of the current document.
listVersions*(documentId?: string): Promise<VersionSummary[]>—Version summaries, newest first.
restoreVersion*(versionId: string): Promise<FabricDocument>—Keeps an automatic Before restoring "..." version first, then loads the old content as a new, unsaved revision.
deleteVersion*(versionId: string): Promise<void>—Deletes a version.
save*(options?: SaveOptions): Promise<FabricDocument>—Saves through storage. Only one save runs at a time, and calls made during a save merge into one follow-up.
isDirty*(): boolean—Whether there are unsaved changes.
getSaveState*(): SaveState—The current SaveState.
registerObject*(definition: CustomObjectDefinition): void—Registers a custom class after the engine was created.
transaction*<Result>(label: string, work: () => Result, options?: TransactionOptions): Result—Records everything work changes as one labelled undo step. Nested and async work is supported.
setPage*(changes: PageChanges, label?: string): void—Changes the page size, background, background image, overlay or canvas mask as one undo step. Marks the document unsaved.
commit*(label?: string): boolean—Records changes your code made since the last step. Returns false if nothing changed.
undo*(): Promise<boolean>—Undoes one step. Calls run in order. A failure rejects with HISTORY_FAILED and keeps the step.
redo*(): Promise<boolean>—Redoes one step. Calls run in order.
canUndo*(): boolean—Whether there is a step to undo.
canRedo*(): boolean—Whether there is a step to redo.
getHistory*(): { undo: string[]; redo: string[]; }—The labels of the undo and redo steps, newest first.
clearHistory*(): void—Forgets every undo and redo step.
getObjectById*(id: string): FabricObject | undefined—Finds any object by its id, including objects inside groups.
getAssetManifest*(): AssetManifest—The images and fonts the current canvas uses.
checkAssets*(): Promise<AssetReport>—Loads every image and font and reports { manifest, missingImages, unavailableFonts, warnings }.
replaceImage*(oldUrl: string, newUrl: string): Promise<number>—Replaces every image that uses oldUrl, keeping each one's size on the page, as one undo step. Returns how many were replaced.
export*(options: ExportOptions): Promise<ExportResult>—Exports PNG, JPEG, WebP, SVG or JSON. Rejects with EXPORT_BLOCKED and a list of problems when something would break the output.
preflightExport*(options: ExportOptions): Promise<ExportPreflight>—Runs the export checks without exporting: { ok, problems, warnings }.
flushRecovery*(): Promise<void>—Writes a recovery copy right now.
getRecoverableDocuments*(): Promise<RecoveryRecord[]>—Every recovery copy, newest first.
getRecovery*(documentId?: string, sessionId?: string): Promise<RecoveryRecord | undefined>—One recovery copy. The default is the current document.
restoreRecovery*(documentId?: string, options?: RestoreRecoveryOptions): Promise<FabricDocument>—Loads a recovery copy as unsaved work, keeping the revision it was based on.
discardRecovery*(documentId?: string, sessionId?: string): Promise<void>—Deletes a recovery copy.
getInterruptedLoad*(): Promise<InterruptedLoad | undefined>—{ documentId, startedAt } of a load that never finished, for example because the tab crashed.
on*<Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe—Subscribes to an event. Returns a function that unsubscribes.
destroy*(): void—Stops listening and cancels loads, saves and timers. Writes a recovery copy if there is unsaved work. Later calls throw ENGINE_DESTROYED.

方法的参数

加载配置

NameTypeDefaultDescription
restoreCanvasSizeboolean—Resize the canvas to the size stored in the document.
discardUnsavedChangesbooleanfalseOpen the document even though the current one has unsaved changes. Without it, the call refuses with UNSAVED_CHANGES.
signalAbortSignalnoneAn AbortSignal that cancels the load. The canvas keeps what it showed before, and the call rejects with LOAD_ABORTED.
onProgress(progress: LoadProgress) => voidnoneCalled with a LoadProgress as the load moves through its stages. The load:progress event carries the same values.

加载进度

NameTypeDefaultDescription
documentId*string | undefined—The id of the document being loaded, when it has one.
stage*LoadStage—prepare, images, objects or done.
done*number—How many images or objects are finished in this stage.
total*number—How many there are in this stage.

图片失败的原因

NameTypeDefaultDescription
url*string—The image address.
reason*ImageFailureReason—NOT_FOUND, HTTP_ERROR, CORS, NETWORK, TIMEOUT, DECODE (not a picture the browser can read) or ABORTED.
message*string—A sentence to show or log.
statusnumber—The HTTP status, when the browser lets the page read it.
timeoutMsnumber—The time limit that ran out, for TIMEOUT.

导入配置

NameTypeDefaultDescription
idstringa new idThe id of the new document.
metadataRecord<string, unknown>{}Metadata for the new document.
restoreCanvasSizeboolean—Resize the canvas to the size stored in the document.Inherited from LoadOptions.
discardUnsavedChangesbooleanfalseOpen the document even though the current one has unsaved changes. Without it, the call refuses with UNSAVED_CHANGES.Inherited from LoadOptions.
signalAbortSignalnoneAn AbortSignal that cancels the load. The canvas keeps what it showed before, and the call rejects with LOAD_ABORTED.Inherited from LoadOptions.
onProgress(progress: LoadProgress) => voidnoneCalled with a LoadProgress as the load moves through its stages. The load:progress event carries the same values.Inherited from LoadOptions.

SVG 导入配置

NameTypeDefaultDescription
viewport"preserve" | "content""preserve"preserve uses the SVG's own viewBox, width and height as the frame, so elements outside it cannot move the artwork. content uses the bounds of what is drawn.
offscreen"keep" | "drop" | "clip""keep"Elements entirely outside the viewport: keep, drop or clip.
as"group" | "objects""group"One group with a fixed layout the size of the viewport, or objects for separate objects in the same places.
preserveGroupsbooleanfalseRebuilds each <g> and <a> as a Fabric group with its id, opacity and clip path. Objects and groups get svgId, svgClass and svgData, which are saved.
leftnumber0Where the viewport's left edge lands on the canvas.
topnumber0Where the viewport's top edge lands on the canvas.
fit{ width: number; height: number; mode?: "contain" | "cover" | "fill"; }none{ width, height, mode? } scales the viewport into a box. mode is contain (default), cover or fill.
crossOrigin"anonymous" | "use-credentials" | null"anonymous"Passed to images in the SVG, so the canvas can still be exported.
signalAbortSignalnoneCancels the import with LOAD_ABORTED.
NameTypeDefaultDescription
objects*FabricObject[]—The objects added to the canvas: one group, or each object.
viewport*{ width: number; height: number; }—The size of the SVG's viewport, before fit.
warnings*SvgImportWarning[]—SVG_CONTENT_REMOVED, SVG_IMAGE_BLOCKED or SVG_OFFSCREEN_DROPPED, each with a message.

保存配置

NameTypeDefaultDescription
overwritebooleanfalseSkip the revision check and keep this version after a SAVE_CONFLICT.

保存状态

NameTypeDefaultDescription
status*SaveStatus—One of saved, unsaved, saving, error or conflict.
isDirty*boolean—Whether there are unsaved changes.
isSaving*boolean—Whether a save is running.
revision*number—The revision last saved or loaded.
lastSavedAt*string | undefined—When the last save finished, as an ISO date.
error*DocumentEngineError | undefined—The error of the last failed save.

导出配置

NameTypeDefaultDescription
format*ExportFormat—'png', 'jpeg', 'webp', 'svg' or 'json'.
scalenumber1Output size multiplier, such as 2 for retina screens.
qualitynumber0.920 to 1, for JPEG and WebP.
areaExportArea'canvas''canvas', 'content' (every object), 'selection', or { left, top, width, height }.
paddingnumber0Extra space around content or selection.
backgroundExportBackground'keep''keep', 'transparent' or any CSS color.
signalAbortSignal—An AbortSignal that cancels the export.
svgSvgExportOptions{}Options for SVG exports: curved text, and embedding images and fonts. See SvgExportOptions.

SVG 导出配置

NameTypeDefaultDescription
textOnPath"vector" | "fabric""vector"vector writes text on a path exactly as the canvas draws it. fabric keeps Fabric's own output, with a TEXT_ON_PATH_APPROXIMATED warning.
textDecorations"shapes" | "css""shapes"Underlines, overlines and line-throughs of straight text: shapes draws them where the canvas does, css keeps Fabric's text-decoration output.
embedImagesboolean | "require"falsePuts every image into the file as data. true exports anyway and warns with IMAGE_NOT_EMBEDDED; "require" blocks the export with EXPORT_BLOCKED.
maxEmbeddedImageBytesnumber25 MBLarger images are not embedded.
embedFontsRecord<string, FontSource>{}Font files to embed, by family: a URL, an ArrayBuffer, a Uint8Array or a Blob. Fonts set on single letters are embedded too.

导出结果

NameTypeDefaultDescription
format*ExportFormat—The format you asked for.
mimeType*string—The MIME type of blob.
blob*Blob—The file, ready to download or upload.
width*number—Output width in pixels.
height*number—Output height in pixels.
warnings*AssetWarning[]—Asset warnings, such as a font that fell back.
documentFabricDocument—JSON exports only: the portable document.

页面修改

setPage 接受这些字段。见撤销和重做。

NameTypeDefaultDescription
widthnumber—Page width in pixels.
heightnumber—Page height in pixels.
backgroundstring | TFiller | null—A color, gradient or pattern behind the objects.
backgroundImageFabricObject | null—A Fabric image (or object) drawn behind the objects.
overlaystring | TFiller | null—A color, gradient or pattern drawn over the objects.
overlayImageFabricObject | null—A Fabric image (or object) drawn over the objects.
clipPathFabricObject | null—A shape that clips the whole canvas.

事务配置

NameTypeDefaultDescription
rollbackbooleanfalseWhen work throws or rejects, puts the canvas back as it was, with no undo step and no unsaved change. The error is rethrown.

恢复副本配置

NameTypeDefaultDescription
sessionIdstringthe newest copyWhich tab's copy to restore, from RecoveryRecord.sessionId.
restoreCanvasSizeboolean—Resize the canvas to the size stored in the document.Inherited from LoadOptions.
discardUnsavedChangesbooleanfalseOpen the document even though the current one has unsaved changes. Without it, the call refuses with UNSAVED_CHANGES.Inherited from LoadOptions.
signalAbortSignalnoneAn AbortSignal that cancels the load. The canvas keeps what it showed before, and the call rejects with LOAD_ABORTED.Inherited from LoadOptions.
onProgress(progress: LoadProgress) => voidnoneCalled with a LoadProgress as the load moves through its stages. The load:progress event carries the same values.Inherited from LoadOptions.

适用于所有 DocumentEngine 方法的规则

  • 加载失败永远不会清空画布或只加载一半。
  • 接入存储适配器后,只要有未保存的改动,load、loadDocument、importFabricJson 和 newDocument 都会以 UNSAVED_CHANGES 拒绝,除非传入 discardUnsavedChanges: true。
  • 同一时间只有一次保存。保存期间再调用 save,会合并为一次后续保存。
  • undo 和 redo 调用按顺序执行。
  • export 不会改变画布、历史记录或未保存状态。
  • 调用 destroy() 之后,任何调用都会抛出 ENGINE_DESTROYED。

每组 DocumentEngine 方法的详细说明见指南:保存和加载、撤销和重做和导出。

DocumentEngine 方法 | Fabric.js Document Engine