Import & Export

Preset ModePlugin Mode

Preset Info

@univerjs/preset-docs-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 .docx files into Univer documents or export document content as .docx 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 UniverDocsAdvancedPreset preset from @univerjs/preset-docs-advanced depends on the UniverDocsDrawingPreset preset at runtime. Please install @univerjs/preset-docs-drawing first.

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

Usage

import { UniverDocsAdvancedPreset } from '@univerjs/preset-docs-advanced'
import UniverPresetDocsAdvancedEnUS from '@univerjs/preset-docs-advanced/locales/en-US'
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'
import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US'
import { UniverDocsDrawingPreset } from '@univerjs/preset-docs-drawing'
import UniverPresetDocsDrawingEnUS from '@univerjs/preset-docs-drawing/locales/en-US'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-docs-core/lib/index.css'
import '@univerjs/preset-docs-drawing/lib/index.css'
import '@univerjs/preset-docs-advanced/lib/index.css'

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetDocsCoreEnUS,
      UniverPresetDocsDrawingEnUS, 
      UniverPresetDocsAdvancedEnUS, 
    ),
  },
  presets: [
    UniverDocsCorePreset(),
    UniverDocsDrawingPreset(), 
    UniverDocsAdvancedPreset({ 
      universerEndpoint: 'http://localhost:3010', 
    }), 
  ],
})

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

Presets and Configuration

The configuration options for UniverDocsAdvancedPreset are as follows:

interface IUniverSheetsAdvancedPresetConfig {
  // This is the endpoint for the Univer server
  universerEndpoint?: string
}

Plugin Mode

Installation

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

Usage

import { UniverDocsExchangeClientPlugin } from '@univerjs-pro/docs-exchange-client'
import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client'
import ExchangeClientEnUS from '@univerjs-pro/exchange-client/locale/en-US'
import { LocaleType, mergeLocales, 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]: mergeLocales(
      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(UniverDocsExchangeClientPlugin)

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
  // Maximum timeout time in milliseconds
  maxTimeoutTime?: number
}

Facade API

Importing

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

Importing `.docx`

Import `.docx` 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.importDOCXToUnitIdAsync 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.importDOCXToUnitIdAsync(file)
// Or accept a remote file URL
// const unitId = await univerAPI.importDOCXToUnitIdAsync('https://example.com/filename.docx');

// 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', '1') // The meaning of 1 is UniverInstanceType.UNIVER_DOC
window.location.href = url.toString()

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

Import `.docx` file and get `IDocumentData`

Using univerAPI.importDOCXToSnapshotAsync to import a .docx file will return the document data in the IDocumentData format.

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

// Create a new document via snapshot
univerAPI.createUniverDoc(snapshot)

Exporting `.docx`

Export `.docx` file using `unitId`

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

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

const fDocument = univerAPI.getActiveDocument()
const unitId = fDocument.getId()
const file = await univerAPI.exportDOCXByUnitIdAsync(unitId)

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

Export `.docx` file using `IDocumentData`

Using univerAPI.exportDOCXBySnapshotAsync with IDocumentData will return a File object.

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

const fDocument = univerAPI.getActiveDocument()
const snapshot = fDocument.getSnapshot()
const file = await univerAPI.exportDOCXBySnapshotAsync(snapshot)

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

Table of Contents