File exchange integration

To open an Excel file in Univer, first convert it into data the editor can read. To export it, convert the edited data back into an Excel file. The server-side @univerjs-pro/exchange-node module handles conversion; the browser uploads files, opens documents, and downloads results.

Without collaborative editing

For example, a user uploads an Excel file, edits it on the page, and downloads the result as Excel.

1. The browser uploads the file. The server converts it into Univer document data and returns it.
2. The browser opens a spreadsheet with that data, ready for editing.
3. On export, the browser sends the edited data to the server, which generates an Excel file for download.

This does not require a collaboration service. A snapshot in the browser APIs is the document data used here. Snapshot import and export still need server-side conversion. To let users save their work and return later, your application also needs to store that data.

See Office file import and export for installing and using the conversion module. Start there as well if you only need to process files in Node.js.

With collaborative editing

For example, a user imports an Excel file, shares the document with colleagues, edits it together with them, and exports it later.

1. The server converts the uploaded file and saves the result as a collaborative document.
2. The server returns a document ID. The browser opens that ID, and other users join the same document using it.
3. On export, the server reads the document's latest content and generates an Excel file for download.

The unitId in the browser APIs is this document ID. Complete Collaboration integration first, then run the Exchange example. It includes browser, server, and conversion code to follow together.

Wait for current edits to synchronize before exporting, or the file may omit recent changes. See the server-side Office Exchange section of extension modules for reading and converting collaborative documents.

Connect the import and export buttons

Once server-side conversion works, connect it to your page:

• Using Univer menus or Facade APIs: follow the Exchange example to implement the required upload, conversion, task-query, and download interfaces, then configure the browser plugins. Request addresses and response formats must match.
• Using your own buttons: call your application APIs. Open the returned document data or document ID after import, and download the generated file after export.

See Sheets, Docs, Slides, Boards, Bases, and PDFs for browser configuration. The collaboration example demonstrates Sheets. For other products, check Office file import and export and the formats supported by your release.

Check the integration

Import a real application file, edit it, and export it. Open the result in an Office application and check the edits, formulas, images, and layout. With collaboration, also check that other users can open the same document and that its content survives a server restart.

Before deployment, replace the example's temporary files and in-memory tasks with application storage, limit upload sizes, and handle conversion failures and timeouts. Uploads, task queries, and downloads need access checks; see identity and authorization.

Export failures and license limits

An export can fail when submitted or while polling its task. An HTTP success alone does not mean the file is ready: inspect the protocol error.code and the task state. The exchange client preserves server export errors in IExchangeService.requestState$; a custom export UI can subscribe before starting the operation.

import { IExchangeService } from '@univerjs-pro/exchange-client'import { ErrorCode } from '@univerjs/protocol'const exchange = univer.__getInjector().get(IExchangeService)const subscription = exchange.requestState$.subscribe(({ error }) => {  if (!error || error.code === ErrorCode.OK) return  console.error(error.code, error.message)})

Compare named ErrorCode values from @univerjs/protocol, not translated message text. Retain the server’s message for diagnostics. Network failures, malformed task responses, and polling timeouts may instead report a generic failure; they do not prove a license rejection. Dispose the subscription with subscription.unsubscribe() when removing the editor.

For a custom backend or proxy, preserve the structured error response and report a failed task instead of leaving it pending. Increasing maxTimeoutTime only extends task polling; it does not increase export quota or change license coverage.

OLE attachments

Sheets, Docs, and Slides preserve imported OLE files separately from their preview images. Users can download available original files, rename an occurrence, and remove an attachment when permitted. Image and PDF attachments can be previewed. Office previews use Exchange JSON conversion and a temporary read-only editor; opening a preview does not create a persisted child document. Native Office applications and macros are not executed.

Add ole to the existing UniverDrawingPlugin registration before registering Exchange. The route below is an application route: resolve it to your document UI, using the optional second getLink argument (document type) if needed. Exchange supplies Office conversion and collaboration detection. UUID-backed attachments additionally require ole.attachmentIo with authorized upload(file, targetUnitId) and read(attachment, signal) callbacks. Office previews require the corresponding renderer or a custom previewOffice / createOfficePreview callback.

import { UniverDrawingPlugin } from '@univerjs/drawing'univer.registerPlugin(UniverDrawingPlugin, {  ole: {    getLink: (unitId) => `/documents/${encodeURIComponent(unitId)}`,  },})

Converting an Office attachment to an online document requires a collaborative host, edit permission, conversion support, and getLink. It creates an independent document and saves its identity on the attachment; later opens reuse it. Editing that document does not overwrite the original attachment bytes. Missing, external, or unsupported attachments retain their status rather than becoming editable Office objects.

Exports default to oleAttachmentSource: 'original'. Set 'online' to embed the current confirmed versions of converted online documents in that export only; it does not rewrite the stored originals. Wait for synchronization before exporting and authorize access to referenced documents on the backend. Pass the option as the second argument to Docs/Slides export APIs, or the fourth argument to Sheets export APIs; snapshot variants accept it in the same position. See the export API.

Exchange submits fileID and the owning sourceUnitID for persisted attachments. The import backend must validate their relationship and the caller’s access before converting by reference. Task polling can return progress.stage: reading, converting, creating, or done. For a custom conversion UI, see the attachment import and progress APIs.