Collaboration

GitHubEdit on GitHub
Preset Info
@univerjs/preset-sheets-collaboration
Server Required
Yes

Caution

The collaborative editing functionality requires support from the Univer server. Please ensure that you have correctly installed and configured the Univer server. For details, please refer to: Upgrading to Pro

The collaborative editing feature allows multiple users to edit the same document simultaneously with real-time synchronization of changes. It is ideal for team collaboration and multi-user editing scenarios.

Preset Mode

Installation

The UniveSheetsCollaborationPreset preset from @univerjs/preset-sheets-collaboration depends on the UniverSheetsDrawingPreset and UniverSheetsAdvancedPreset presets at runtime. Please install @univerjs/preset-sheets-drawing and @univerjs/preset-sheets-advanced first.

npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced @univerjs/preset-sheets-collaboration

Usage

import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US'
import { UniverSheetsCollaborationPreset } from '@univerjs/preset-sheets-collaboration'
import UniverPresetSheetsCollaborationEnUS from '@univerjs/preset-sheets-collaboration/locales/en-US'
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US'
import { createUniver, LocaleType, merge } from '@univerjs/presets'

import '@univerjs/presets/lib/styles/preset-sheets-core.css'
import '@univerjs/preset-sheets-drawing/lib/index.css'
import '@univerjs/preset-sheets-advanced/lib/index.css'
import '@univerjs/preset-sheets-collaboration/lib/index.css'

const { univerAPI } = createUniver({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: merge(
      {},
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS, 
      UniverPresetSheetsAdvancedEnUS, 
      UniverPresetSheetsCollaborationEnUS, 
    ),
  },
  collaboration: true, 
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset({ 
      collaboration: true, 
    }), 
    UniverSheetsAdvancedPreset({ 
      collaboration: true, 
    }), 
    UniverSheetsCollaborationPreset({ 
      universerEndpoint: 'http://localhost:3010', 
    }), 
  ],
})

If you have a commercial license for Univer, please refer to Using License in Client for configuration.

Plugin Mode

Installation

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

Usage

import { UniverCollaborationPlugin } from '@univerjs-pro/collaboration'
import { UniverCollaborationClientPlugin } from '@univerjs-pro/collaboration-client'
import { BrowserCollaborationSocketService, UniverCollaborationClientUIPlugin } from '@univerjs-pro/collaboration-client-ui'
import CollaborationClientEnUS from '@univerjs-pro/collaboration-client/locale/en-US'
import { LocaleType, merge, Univer } from '@univerjs/core'

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({
  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)

If you have a commercial license for Univer, please refer to Using License in Client for configuration.

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 Document API.
  • You can import a .xlsx file into the Univer server using the FUniver.importXLSXToUnitIdAsync method provided by the Import Plugin.

Loading Collaborative Documents via URL Parameters

The @univerjs-pro/collaboration-client plugin provides functionality to automatically load the corresponding data based on the URL parameters unit and type, which can simplify data loading logic in some scenarios.

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

import { UniverInstanceType } from '@univerjs/core'
// In preset mode, `UniverInstanceType` can be imported from `@univerjs/presets`
import { UniverInstanceType } from '@univerjs/presets'

// The original logic, applicable to non-collaborative documents
univer.createUnit(UniverInstanceType.UNIVER_SHEET, {}) 

// The 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 document
  fetch(`/universer-api/snapshot/${UniverInstanceType.UNIVER_SHEET}/unit/-/create`, { 
    method: 'POST', 
    headers: { 
      'Content-Type': 'application/json', 
    }, 
    body: JSON.stringify({ 
      type: UniverInstanceType.UNIVER_SHEET, // instance type
      name: 'New Sheet By Univer', // workbook 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_SHEET)) 
    window.location.href = url.toString() 
  }).catch((error) => { 
    console.error(error) 
  }) 
}

Facade API

Loading Collaborative Documents

If you do not want to use URL parameters to load collaborative documents, you can also load collaborative documents through the Facade API.

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

Further Reading

If you want to learn more about how collaborative editing works, you can read the following article:

Charts

Previous Page

Edit History

Next Page