Import & Export

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

Caution

The import and export 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

Import and export functionality allows users to import .xlsx files into Univer documents or export document content as .xlsx files through the Univer server, facilitating interaction with other office software or platforms.

Why does Univer implement import and export through backend services?

Importing and exporting implemented solely through the frontend cannot meet enterprise needs in terms of performance and results. Therefore, we provide backend services to implement import and export functionality. You can use open-source DOCX parsing libraries to parse files into data structures that conform to the IDocumentData interface, and then use the Facade API to import data into Univer.

After successfully importing through the import entry in the menu bar, a notification will pop up in the lower left corner of the page, displaying information about the successful import and providing a link to access the imported document. If the default import and export behavior does not meet your needs, please refer to Custom Import Documents to learn how to customize the import behavior.

Preset Mode

Installation

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

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

Usage

import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/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/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css'
import '@univerjs/preset-sheets-advanced/lib/index.css'

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

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

Preset and Configuration

The configuration options for UniverSheetsAdvancedPreset are as follows:

interface IUniverSheetsAdvancedPresetConfig {
  // This is the endpoint for the Univer server
  universerEndpoint?: string
  exchangeClientOptions?: {
    // The minimum number of rows in the imported worksheet
    minSheetRowCount?: number
    // The minimum number of columns in the imported worksheet
    minSheetColumnCount?: number
    /**
     * Export whether to enable server-side formula calculation. When enabled, each export will trigger server-side formula calculation, addressing the following issues:
     * 1. Formulas have no default values when opening files in office software like WPS
     * 2. Excel does not show formula results unless editing is enabled
     * 3. Array formulas with the @ prefix cannot expand calculation results
     * Note: The server configuration file needs to set `SSC_SERVER_ENABLED=true`.
     */
    enableServerSideComputing?: boolean
  }
}

Plugin Mode

Installation

npm install @univerjs-pro/exchange-client @univerjs-pro/sheets-exchange-client

Usage

import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client'
import ExchangeClientEnUS from '@univerjs-pro/exchange-client/locale/en-US'
import { UniverSheetsExchangeClientPlugin } from '@univerjs-pro/sheets-exchange-client'
import { LocaleType, merge, Univer } from '@univerjs/core'

import '@univerjs-pro/exchange-client/facade'

import '@univerjs-pro/exchange-client/lib/index.css'

const univer = new Univer({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: merge(
      {},
      ExchangeClientEnUS, 
    ),
  },
})

const UNIVER_SERVER_ENDPOINT = `http://localhost:8000`

univer.registerPlugin(UniverExchangeClientPlugin, { 
  uploadFileServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/stream/file/upload`, 
  importServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/{type}/import`, 
  exportServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/{type}/export`, 
  getTaskServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/task/{taskID}`, 
  signUrlServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/file/{fileID}/sign-url`, 
  downloadEndpointUrl: `${UNIVER_SERVER_ENDPOINT}/`, 
}) 
univer.registerPlugin(UniverSheetsExchangeClientPlugin)

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

Plugins and Configuration

The configuration options for UniverExchangeClientPlugin are as follows:

interface IUniverExchangeClientConfig {
  // Configuration for the Univer server
  downloadEndpointUrl?: string
  uploadFileServerUrl?: string
  importServerUrl?: string
  exportServerUrl?: string
  getTaskServerUrl?: string
  signUrlServerUrl?: string
  // The maximum timeout time, in milliseconds
  maxTimeoutTime?: number
  options?: {
    // The minimum number of rows in the imported worksheet
    minSheetRowCount?: number
    // The minimum number of columns in the imported worksheet
    minSheetColumnCount?: number
    /**
     * Export whether to enable server-side formula calculation. When enabled, each export will trigger server-side formula calculation, addressing the following issues:
     * 1. Formulas have no default values when opening files in office software like WPS
     * 2. Excel does not show formula results unless editing is enabled
     * 3. Array formulas with the @ prefix cannot expand calculation results
     * Note: The server configuration file needs to set `SSC_SERVER_ENABLED=true`.
     */
    enableServerSideComputing?: boolean
  }
}

Facade API

Import

Import .xlsx file and get unitId

Caution

This method is only applicable for importing documents with collaborative editing enabled.

When collaborative editing is enabled, each document has a unique unitId. Using univerAPI.importXLSXToUnitIdAsync with the file parameter will return the unitId, which can be used to access the document. The file parameter can be a File object or a remote file URL.

// Accept a File object
const unitId = await univerAPI.importXLSXToUnitIdAsync(file)
// Or accept a remote file URL
// const unitId = await univerAPI.importXLSXToUnitIdAsync('https://example.com/filename.xlsx');

// Using with collaborative editing to automatically load data https://docs.univer.ai/en-US/guides/docs/features/collaboration#loading-collaborative-documents
const url = new URL(window.location.href)
url.searchParams.set('unit', unitId)
url.searchParams.set('type', '2') // The meaning of 2 is UniverInstanceType.UNIVER_SHEET

window.location.href = url.toString()

// Or call the API: univerAPI.loadServerUnit(unitId, 2) to load the document, refer to https://reference.univer.ai/en-US/classes/FUniver#loadserverunit for specific parameters

Import .xlsx file and get IWorkbookData

Using univerAPI.importXLSXToSnapshotAsync to import a .xlsx file will return the document data in the IWorkbookData format.

// Accept a File object
const snapshot = await univerAPI.importXLSXToSnapshotAsync(file)
// Or accept a remote file URL
// const snapshot = await univerAPI.importXLSXToSnapshotAsync('https://example.com/filename.xlsx');

// Create a new workbook via snapshot
univerAPI.createWorkbook(snapshot)

Export

Export .xlsx file using unitId

When collaborative editing is enabled, each document has a unique unitId. Using univerAPI.exportXLSXByUnitIdAsync with the unitId parameter will return a File object.

import { downloadFile } from '@univerjs-pro/exchange-client'

const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
const file = await univerAPI.exportXLSXByUnitIdAsync(unitId)

// Download the file using the downloadFile function from @univerjs-pro/exchange-client
downloadFile(file, 'univer', 'xlsx')

Export .xlsx file using IWorkbookData

Using univerAPI.exportXLSXBySnapshotAsync with the IWorkbookData will return a File object.

import { downloadFile } from '@univerjs-pro/exchange-client'

const fWorkbook = univerAPI.getActiveWorkbook()
const snapshot = fWorkbook.getSnapshot()
const file = await univerAPI.exportXLSXBySnapshotAsync(snapshot)

// Download the file using the downloadFile function from @univerjs-pro/exchange-client
downloadFile(file, 'univer', 'xlsx')

Converting Data on the Node.js Server

Univer server provides APIs for import and export, but the data format converted on the server does not match the Univer format. If you use our frontend import and export plugin @univerjs-pro/exchange-client, the data is already converted by default, and no additional processing is required. If you directly use the server's import and export API, you need to use the following methods to convert the data.

Transform Snapshot to IWorkbookData

After importing, the Snapshot JSON data needs to be transformed into the IWorkbookData format to be used in Univer.

import { transformSnapshotJsonToWorkbookData } from '@univerjs-pro/exchange-client'

// The json data contains snapshot and sheetBlocks
const workbookData = transformSnapshotJsonToWorkbookData(json)

Transform IWorkbookData to Snapshot JSON

Before exporting, the IWorkbookData format data needs to be transformed into Snapshot JSON data, which can then be sent to the server for export.

import { transformWorkbookDataToSnapshotJson } from '@univerjs-pro/exchange-client'

const snapshotJson = transformWorkbookDataToSnapshotJson(workbookData)

How is this guide?

Edit History

Previous Page

UI Overview

Next Page