# 滤镜 API

> createFilterWorker 配置项、它返回的 FilterWorker、用于进度和取消的配置，以及分步运行的滤镜流水线。

Source: https://fabricjs-document-engine.jscrate.dev/zh/docs/api/filters-api
Last updated: 2026-10-02

Worker 怎样运行滤镜、哪些浏览器会使用它，见[图片滤镜](https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/image-filters)指南。

```ts
import {
  canRunInWorker,
  createFilterWorker,
  runFilterPipeline,
} from "fabricjs-document-engine/filters";
```

## createFilterWorker 配置项

```ts
function createFilterWorker(options?: FilterWorkerOptions): FilterWorker
```

Runs Fabric image filters in a Web Worker, with progress, cancel and newest-run-wins.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `createWorker` | `() => Worker` | `the shipped worker` | Makes a worker, for bundlers that need their own worker setup. |
| `worker` | `boolean` | `true` | `false` runs filters in steps on the main thread instead. |
| `poolSize` | `number` | `1` | Workers to run at once. |
| `bandRows` | `number` | `64` | Rows per step for pixel filters. |
| `engine` | `DocumentEngine` | `none` | Records each finished run as one undo step and drops runs that finish after another document opened. |

## FilterWorker

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `apply` (required) | `(image: FabricImage, filters?: ImageFilter[], options?: ApplyFilterOptions): Promise<boolean>` | — | Applies filters to an image. Resolves `true` when it changed, `false` when a newer run replaced it. Rejects with the signal's reason when aborted. |
| `mode` (required) | `"worker" \| "main-thread"` | — | `worker` or `main-thread`. |
| `terminate` (required) | `(): void` | — | Stops the workers. Runs still going resolve `false`. |

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `signal` | `AbortSignal` | `none` | Cancels the run; the image is left as it was. |
| `onProgress` | `(done: number) => void` | `none` | Called with the share done, from 0 to 1. |

## 流水线

`runFilterPipeline` 就是 Worker 运行的内容。它也可以在主线程上处理任意 `ImageData`，用在你自己的工具里。

```ts
function runFilterPipeline(filters: readonly PipelineFilter[], state: PipelineState, options?: PipelineOptions): Promise<ImageData | undefined>
```

Runs filters on `ImageData` in steps, with progress and cancel.

```ts
function canRunInWorker(filters: ReadonlyArray<{
  type?: unknown;
  subFilters?: unknown[];
}>): boolean
```

True when every filter, inside `Composed` ones too, can run in a worker.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bandRows` | `number` | `64` | Rows per step for pixel filters. |
| `onProgress` | `(done: number) => void` | `none` | Called after each step with the share done. |
| `isCancelled` | `() => boolean` | `none` | Checked after each step; `true` stops the run. |
| `pause` | `() => Promise<void>` | `none` | Lets other work run between steps. |

`PIXEL_FILTERS` 和 `WORKER_FILTERS` 分别列出按行分块运行的滤镜类型，以及 Worker 能运行的所有类型。其他滤镜会让 `apply` 使用 Fabric 的 `applyFilters`，不论 createFilterWorker 配置项怎样设置。