Collaboration

Packages	`@univerjs-pro/collaboration-client`

Load collaborative units, observe collaborators and synchronization state, and wait for pending changes to reach the server.

TypeScript

import '@univerjs-pro/collaboration-client/facade'const collaboration = univerAPI.getCollaboration()

Unit loading

TypeScript

loadSheetAsync(unitId: string, context?: ILogContext): Promise<FWorkbook | null>loadDocAsync(unitId: string, context?: ILogContext): Promise<FDocument | null>loadBaseAsync(unitId: string, context?: ILogContext): Promise<FBase | null>loadSlideAsync(unitId: string, context?: ILogContext): Promise<FPresentation | null>loadBoardAsync(unitId: string, context?: ILogContext): Promise<FBoard | null>loadPdfAsync(unitId: string, context?: ILogContext): Promise<FPdf | null>

Each method loads the server snapshot, waits until collaboration is ready, and returns the matching Facade object. It returns null when the unit cannot be loaded as the requested type.

TypeScript

const board = await collaboration.loadBoardAsync('board-unit-id')if (!board) throw new Error('Board not found')

PDF loading requires the PDF Facade entry in addition to collaboration:

TypeScript

import '@univerjs-pro/pdfs/facade'const pdf = await collaboration.loadPdfAsync('pdf-unit-id')

For lower-level access, univerAPI also exposes:

TypeScript

loadServerUnit(unitId: string, unitType: UniverInstanceType, subUnitId?: string): Promise<UnitModel | null>loadServerUnitOfRevision(unitId: string, unitType: UniverInstanceType, rev: number): Promise<UnitModel | null>

Synchronization

TypeScript

getCollaborationStatus(unitId?: string): CollaborationStatusflush(unitId?: string, options?: { timeout?: number }): Promise<void>

getCollaborationStatus() uses the focused unit when unitId is omitted and returns NOT_COLLAB when collaboration is unavailable. Other statuses include SYNCED, PENDING, AWAITING, AWAITING_WITH_PENDING, FETCH_MISS, CONFLICT, and OFFLINE.

Use flush() as an explicit barrier after a batch of Facade mutations. It resolves at SYNCED, defaults to a 30-second timeout, and rejects when there is no target unit, collaboration is unavailable, a conflict occurs, or the timeout expires. Temporary offline status remains waitable.

TypeScript

document.insertText(0, 'Saved through collaboration')await collaboration.flush(document.getId(), { timeout: 15_000 })

Collaborators

TypeScript

subscribeCollaborators(unitId: string, callback: (members: IMember[]) => void): IDisposable

Dispose the returned handle when the subscription is no longer needed.

TypeScript

const subscription = collaboration.subscribeCollaborators('unit-id', (members) => {  console.log(members)})subscription.dispose()

Source: @univerjs-pro/collaboration-client

How is this guide?