Collaboration

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.

This class should not be instantiated directly. Use factory methods on univerAPI instead.

Overview

@univerjs-pro/collaboration-client

APIs

Loading

loadActiveSheet

Signature

async loadActiveSheet(): Promise<FWorkbook | null>

Returns

• Promise<any> — The FWorkbook or null if the active Univer Sheet cannot be loaded.

loadActiveSheetAsync

Load the active Univer Sheet. It should be associated with the Uniscript Node.js Runtime.

Signature

async loadActiveSheetAsync(): Promise<FWorkbook | null>

Returns

• Promise<any> — The FWorkbook or null if the active Univer Sheet cannot be loaded.

Tags

• @throws — If the method is not overridden.

Examples

const collaboration = univerAPI.getCollaboration();
const workbook = await collaboration.loadActiveSheetAsync();

loadSheet

Signature

async loadSheet(unitId: string): Promise<FWorkbook | null>

Parameters

• unitId string — No description

Returns

• Promise<any> — The FWorkbook or null if the Univer Sheet cannot be loaded.

loadSheetAsync

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

Signature

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

Parameters

• unitId string — No description
• context ILogContext (optional) — No description

Returns

• Promise<any> — 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');

Members & Status

getCollaborationStatus

Get the synchronization status of a unit.

Signature

getCollaborationStatus(unitId?: string): CollaborationStatus

Parameters

• unitId string (optional) — No description

Returns

• CollaborationStatus — 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 unitId
const workbook = await collaboration.loadSheetAsync('unit-id');
await new Promise((resolve) => setTimeout(resolve, 1000)); // Wait for collaboration to initialize
const status = collaboration.getCollaborationStatus('unit-id');

// Browser environment - use focused unit (backward compatible)
const status = collaboration.getCollaborationStatus();

// Check if synchronized
if (status === univerAPI.Enum.CollaborationStatus.SYNCED) {
  console.log('All changes are synced!');
}

subscribeCollaborators

Subscribe collaborators of a Univer file.

Signature

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

Parameters

• unitId string — No description
• callback (members: IMember[]) => void — No description

Returns

• IDisposable — A handler to dispose the subscription.

Examples

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