# 事件

> 每个文档引擎事件及其数据：save:status、history:change，以及加载、恢复、导出和版本事件，还有怎么取消订阅。

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

引擎通过文档引擎事件告诉你它在做什么。用 `engine.on(name, handler)` 订阅，它会返回一个取消订阅的函数。数据的类型由 `DocumentEngineEvents` 完整定义。

```ts
const unsubscribe = engine.on("save:status", ({ status }) => {
  statusLabel.textContent = status;
});

unsubscribe();
```

在 React 里，`useDocumentEvent(engine, name, handler)` 会始终使用最新的处理函数订阅。

## 全部文档引擎事件

| 事件                  | 数据                                         | 触发时机               |
| --------------------- | -------------------------------------------- | ---------------------- |
| `load:start`          | `{ documentId }`                             | 开始加载               |
| `document:change`     | `{ documentId }`                             | 打开了另一份文档       |
| `load:success`        | `{ document, warnings, migratedFrom }`       | 加载完成               |
| `load:error`          | `{ error }`                                  | 加载失败，画布不变     |
| `assets:warning`      | `{ warnings }`                               | 图片或字体需要注意     |
| `save:start`          | `{ document }`                               | 开始保存               |
| `save:success`        | `{ document }`                               | 保存完成               |
| `save:error`          | `{ error }`                                  | 重试后仍然保存失败     |
| `save:retry`          | `{ attempt, delay, error }`                  | 失败的保存将要重试     |
| `save:status`         | `SaveState`                                  | 保存状态变化           |
| `history:change`      | `{ canUndo, canRedo, undoLabel, redoLabel }` | 撤销或重做状态变化     |
| `history:error`       | `{ error }`                                  | 撤销或重做无法重建对象 |
| `recovery:checkpoint` | `{ documentId, savedAt }`                    | 写入了一份恢复副本     |
| `recovery:restored`   | `{ document }`                               | 恢复了一份副本         |
| `recovery:error`      | `{ error }`                                  | 无法写入恢复副本       |
| `export:success`      | `{ format, width, height, warnings }`        | 导出完成               |
| `export:error`        | `{ error }`                                  | 导出失败               |
| `version:created`     | `VersionSummary`                             | 保存了一个版本         |
| `version:restored`    | `{ version, document }`                      | 恢复了一个版本         |
| `version:error`       | `{ error }`                                  | 自动版本失败           |

每个 `error` 都是带稳定 `code` 的 `DocumentEngineError`。详见[错误码](https://fabricjs-document-engine.jscrate.dev/zh/docs/api/error-codes)。

## 大多数应用需要的几个

- `save:status` 驱动保存状态提示。
- `history:change` 驱动撤销和重做按钮。
- `load:error` 和 `save:error` 驱动错误提示。

如果想一次拿到所有值，`createDocumentStateStore` 会把这些文档引擎事件合并成一个快照。详见[原生 JavaScript](https://fabricjs-document-engine.jscrate.dev/zh/docs/frameworks/vanilla-js)。