FCollaboration

The Facade API object for the Collaboration module. It provides methods to interact with the Univer Collaboration backend server, such as loading Univer Sheets and subscribing to collaborators.

Access

Access through:

• FUniver.getCollaboration()

Setup

Register @univerjs-pro/collaboration-client or a preset that includes it. In plugin mode, import @univerjs-pro/collaboration-client/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs-pro/collaboration-client

FCollaboration.flush

Wait until all currently queued collaboration changes for a unit are synchronized.

This is intended as an explicit barrier for scripts, agents, and tests after a batch of facade mutations. It does not make individual facade APIs asynchronous.

flush(unitId?: string, options?: ICollaborationFlushOptions): Promise<void>

Parameters

• unitId — Optional. Optional unit ID. If omitted, uses the focused unit.
• options — Optional. Default: {}. Optional timeout configuration.

Returns

Resolves when the unit reaches CollaborationStatus.SYNCED.

Examples

const collaboration = univerAPI.getCollaboration()document.insertText(0, 'Saved through collaboration')await collaboration.flush(document.getId())

Types: Promise · ICollaborationFlushOptions

Package: @univerjs-pro/collaboration-client · Type definitions

FCollaboration.getCollaborationStatus

Get the synchronization status of a unit.

getCollaborationStatus(unitId?: string): CollaborationStatus

Parameters

• unitId — Optional. Optional unit ID. If not provided, uses the focused unit.

Returns

The current synchronization status. Returns CollaborationStatus.NOT_COLLAB if no unit is found or collaboration is not enabled.

Possible status values:

• NOT_COLLAB: Not in collaboration mode
• SYNCED: All changes are synchronized
• PENDING: Local changes waiting to be sent
• AWAITING: Changes sent, waiting for server acknowledgement
• AWAITING_WITH_PENDING: Awaiting acknowledgement with new local changes
• FETCH_MISS: Fetching missing changesets from server
• CONFLICT: Conflict detected and being resolved
• OFFLINE: Network is offline

Examples

const collaboration = univerAPI.getCollaboration()// Node environment - specify unitIdconst workbook = await collaboration.loadSheetAsync('unit-id')await new Promise((resolve) => setTimeout(resolve, 1000)) // Wait for collaboration to initializeconst status = collaboration.getCollaborationStatus('unit-id')// Browser environment - use focused unit (backward compatible)const status = collaboration.getCollaborationStatus()// Check if synchronizedif (status === univerAPI.Enum.CollaborationStatus.SYNCED) {  console.log('All changes are synced!')}

Types: CollaborationStatus

Package: @univerjs-pro/collaboration-client · Type definitions

FCollaboration.loadBaseAsync

Load a Univer Base from the server with a unit ID.

loadBaseAsync(unitId: string, context?: ILogContext): Promise<FBaseFacade | null>

Parameters

• unitId — Required. ID of the Univer Base that you would like to load.
• context — Optional. Optional context.

Returns

The Base facade or null if ID cannot be associated with a Univer Base.

Examples

const collaboration = univerAPI.getCollaboration()const base = await collaboration.loadBaseAsync('your-unit-id')

Types: FBaseFacade · Promise · ILogContext

Package: @univerjs-pro/collaboration-client · Type definitions

FCollaboration.loadBoardAsync

Load a Univer Board from the server with a unit ID.

loadBoardAsync(unitId: string, context?: ILogContext): Promise<FBoard | null>

Parameters

• unitId — Required. ID of the Univer Board that you would like to load.
• context — Optional. Optional context.

Returns

The FBoard or null if ID cannot be associated with a Univer Board.

Examples

const collaboration = univerAPI.getCollaboration()const board = await collaboration.loadBoardAsync('your-unit-id')

Types: FBoard · Promise · ILogContext

Package: @univerjs-pro/collaboration-client · Type definitions

FCollaboration.loadDocAsync

Load a Univer Document from the server with a unit ID.

loadDocAsync(unitId: string, context?: ILogContext): Promise<FDocument | null>

Parameters

• unitId — Required. ID of the Univer Document that you would like to load.
• context — Optional. Optional context.

Returns

The FDocument or null if ID cannot be associated with a Univer Document.

Examples

const collaboration = univerAPI.getCollaboration()const document = await collaboration.loadDocAsync('your-unit-id')

Types: FDocument · Promise · ILogContext

Package: @univerjs-pro/collaboration-client · Type definitions

FCollaboration.loadPdfAsync

Load a Univer PDF from the server with a unit ID.

loadPdfAsync(unitId: string, context?: ILogContext): Promise<FPdf | null>

Parameters

• unitId — Required. ID of the Univer PDF that you would like to load.
• context — Optional. Optional context.

Returns

The FPdf or null if ID cannot be associated with a Univer PDF.

Examples

const collaboration = univerAPI.getCollaboration()const pdf = await collaboration.loadPdfAsync('your-unit-id')

Types: FPdf · Promise · ILogContext

Package: @univerjs-pro/collaboration-client · Type definitions

FCollaboration.loadSheetAsync

Load a Univer Sheet from the server with a unit ID.

loadSheetAsync(unitId: string, context?: ILogContext): Promise<FWorkbook | null>

Parameters

• unitId — Required. ID of the Univer Sheet that you would like to load.
• context — Optional. Optional context.

Returns

The FWorkbook or null if ID cannot be associated with a Univer Sheet.

Examples

const collaboration = univerAPI.getCollaboration()const workbook = await collaboration.loadSheetAsync('your-unit-id')

Types: FWorkbook · Promise · ILogContext

Package: @univerjs-pro/collaboration-client · Type definitions

FCollaboration.loadSlideAsync

Load a Univer Slide from the server with a unit ID.

loadSlideAsync(unitId: string, context?: ILogContext): Promise<FPresentation | null>

Parameters

• unitId — Required. ID of the Univer Slide that you would like to load.
• context — Optional. Optional context.

Returns

The FPresentation or null if ID cannot be associated with a Univer Slide.

Examples

const collaboration = univerAPI.getCollaboration()const presentation = await collaboration.loadSlideAsync('your-unit-id')

Types: FPresentation · Promise · ILogContext

Package: @univerjs-pro/collaboration-client · Type definitions

FCollaboration.subscribeCollaborators

Subscribe collaborators of a Univer file.

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

Parameters

• unitId — Required. ID of the Univer file.
• callback — Required. A callback function that will be called when the collaborators change.

Returns

A handler to dispose the subscription.

Examples

const collaboration = univerAPI.getCollaboration()collaboration.subscribeCollaborators('your-unit-id', (members) => {  console.log(members)})

Types: IDisposable · IMember

Package: @univerjs-pro/collaboration-client · Type definitions