---
title: "配置 Hocuspocus 提供者"
canonical_url: "https://tiptap.zhcndoc.com/hocuspocus/provider/configuration"
---

# 配置 Hocuspocus 提供者

## 设置

### HocuspocusProvider

| 设置                  | 描述                                                                                                                                                                           | 默认值                                 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `url`               | Hocuspocus/WebSocket 服务器的 URL。                                                                                                                                               | `''`                                |
| `websocketProvider` | HocuspocusProviderWebsocket 的实例，如果你想在多个 provider 之间共享一个 socket                                                                                                               | `new HocuspocusProviderWebsocket()` |
| `name`              | 文档名称。                                                                                                                                                                        | `''`                                |
| `document`          | 实际的 Y.js 文档。可选，默认情况下会创建一个新文档，并可通过 provider.document 访问。                                                                                                                      | `new Y.Doc()`                       |
| `token`             | 将传递给服务器的身份验证令牌（支持字符串、函数和 Promises）。                                                                                                                                          | `''`                                |
| `awareness`         | Awareness 对象，默认情况下会附加到传入的 Y.js 文档上。                                                                                                                                          | `new Awareness()`                   |
| `forceSyncInterval` | 每隔 x 毫秒向服务器请求更新。                                                                                                                                                             | `false`                             |
| `sessionAwareness`  | 在每条消息的文档名称中嵌入唯一的 `sessionId`，允许在同一个 WebSocket 上使用具有相同文档名称的多个 provider。连接到 v3 服务器时保持 `false`。需要 v4 服务器。                                                                       | `false`                             |
| `flushDelay`        | 在一个短时间窗口内批量发送文档和 awareness 更新，而不是每次变更都发送一条消息。可减少大量编辑时的 websocket 流量。新增延迟最多为 `flushDelay`，因此应保持较小值（例如 `500`）。设置为 `false` 可立即发送每次变更。参见 [批量发送外发更新](#batching-outgoing-updates)。 | `false`                             |

### HocuspocusProviderWebsocket

| 设置                        | 描述                                                       | 默认值         |
| ------------------------- | -------------------------------------------------------- | ----------- |
| `url`                     | Hocuspocus/WebSocket 服务器的 URL。                           | `''`        |
| `WebSocketPolyfill`       | 在 Node.js 环境中运行时：传入 WebSocket 的 polyfill，例如 ws。          | `WebSocket` |
| `timeout`                 | 毫秒为单位的超时时间。如果超时非零，则设置一个 setTimeout 定时器触发。如果触发超时，后续尝试将终止。 | `0`         |
| `factor`                  | 用于以指数方式增长延迟的因子选项。                                        | `2`         |
| `maxAttempts`             | 最大尝试次数，若为 0，则尝试次数无上限。                                    | `0`         |
| `minDelay`                | 当抖动（jitter）启用时，用于设置延迟的下限。如果关闭抖动，则此属性无效。                  | `1000`      |
| `maxDelay`                | 用于设置当启用因子调整时的延迟上限。如果不需要上限，可设置为 0。                        | `30000`     |
| `jitter`                  | 若为 true，则当前迭代的延迟将在 minDelay 与计算得出的延迟之间随机取整数值。            | `true`      |
| `messageReconnectTimeout` | 如果在配置的 messageReconnectTimeout 时间内未收到消息，则关闭连接。           | `30000`     |
| `delay`                   | 每次尝试之间的延迟时间（毫秒）。可传入因子以实现延迟指数增长。                          | `1000`      |
| `initialDelay`            | 首次尝试前的等待时间。该选项通常为 0，因为通常希望首次尝试立即进行。                      | `0`         |

## 使用

## 使用

设置提供程序所需的内容并不多，简单示例可以在 [快速开始](https://tiptap.zhcndoc.com/hocuspocus/provider/install.md) 中找到

## 批量发送出站更新

默认情况下，提供程序每次变更都会发送一条 websocket 消息。在重度编辑期间——快速输入、大段粘贴，或光标快速移动——这可能会产生很多小消息。将 `flushDelay` 设为一个毫秒数，可以在一个短时间窗口内批量发送出站文档更新和 awareness 更新：

```js
import { HocuspocusProvider } from '@hocuspocus/provider'

const provider = new HocuspocusProvider({
  url: 'ws://127.0.0.1:1234',
  name: 'example-document',
  flushDelay: 500,
})
```

在每个窗口内，缓冲的 Yjs 更新会通过 `Y.mergeUpdates` 合并为一条消息，而 awareness 会折叠为每个已变更客户端的最新状态。这个窗口是固定批次，而不是会重置的防抖，因此即使用户持续输入，新增延迟也会被限制在 `flushDelay` 之内——请将其保持较小（例如 `500`），以避免延迟其他客户端看到的内容。

你可以通过调用 `provider.flushPendingUpdates()` 强制立即发送当前窗口中所有已缓冲的内容。