协同编辑
协同编辑需要前端编辑器和服务端共同接入。请先按协同集成运行示例，再接入业务身份、权限和数据存储。前后端的配置代码见 协同快速开始。
文档由经过认证的业务 API 创建。前端拿到服务端返回的 Unit 标识后，使用下面的方法加载；再次打开同一份文档时，继续使用这个标识。
加载文档
先设置当前用户，再加载文档。当前用户决定协同编辑的身份和本地离线缓存的归属。设置当前用户后调用 Facade 方法显式加载：
TypeScript
import { UserManagerService } from '@univerjs/core'import '@univerjs-pro/collaboration-client/facade'univer.__getInjector().get(UserManagerService).setCurrentUser({ userID, name, avatar })const collaboration = univerAPI.getCollaboration()const unit = await collaboration.loadSheetAsync('your-unit-id')通过同步状态、重发与冲突恢复实现保存提示，并在刷新前保护尚未确认的修改。
移除内置 URL 加载协同文档
注意事项
从 1.2.0 版本开始，Univer 移除了内置的 URL 协同文档加载逻辑，不再自动读取 URL 中的 unit、type 和 subunit 参数来加载协同文档及定位工作表。
如果你的应用依赖这一行为，可以通过自定义插件恢复。
接入自定义插件
将下方四个文件按以下目录结构复制到项目中：
text
custom-url-load/├── plugin.ts├── controllers/│ └── data-loader.controller.ts└── services/ ├── url.service.ts └── web-url.service.ts在完成编辑器和协同插件初始化后，先设置当前用户，再注册 CustomUrlLoadPlugin。插件模式和预设模式均可使用这一接入方式：
TypeScript
import { UserManagerService } from '@univerjs/core'import { CustomUrlLoadPlugin } from './custom-url-load/plugin'univer.__getInjector().get(UserManagerService).setCurrentUser({ userID, name, avatar })univer.registerPlugin(CustomUrlLoadPlugin)注册该插件后，由插件负责加载文档，无需再为同一文档调用 loadSheetAsync()。如果应用已经通过 Facade 加载文档，可以继续使用上一节的方式，并根据业务需要自行处理 URL。
完整插件代码
TypeScript
import { UniverCollaborationClientPlugin } from '@univerjs-pro/collaboration-client'import { DependentOn, Inject, Injector, Plugin } from '@univerjs/core'import { CollaborationDataLoaderController } from './controllers/data-loader.controller'import { IURLService } from './services/url.service'import { WebURLService } from './services/web-url.service'@DependentOn(UniverCollaborationClientPlugin)export class CustomUrlLoadPlugin extends Plugin { static override pluginName = 'CUSTOM_URL_LOAD_PLUGIN' constructor( _config: undefined, @Inject(Injector) protected override readonly _injector: Injector ) { super() } override onStarting(): void { this._injector.add([IURLService, { useClass: WebURLService }]) this._injector.add([CollaborationDataLoaderController]) this.disposeWithMe(this._injector.get(IURLService)) this.disposeWithMe(this._injector.get(CollaborationDataLoaderController)) }}TypeScript
import type { ISetWorksheetActivateCommandParams } from '@univerjs/sheets'import type { Subscription } from 'rxjs'import { DataLoaderService } from '@univerjs-pro/collaboration-client'import { ICommandService, ILogService, Inject, IUniverInstanceService, RxDisposable, toDisposable, UniverInstanceType, Workbook,} from '@univerjs/core'import { SetWorksheetActivateCommand } from '@univerjs/sheets'import { takeUntil } from 'rxjs'import { IURLService } from '../services/url.service'/** * 通过 URL 参数加载协同文档，并同步同一文档中的工作表导航。 */export class CollaborationDataLoaderController extends RxDisposable { private _unitId: string | undefined private _unitType = UniverInstanceType.UNIVER_SHEET private _workbook: Workbook | null = null private _activeSheetSubscription: Subscription | null = null constructor( @IURLService private readonly _urlService: IURLService, @ILogService private readonly _logService: ILogService, @ICommandService private readonly _commandService: ICommandService, @Inject(DataLoaderService) private readonly _dataLoaderService: DataLoaderService, @IUniverInstanceService private readonly _instanceService: IUniverInstanceService ) { super() this._init() } private _init(): void { this._unitId = this._urlService.getParam('unit') const type = this._urlService.getParam('type') if (!this._unitId || !type) { return } this._unitType = Number(type) this.disposeWithMe(toDisposable(() => this._unbindWorkbook())) // 历史版本回滚可能在保留文档 ID 的同时替换 Workbook，需要重新绑定。 this._dataLoaderService.unitLoaded$.pipe(takeUntil(this.dispose$)).subscribe((unit) => { if (unit instanceof Workbook && unit.getUnitId() === this._unitId) { this._bindWorkbook(unit).catch((error: unknown) => this._reportError(error)) } }) this._instanceService.unitDisposed$.pipe(takeUntil(this.dispose$)).subscribe((unit) => { if (unit === this._workbook) { this._unbindWorkbook() } }) this._urlService.urlChange$.pipe(takeUntil(this.dispose$)).subscribe(() => { if (this._workbook) { this._activateWorksheetFromUrl(this._workbook).catch((error: unknown) => this._reportError(error)) } }) this._dataLoaderService.loadUnit(this._unitId, this._unitType, this._urlService.getParam('subunit')) .catch((error: unknown) => this._reportError(error)) } private async _bindWorkbook(workbook: Workbook): Promise<void> { this._unbindWorkbook() this._workbook = workbook // 快照回放直接更新模型，需要激活一次工作表以通知渲染层。 await this._activateWorksheetFromUrl(workbook, true) if (this._workbook !== workbook || this._disposed) { return } this._activeSheetSubscription = workbook.activeSheet$.subscribe((worksheet) => { if (worksheet) { this._updateUrl(worksheet.getSheetId()) } }) } private _unbindWorkbook(): void { this._activeSheetSubscription?.unsubscribe() this._activeSheetSubscription = null this._workbook = null } private _matchesDocument(): boolean { return this._urlService.getParam('unit') === this._unitId && Number(this._urlService.getParam('type')) === this._unitType } private async _activateWorksheetFromUrl(workbook: Workbook, forceActivate = false): Promise<void> { if (this._disposed || this._workbook !== workbook || !this._matchesDocument()) { return } const requestedSheetId = this._urlService.getParam('subunit') const worksheet = (requestedSheetId ? workbook.getSheetBySheetId(requestedSheetId) : null) ?? workbook.getSheetBySheetId(workbook.getUnhiddenWorksheets()[0]) if (!worksheet) { return } const subUnitId = worksheet.getSheetId() if (subUnitId !== requestedSheetId) { this._updateUrl(subUnitId, true) } if (!forceActivate && workbook.getActiveSheet()?.getSheetId() === subUnitId) { return } await this._commandService.executeCommand<ISetWorksheetActivateCommandParams>(SetWorksheetActivateCommand.id, { unitId: workbook.getUnitId(), subUnitId, }) } private _updateUrl(subUnitId: string, replace = false): void { if (this._matchesDocument() && this._urlService.getParam('subunit') !== subUnitId) { this._urlService.setParam('subunit', subUnitId, replace) } } private _reportError(error: unknown): void { this._logService.error('[CollaborationDataLoaderController]', error) }}TypeScript
import type { IDisposable } from '@univerjs/core'import type { Observable } from 'rxjs'import { createIdentifier } from '@univerjs/core'export interface IURLService extends IDisposable { getParam: (key: string) => string | undefined setParam: (key: string, value: string, useReplace?: boolean) => void removeParam: (key: string, useReplace?: boolean) => void readonly urlChange$: Observable<void>}export const IURLService = createIdentifier<IURLService>('demo.custom-url-load.url-service')TypeScript
import type { IURLService } from './url.service'import { RxDisposable } from '@univerjs/core'import { fromEvent, map, shareReplay, takeUntil } from 'rxjs'export class WebURLService extends RxDisposable implements IURLService { readonly urlChange$ = fromEvent(window, 'popstate').pipe( map(() => undefined), takeUntil(this.dispose$), shareReplay({ bufferSize: 1, refCount: true }) ) getParam(key: string): string | undefined { return new URL(window.location.href).searchParams.get(key) ?? undefined } setParam(key: string, value: string, useReplace = false): void { const url = new URL(window.location.href) url.searchParams.set(key, value) this._updateUrl(url, useReplace) } removeParam(key: string, useReplace = false): void { const url = new URL(window.location.href) url.searchParams.delete(key) this._updateUrl(url, useReplace) } private _updateUrl(url: URL, useReplace: boolean): void { if (useReplace) { window.history.replaceState(window.history.state, '', url.toString()) } else { window.history.pushState(window.history.state, '', url.toString()) } }}你觉得这篇文档如何？