# createDocumentEngine

> createDocumentEngine 配置项全列表：存储、自动保存、历史记录上限、资源、恢复、版本和安全限制。

Source: https://fabricjs-document-engine.jscrate.dev/zh/docs/api/create-document-engine
Last updated: 2026-09-28

`createDocumentEngine` 把引擎连接到现有的 Fabric.js 画布，并返回一个 [`DocumentEngine`](https://fabricjs-document-engine.jscrate.dev/zh/docs/api/document-engine)。下面列出所有 createDocumentEngine 配置项。

```ts
function createDocumentEngine(options: DocumentEngineOptions): DocumentEngine
```

Connects the engine to an existing Fabric.js canvas. The canvas stays yours: the engine only listens to it, and changes it when you load, undo or restore.

## 用法

```ts
import { createDocumentEngine } from "fabricjs-document-engine";
import { createLocalStorage } from "fabricjs-document-engine/storage";

const engine = createDocumentEngine({
  canvas,
  storage: createLocalStorage(),
  autosave: true,
  history: { limit: 50 },
});
```

只有 `canvas` 是必填的。没有 `storage`（存储）时，仍然可以用 `toDocument()` 保存、用 `loadDocument()` 加载，但 `save()`、`load(id)`、自动保存和版本都不可用。

## createDocumentEngine 配置项

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `canvas` (required) | `StaticCanvas` | — | Your Fabric.js canvas, a `Canvas` or a `StaticCanvas`. |
| `storage` | `DocumentStorage` | `none` | Where documents are saved and loaded. Needed for `load`, `save`, autosave and versions. |
| `customObjects` | `CustomObjectDefinition[]` | `[]` | Your own Fabric classes and the extra properties they need to keep. |
| `document` | `NewDocumentOptions` | `a new id` | The `id` and `metadata` of the first, empty document. |
| `history` | `HistoryOptions` | `{ limit: 100, maxBytes: 64 MB }` | How many undo steps to keep, and how much memory they may use. |
| `autosave` | `boolean \| AutosaveOptions` | `off` | Saves on its own after edits. `true` means `{ delay: 1000, maxWait: 10000 }`. Needs `storage`. |
| `saveRetry` | `RetryOptions` | `{ attempts: 3, baseDelay: 500, maxDelay: 8000 }` | How failed saves are retried. |
| `assets` | `AssetOptions` | `{}` | How images and fonts are resolved, checked and uploaded. |
| `recovery` | `RecoveryOptions` | `off` | Keeps local copies of unsaved work, so it can be restored after a crash or refresh. |
| `versions` | `VersionOptions` | `{ autoEvery: 0, keepAuto: 20 }` | Keeps an automatic version every N saves, and how many of them to keep. |
| `limits` | `ContentLimits` | `{ maxObjects: 50000, maxDepth: 100 }` | Safety limits for documents that are loaded or imported. |

## 嵌套配置项

### 自动保存

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | `1000` | Save after this many milliseconds without an edit. |
| `maxWait` | `number` | `10000` | Save at the latest this many milliseconds after the first unsaved edit, even while the user keeps editing. |

### 保存重试

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `attempts` | `number` | `3` | How many times to retry. |
| `baseDelay` | `number` | `500` | The first wait, in milliseconds. |
| `maxDelay` | `number` | `8000` | The longest wait, in milliseconds. |

### 历史记录

撤销的步数上限和内存上限：

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | `number` | `100` | How many undo steps to keep. |
| `maxBytes` | `number` | `64 MB` | The memory undo history may use. The oldest steps are dropped first. |

### 资源

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `resolveUrl` | `(url: string) => string \| Promise<string>` | — | Rewrites each stored image URL before loading, for example to sign it or map it to a CDN. |
| `replaceMissingImage` | `(image: ImageAsset) => string \| null \| undefined \| Promise<string \| null \| undefined>` | — | Supplies a replacement URL for an image that did not load. Return `null` to leave it missing. |
| `upload` | `(request: UploadRequest) => Promise<string>` | — | Stores `blob:` and `data:` images while saving, and returns their permanent URL. |
| `loadFont` | `FontLoader` | — | Loads a font before text is created. |
| `checkImages` | `boolean` | `true` | Set to `false` to skip loading images during the check. |
| `requireFonts` | `boolean` | `false` | Fail loading with `MISSING_FONTS`, and export with `MISSING_FONT`, instead of warning. |

### 自定义对象

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fabricClass` (required) | `{ type: string; fromObject?: unknown; }` | — | Your Fabric class. It needs a static `type`. |
| `properties` | `string[]` | `[]` | The extra properties to save and load with the object. |

### 恢复

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` (required) | `RecoveryStore` | — | Where copies are kept, such as `createIndexedDbRecovery()`. |
| `interval` | `number` | `2000` | Write a copy at most once every this many milliseconds while there are unsaved changes. |

### 版本

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `keepAuto` | `number` | `20` | How many automatic versions to keep. Named versions are never pruned. |
| `autoEvery` | `number` | `0 (off)` | Keep an automatic version after every N successful saves. |

### 限制

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `maxObjects` | `number` | `50000` | Refuse documents with more objects than this. |
| `maxDepth` | `number` | `100` | Refuse documents nested deeper than this. |
| `isAllowedUrl` | `(url: string) => boolean` | `isSafeImageUrl` | Decides which image addresses may be fetched, after `resolveUrl`. |

大部分 createDocumentEngine 配置项只在创建引擎时读取一次。要修改它们，请创建一个新引擎。