@univerjs-pro/exchange-client

Shared import and export client integration for Web SDK units.

import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client'univer.registerPlugin(UniverExchangeClientPlugin, config)

Entry Points

• Facade: @univerjs-pro/exchange-client/facade

Facade Utilities

Import the Facade entry and call exchange utilities through univerAPI:

import '@univerjs-pro/exchange-client/facade'if (file) univerAPI.downloadFile(file, 'univer', 'xlsx')

The shared Facade entry only adds downloadFile(file, filename, fileExt). Import, export, and snapshot conversion methods live in the corresponding host package Facade: bases-exchange-client, boards-exchange-client, docs-exchange-client, pdfs-exchange-client, sheets-exchange-client, or slides-exchange-client.

Plugin configuration

interface IUniverExchangeClientConfig {  /**   * The URL of the endpoint for downloading files.   * @default 'location.origin'   */  downloadEndpointUrl?: string  uploadFileServerUrl?: string  importServerUrl?: string  exportServerUrl?: string  getTaskServerUrl?: string  signUrlServerUrl?: string  maxTimeoutTime?: number}

Request options

export interface IExchangeImportOptions {  sheet?: IExchangeSheetImportOption  base?: IExchangeBaseImportOption  doc?: IExchangeDocImportOption}export interface IExchangeOleExportOption {  oleAttachmentSource?: 'original' | 'online'}export interface IExchangeExportOptions extends IExchangeOleExportOption {  sheet?: IExchangeSheetExportOption  base?: IExchangeBaseExportOption}

IImportRequest.options and IExportRequest.options now group format-specific settings by unit kind. Base requests use ExchangeBaseImportMode, ExchangeBaseExportMode, and ExchangeBaseFormulaPolicy. ExchangeFormat supports xlsx, csv, tsv, docx, pptx, and pdf.

oleAttachmentSource defaults to 'original'; 'online' embeds confirmed versions of converted online documents in that export without modifying stored originals. The plugin supplies OLE Office conversion and collaborative-host detection while preserving custom Drawing ole callbacks. Configure attachment IO and application links as described in OLE integration.

Attachment imports and task progress

IExchangeService.importAttachmentToUnitId(fileID, sourceUnitID, type, onProgress?) converts a persisted attachment into an independent Unit without downloading and uploading its bytes in the browser. Both IDs must be nonempty; the backend must authorize the attachment in its owning sourceUnitID. The result is a Unit ID or undefined if the import does not complete.

The optional callback receives IExchangeTaskProgress, whose stage is 'reading', 'converting', 'creating', or 'done'. The server can report it in IGetTaskResponse.progress; it is a stage, not a percentage. importFileToUnitId(file, type, options?, onProgress?) also accepts this callback.

import { UniverInstanceType } from '@univerjs/core'import { IExchangeService } from '@univerjs-pro/exchange-client'const exchange = univer.__getInjector().get(IExchangeService)const unitId = await exchange.importAttachmentToUnitId(  fileID,  sourceUnitID,  UniverInstanceType.UNIVER_DOC,  ({ stage }) => console.log(stage),)

Export error reporting

IExchangeService.requestState$ reports the original protocol error when export submission or a polled task returns a server failure. Inspect error.code from @univerjs/protocol to distinguish size, quota, version, and document-type license limits. Transport failures or invalid responses may instead produce a generic error. Increasing maxTimeoutTime changes polling duration, not license limits. See the subscription example and error handling.