Collaborative Editing

Facade API	Has Paid Plan	Univer Server	Univer on Node.js	Preset
-	✅	✅	-	UniverDocsCollaborationPreset

Univer provides collaborative editing functions, supporting multiple people to edit the same document at the same time.

This feature includes the following plugin packages:

Presets Installation


import { createUniver, defaultTheme, LocaleType, merge } from '@univerjs/presets';
import { UniverDocsCorePreset } from '@univerjs/presets/preset-docs-core';
import UniverPresetDocsCoreEnUS from '@univerjs/presets/preset-docs-core/locales/en-US';
import { UniverDocsAdvancedPreset } from '@univerjs/presets/preset-docs-advanced';
import UniverPresetDocsAdvancedEnUS from '@univerjs/presets/preset-docs-advanced/locales/en-US';
import { UniverDocsCollaborationPreset } from '@univerjs/presets/preset-docs-collaboration';
import UniverPresetDocsCollaborationEnUS from '@univerjs/presets/preset-docs-collaboration/locales/en-US';
import { UniverDocsDrawingPreset } from '@univerjs/presets/preset-docs-drawing'
import UniverPresetDocsDrawingEnUS from '@univerjs/presets/preset-docs-drawing/locales/en-US'
 
import '@univerjs/presets/lib/styles/preset-docs-core.css'
import '@univerjs/presets/lib/styles/preset-docs-drawing.css'
import '@univerjs/presets/lib/styles/preset-docs-advanced.css'
import '@univerjs/presets/lib/styles/preset-docs-collaboration.css'
 
const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: merge(
      {},
      UniverPresetDocsCoreEnUS,
      UniverPresetDocsDrawingEnUS,
      UniverPresetDocsAdvancedEnUS,
      UniverPresetDocsCollaborationEnUS,
    ),
  },
  theme: defaultTheme,
  collaboration: true,
  presets: [
    UniverDocsCorePreset(),
    UniverDocsDrawingPreset(),
    UniverDocsAdvancedPreset(),
    UniverDocsCollaborationPreset({
      universerEndpoint: 'http://localhost:3010',
    }),
  ],
});

Piecemeal Installation


npm install @univerjs-pro/collaboration @univerjs-pro/collaboration-client


pnpm add @univerjs-pro/collaboration @univerjs-pro/collaboration-client


yarn add @univerjs-pro/collaboration @univerjs-pro/collaboration-client


bun add @univerjs-pro/collaboration @univerjs-pro/collaboration-client


import { LocaleType, merge, Univer } from '@univerjs/core';
import { defaultTheme } from "@univerjs/design";
import { UniverCollaborationPlugin } from '@univerjs-pro/collaboration';
import { UniverCollaborationClientPlugin } from '@univerjs-pro/collaboration-client';
import { UniverCollaborationClientUIPlugin, BrowserCollaborationSocketService } from '@univerjs-pro/collaboration-client-ui';
import CollaborationClientEnUS from '@univerjs-pro/collaboration-client/locale/en-US';
 
import '@univerjs-pro/collaboration-client/facade';
import '@univerjs-pro/collaboration-client-ui/facade';
 
import '@univerjs-pro/collaboration-client/lib/index.css';
 
const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: merge(
      CollaborationClientEnUS
    ),
  },
});
 
// By setting the override option to [[IAuthzIoService, null]], you can instruct Univer not to register the built-in IAuthzIoService.
// By setting the override option to [[IUndoRedoService, null]], you can instruct Univer not to register the built-in IUndoRedoService.
// This way, Univer will use the services provided by the UniverCollaborationPlugin as the implementation for the authorization and undo-redo features.
const univer = new Univer({
  override: [
    [IAuthzIoService, null]
    [IUndoRedoService, null],
  ],
});
 
univer.registerPlugin(UniverCollaborationPlugin);
univer.registerPlugin(UniverCollaborationClientPlugin, {
  socketService: BrowserCollaborationSocketService,
  authzUrl: 'http://localhost:3010/universer-api/authz',
  snapshotServerUrl: 'http://localhost:3010/universer-api/snapshot',
  collabSubmitChangesetUrl: 'http://localhost:3010/universer-api/comb',
  collabWebSocketUrl: 'ws://localhost:3010/universer-api/comb/connect',
});
univer.registerPlugin(UniverCollaborationClientUIPlugin);

Collaborative Document Data

The collaborative editing plugin relies on the Univer server, and the data for collaborative documents is stored in the Univer server.

unitId

Each collaborative document in the Univer server has a unique unitId. The Univer collaboration client (collaborative editing plugin) uses the unitId to retrieve the corresponding collaborative document data from the Univer server for collaborative editing.

type

type is the type of the collaborative document, which determines the initial data structure of the collaborative document.

Creating Collaborative Documents

There are multiple ways to create collaborative documents in the Univer server:

You can create a blank document using the Create Unit API.
You can import an DOCX file into the Univer server using the importDOCXToUnitIdAsync method provided by the Import Plugin Facade API.

Loading Collaborative Documents with URL Parameters

@univerjs-pro/collaboration-client plugin provides a feature that automatically loads corresponding data according to the URL parameters unit and type, which can simplify the data loading logic in some cases.

If you want to use this feature, you need to modify the original data loading logic appropriately and add the unit and type parameters to the URL, as shown below:


import { UniverInstanceType } from '@univerjs/core';
 
# Original logic, only applicable to non-collaborative documents
- univer.createUnit(UniverInstanceType.UNIVER_DOC, {});
 
# Modified logic, applicable to collaborative documents
+ const url = new URL(window.location.href);
+ const unit = url.searchParams.get('unit');
 
+ if (unit) {
+   // If the URL contains the unit parameter, the data will be loaded automatically
+ } else {
+   // Or create a new workbook
+   fetch(`/universer-api/snapshot/${UniverInstanceType.UNIVER_DOC}/unit/-/create`, {
+     method: 'POST',
+     headers: {
+       'Content-Type': 'application/json',
+     },
+     body: JSON.stringify({
+       type: UniverInstanceType.UNIVER_DOC, // instance type
+       name: 'New Doc By Univer', // doc name
+       creator: 'user',  // creator name
+     }),
+   }).then((response) => {
+     if (!response.ok) {
+       throw new Error('create unit failed');
+     }
+
+     return response.json();
+   }).then((data) => {
+     if (!data.unitID) {
+       throw new Error('create unit failed');
+     }
+
+     url.searchParams.set('unit', data.unitID);
+     url.searchParams.set('type', String(UniverInstanceType.UNIVER_DOC));
+     window.location.href = url.toString();
+   }).catch((error) => {
+     console.error(error);
+   })
+ }