# 存储 API

> 存储适配器 API 参考：内置的 localStorage 和内存适配器、适配器检查，以及 DocumentStorage 接口。

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

存储适配器 API 分两部分：`fabricjs-document-engine/storage` 里的内置适配器，以及你自己的适配器要实现的 `DocumentStorage` 接口。

## 内置适配器

```ts
function createLocalStorage(options?: LocalStorageOptions): ManagedDocumentStorage
```

The same as `createMemoryStorage`, backed by `localStorage`. Also offers `listDocuments()` and `deleteDocument(id)`.

```ts
function createMemoryStorage(): ManagedDocumentStorage
```

In-memory storage with revisions, listing and versions. Useful for tests and demos.

```ts
function createKeyValueStorage(store: KeyValueStore, prefix: string): ManagedDocumentStorage
```

The same, on any key-value store that has `{ read, write, remove, keys }`.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `prefix` | `string` | — | Prefix for every key, so several apps can share one origin. |
| `storage` | `Storage` | `localStorage` | Another `Storage` object, such as `sessionStorage`. |

内置适配器还提供 `listDocuments()` 和 `deleteDocument(id)`，并支持版本。

## 检查适配器

```ts
function verifyStorageAdapter(storage: DocumentStorage): Promise<AdapterReport>
```

Runs the storage contract against your adapter and returns `{ ok, checks }`, so you know it follows the save rules.

每项检查的含义见[检查适配器](https://fabricjs-document-engine.jscrate.dev/zh/docs/storage/verify-adapter)。

## DocumentStorage 接口

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `loadDocument` (required) | `(id: string): Promise<unknown>` | — | Returns the stored document, or plain Fabric JSON. |
| `saveDocument` (required) | `(document: FabricDocument, context: SaveContext): Promise<void \| SaveResult>` | — | Stores the document. Throw an error with `code: 'SAVE_CONFLICT'` when the stored revision differs from `expectedRevision`. Return `{ revision }` if your backend assigns its own number. |

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `expectedRevision` (required) | `number \| null` | — | The revision this editor last saved or loaded. `null` when the user chose to overwrite. |
| `signal` (required) | `AbortSignal` | — | Aborted when another document is opened. Pass it to `fetch`. |

## 版本

存储适配器实现下面四个方法，就能支持版本：

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `saveVersion` (required) | `(version: DocumentVersion): Promise<void>` | — | Stores a full copy of the document as a version. |
| `listVersions` (required) | `(documentId: string): Promise<VersionSummary[]>` | — | Version summaries for a document, newest first. |
| `loadVersion` (required) | `(documentId: string, versionId: string): Promise<DocumentVersion>` | — | Returns one version. |
| `deleteVersion` (required) | `(documentId: string, versionId: string): Promise<void>` | — | Deletes one version. |

## 冲突

```ts
function createConflictError(documentId: string, expectedRevision: number, actualRevision: number): DocumentEngineError
```

A `SAVE_CONFLICT` error for your storage adapter to throw.

这套存储适配器 API 背后的规则，以及完整的 REST 示例，见[自定义后端](https://fabricjs-document-engine.jscrate.dev/zh/docs/storage/custom-backend)。