# React hooks

> Fabric.js React hooks 参考：创建引擎、读取文档状态、订阅事件，以及在组件树里传递引擎。

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

这些 Fabric.js React hooks 位于 `fabricjs-document-engine/react`。这个入口标记了 `'use client'`，React 是可选的 peer 依赖：核心代码从不导入它。支持 React 18 和 19。

```tsx
import {
  DocumentEngineProvider,
  useDocumentEngine,
  useDocumentEvent,
  useDocumentState,
  useEngine,
} from "fabricjs-document-engine/react";
```

## useDocumentEngine

```ts
function useDocumentEngine(canvas: StaticCanvas | null | undefined, options?: ReactEngineOptions): DocumentEngine | null
```

Creates the engine once `canvas` exists and destroys it on unmount. Returns `null` until then. Options are read when the engine is created.

配置项和 [`createDocumentEngine`](https://fabricjs-document-engine.jscrate.dev/zh/docs/api/create-document-engine) 相同，只是没有 `canvas`。

## useDocumentState

```ts
function useDocumentState(engine: DocumentEngine | null | undefined): DocumentState | null
```

Returns `DocumentState`, or `null` without an engine, and re-renders when any of it changes.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `documentId` (required) | `string` | — | The current document id. |
| `isLoading` (required) | `boolean` | — | Whether a load is running. |
| `loadError` (required) | `DocumentEngineError \| undefined` | — | The error of the last failed load. |
| `saveStatus` (required) | `SaveStatus` | — | `saved`, `unsaved`, `saving`, `error` or `conflict`. |
| `isDirty` (required) | `boolean` | — | Whether there are unsaved changes. |
| `isSaving` (required) | `boolean` | — | Whether a save is running. |
| `revision` (required) | `number` | — | The revision last saved or loaded. |
| `lastSavedAt` (required) | `string \| undefined` | — | When the last save finished. |
| `saveError` (required) | `DocumentEngineError \| undefined` | — | The error of the last failed save. |
| `canUndo` (required) | `boolean` | — | Whether there is a step to undo. |
| `canRedo` (required) | `boolean` | — | Whether there is a step to redo. |
| `undoLabel` (required) | `string \| undefined` | — | The label of the next undo step. |
| `redoLabel` (required) | `string \| undefined` | — | The label of the next redo step. |
| `assetWarnings` (required) | `AssetWarning[]` | — | Warnings from the last load, such as a font that fell back. |

## useDocumentEvent

```ts
function useDocumentEvent<Name extends keyof DocumentEngineEvents>(engine: DocumentEngine | null | undefined, name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): void
```

Subscribes to an engine event, always calling the latest `handler`.

事件名和数据列在[事件](https://fabricjs-document-engine.jscrate.dev/zh/docs/api/events)里。

## DocumentEngineProvider 和 useEngine

```ts
function DocumentEngineProvider({ engine, children }: DocumentEngineProviderProps): ReactNode
```

Passes the engine down to deeply nested toolbars.

```ts
function useEngine(): DocumentEngine | null
```

Reads the engine from the nearest `DocumentEngineProvider`.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine` (required) | `DocumentEngine \| null` | — | The engine from `useDocumentEngine`. |
| `children` | `ReactNode` | — | Your editor UI. |

这些 Fabric.js React hooks 组合使用的完整示例见 [React 指南](https://fabricjs-document-engine.jscrate.dev/zh/docs/frameworks/react)。其他框架可以用 [`createDocumentStateStore`](https://fabricjs-document-engine.jscrate.dev/zh/docs/api/helpers)，不依赖 React 也能拿到同样的 `DocumentState`。