Fabric.js Document Engine

Search documentation

Find a page or section

中文

DocumentEngine

View as Markdown

The object createDocumentEngine returns.

createDocumentEngine returns a DocumentEngine. The table below lists all DocumentEngine methods and properties. Methods that touch storage or the canvas return a promise.

Members

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.

Method options

Load options

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.

Load progress

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.

Why an image failed

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.

Import options

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 import options

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.

Save options

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

Save state

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.

Export options

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 export options

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.

Export result

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.

Page changes

setPage takes these fields. See undo and redo.

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.

Transaction options

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.

Restore recovery options

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.

Rules that apply to all DocumentEngine methods

  • A failed load never clears or half-fills the canvas.
  • With a storage adapter, load, loadDocument, importFabricJson and newDocument refuse with UNSAVED_CHANGES while there are unsaved changes, unless you pass discardUnsavedChanges: true.
  • Only one save runs at a time. save calls made during a save merge into one follow-up.
  • undo and redo calls run in order.
  • export never changes the canvas, the history or the unsaved state.
  • After destroy(), every call throws ENGINE_DESTROYED.

The guides explain each group in depth: save and load, undo and redo and export.