集成协作提供者

协作提供者与协作后端一起，构成了实时协同编辑的基础架构。它们建立并管理用户之间的通信通道，确保文档的更新和更改在所有参与者之间同步。

提供者处理实时数据交换的复杂性，包括冲突解决、网络可靠性和用户在线状态感知。

TiptapCollabProvider 增加了针对协作环境的高级功能，如 WebSocket 消息认证、调试模式和灵活的连接策略。

设置提供者

首先，在您的项目中使用以下命令安装提供者包（确保使用提供者 v2，因为 v3 需要 Tiptap v3，而 Tiptap v3 仍处于测试阶段）：

设置私有注册表

请注意，您需要按照这里的说明设置对私有注册表的访问。

此外，您可能需要将以下行添加到您的 .npmrc 文件中：

@tiptap-cloud:registry=https://registry.tiptap.dev/

npm install @tiptap-pro/provider

对于基本设置，请通过指定文档名称、您的文档服务器 ID（在您的云仪表板中标记为"Document server ID"）用于云部署，或用于本地部署的基础 URL，以及您的 JWT，来连接到协作后端。

根据您的框架，注册连接到协作后端的回调，如 React 中的 useEffect() 或 Vue.js 中的 onMounted()。

const doc = new Y.Doc()

useEffect(() => {
  const provider = new TiptapCollabProvider({
    name: note.id, // 文档标识符
    appId: 'YOUR_APP_ID', // 从云仪表板替换为您的文档服务器 ID
    token: 'YOUR_JWT', // 认证令牌
    document: doc,
    user: userId,
  })
}, [])

本地部署用户的提示

如果您在本地托管协作环境，请在提供者配置中用 baseUrl 替换 appId 参数，以连接到您的服务器。

配置协作提供者

Tiptap 协作提供者支持多种设置，用于自定义配置。请查看下表，了解所有参数、实际用例及诸如“awareness”等关键概念。

设置	默认值	说明
`appId`	`''` （空）	您的文档服务器 ID（在云仪表板中标记为"Document server ID"），用于协作云部署
`baseUrl`	`''` （空）	用于连接本地部署服务器的 URL。在本地部署设置中用作 `appId` 的替代方案
`shardKey`	`''` （空）	仅在使用 Tiptap Collab HA 时使用。通常这会设置为文档名称或团队 ID
`name`	`''` （空）	文档的名称
`token`	`''` （空）	用于安全连接的认证令牌。支持字符串、函数和 Promises
`document`	`new Y.Doc()`	Yjs 文档实例。如果未提供，默认为新文档
`user`	`null`	用于归因文档更改的用户 ID 或名称
`forceSyncInterval`	`false`	以毫秒为单位，强制定期与服务器同步

优化重连时间

提供者的重连设置预设为生产环境的最佳性能。如需针对特定场景调整这些参数，可通过延迟配置完成。

您可以调整初始延迟、应用指数退避，或设置最大等待时间，以微调应用的重连行为，平衡响应速度和服务器效率。

设置名	默认值	说明
`delay`	`1000`	两次重连尝试之间的基础延迟，单位毫秒
`factor`	`2`	延迟倍率，每次尝试后指数级增加
`initialDelay`	`0`	第一次重连尝试前的延迟时间，单位毫秒
`maxAttempts`	`0`	最大重连尝试次数。`0` 表示无限次
`jitter`	`true`	是否添加抖动，通过在 `minDelay` 和计算延迟之间随机选取值增加重连的随机性
`minDelay`	`1000`	启用抖动时的最小延迟。如果禁用抖动则无效
`maxDelay`	`30000`	重连尝试之间允许的最大延迟。设置为 `0` 时，延迟将无限制增长，遵循指数退避（`factor`）规律
`timeout`	`0`	每次重连尝试的最大持续时间，单位毫秒，超时则停止尝试
`messageReconnectTimeout`	`30000`	等待服务器消息的时间上限，单位毫秒。若未收到消息，连接将自动关闭

注意：这些设置仅能在单独创建 TiptapCollabProviderWebsocket 实例时配置。然后，您需要将其传递给 TiptapCollabProvider（作为 websocketProvider 参数）。

未同步的更改

提供者维护一个整数，跟踪未同步的更改数量。每当服务器接收到一项更改后，会发送确认，提供者则减少计数。

您应监控此计数器，并在用户离开页面前或经过一定超时或未同步更改数量后，通知用户其更改尚未同步。

“更改”可以是单个字符、单个节点或整个文档，取决于您的自定义用例，因此通常计数应为 0 或略高，但仅在很短时间内存在（主要是连接延迟）。

您可以通过访问 TiptapCollabProvider.unsyncedChanges 获取当前计数，或订阅 unsyncedChanges 事件。

TiptapCollabProvider.on('unsyncedChanges', n => console.log(`${n.number} 个未同步的更改`))

速率限制

为维护系统稳定性并防止配置错误的客户端，我方基础设施（包括管理 API 和通过 TiptapCollabProvider 的 WebSocket 连接）均受速率限制管理。

默认速率限制（每来源 IP）：

请求数： 100 次
时间窗口： 5 秒
突发容量： 最多 200 次请求

如在正常使用情况下遇到限制，请通过电子邮件联系我们。

Previously认证

Next up事件