# 协同集成

> 将 Univer 编辑器连接到协同服务，让多个用户编辑同一份文档。

- Human documentation: [https://docs.univer.ai/zh-CN/server/collaboration/browser-integration](https://docs.univer.ai/zh-CN/server/collaboration/browser-integration)

- Agent Markdown: [https://docs.univer.ai/zh-CN/server/collaboration/browser-integration.md](https://docs.univer.ai/zh-CN/server/collaboration/browser-integration.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [collaboration/browser-integration.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/server/collaboration/browser-integration.zh-CN.mdx)

---

协同集成连接前端编辑器和协同服务。例如，两位用户打开同一份表格，一方修改单元格，另一方能实时看到变化。

先按[服务端集成](https://docs.univer.ai/zh-CN/server.md)准备后端，再完成下面的前端配置和文档加载。具体代码以 [Office 快速开始](https://docs.univer.ai/zh-CN/server/collaboration/quick-start.md)中的 Server、Web 示例为准。

```mermaid
flowchart LR; A["用户 A 的编辑器"] <-->|收发修改| S["协同服务"]; S <-->|收发修改| B["用户 B 的编辑器"]; S --> D[("保存文档")];
```

## 连接已有编辑器

保留已有的 Web SDK 编辑器，按[快速开始中的前端配置](https://docs.univer.ai/zh-CN/server/collaboration/quick-start.md)添加协同插件，并配置文档加载、修改提交和 WebSocket 连接地址。前后端包版本需要匹配。

示例中的固定用户和默认权限仅用于演示。正式接入时，让编辑器请求携带应用的登录信息，由后端确认用户身份和文档权限。许可证配置见[使用许可证](https://docs.univer.ai/zh-CN/guides/license.md)。

## 创建和打开同一份文档

“新建”和“打开”是两步不同的操作：

1. 用户新建文档时，业务后端创建并保存文档，返回文档 ID。
2. 前端用这个 ID 加载文档。再次打开或分享给其他用户时，仍使用同一个 ID。

API 中的 `unitId` 就是文档 ID。不要在每次打开时重新创建本地空白文档。

例如，已经注册 Sheets 和协同插件后，可以这样打开服务端表格：

```ts
import '@univerjs-pro/collaboration-client/facade'

const workbook = await univerAPI.getCollaboration().loadSheetAsync('your-document-id')
if (!workbook) throw new Error('Document could not be loaded')
```

不同产品的加载方式见 [Sheets](https://docs.univer.ai/zh-CN/guides/sheets/features/collaboration.md)、[Docs](https://docs.univer.ai/zh-CN/guides/docs/features/collaboration.md)、[Slides](https://docs.univer.ai/zh-CN/guides/slides/features/collaboration.md)、[Boards](https://docs.univer.ai/zh-CN/guides/boards/features/collaboration.md)、[Bases](https://docs.univer.ai/zh-CN/guides/bases/features/collaboration.md) 和 [PDFs](https://docs.univer.ai/zh-CN/guides/pdfs/features/collaboration.md)。使用前确认对应产品与目标服务端版本支持该能力。

## 验证同步、保存和权限

用两个独立浏览器会话打开同一文档，例如普通窗口和无痕窗口。在一端修改内容，检查另一端是否收到；刷新页面、断线重连和服务重启后，再检查内容是否保留。

随后用编辑者、查看者和无权限用户验证访问规则。前端只读设置控制界面操作，服务端仍需拒绝无权限的读取和修改请求。

如果文档能打开但修改不同步，先检查 WebSocket 连接；如果重启后内容丢失，检查后端存储。相应配置见[服务端集成](https://docs.univer.ai/zh-CN/server.md)。

## 添加导入导出、评论或历史记录

导入文件后多人编辑，需要将转换结果创建为协同文档，见[导入导出集成](https://docs.univer.ai/zh-CN/server/import-export.md)。评论和历史记录需要各自的插件、后端服务及权限，按 [Office 协同扩展模块](https://docs.univer.ai/zh-CN/server/collaboration/extensions.md)接入。

历史面板的前端配置见 [Sheets](https://docs.univer.ai/zh-CN/guides/sheets/features/edit-history.md), [Docs](https://docs.univer.ai/zh-CN/guides/docs/features/edit-history.md), [Slides](https://docs.univer.ai/zh-CN/guides/slides/features/edit-history.md), [Boards](https://docs.univer.ai/zh-CN/guides/boards/features/edit-history.md), [Bases](https://docs.univer.ai/zh-CN/guides/bases/features/edit-history.md)。PDFs 的支持范围见[历史记录说明](https://docs.univer.ai/zh-CN/guides/pdfs/features/edit-history.md)。