导入 & 导出

需要服务端部分功能依赖服务端支持

注意事项

导入导出功能需要 Univer 服务端支持，请确保你已经正确安装并配置了 Univer 服务端。具体请参考：升级到 Pro

导入和导出功能允许用户通过 Univer 服务端将 .docx 文件导入到 Univer 文档中，或将文档内容导出为 .docx 文件，便于与其他办公软件或平台进行交互。

为什么 Univer 通过后端服务实现导入导出？

仅通过前端实现的导入导出无论是从性能还是效果上来说都无法满足企业需求，因此我们提供了后端服务来实现导入导出功能。你可以通过一些开源的 DOCX 解析库将文件解析为符合 IDocumentData 接口的数据结构，然后通过 Facade API 将数据导入到 Univer 中。

通过菜单栏的导入入口成功导入后，页面左下角会弹出提示框，显示导入成功的信息，并提供访问导入文档的链接。若默认的导入导出行为无法满足你的需求，请查看《自定义导入文档》以了解如何自定义导入行为。

如何选择导入/导出方式

导入导出有两条路径，区别在于是否依赖协同服务：

方式	是否需要协同	适用场景	对应 API
通过 `unitId`	需要	已启用协同、需要多人共享/继续协作的文档	`importDOCXToUnitIdAsync` / `exportDOCXByUnitIdAsync`
通过快照（snapshot）	不需要	本地/单人/离线导入导出，或仅做格式转换	`importDOCXToSnapshotAsync` / `exportDOCXBySnapshotAsync`

如果你的项目已接入协同（服务端可持久化文档并通过 unitId 打开），优先使用 unitId 路径；如果你不需要协同能力或只想在本地处理数据，使用快照路径。

预设模式

安装

@univerjs/preset-docs-advanced 的 UniverDocsAdvancedPreset 预设在运行时依赖 UniverDocsDrawingPreset 预设，请先安装 @univerjs/preset-docs-drawing。

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

使用

import { UniverDocsAdvancedPreset } from '@univerjs/preset-docs-advanced'
import UniverPresetDocsAdvancedZhCN from '@univerjs/preset-docs-advanced/locales/zh-CN'
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'
import UniverPresetDocsCoreZhCN from '@univerjs/preset-docs-core/locales/zh-CN'
import { UniverDocsDrawingPreset } from '@univerjs/preset-docs-drawing'
import UniverPresetDocsDrawingZhCN from '@univerjs/preset-docs-drawing/locales/zh-CN'
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.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetDocsCoreZhCN,
      UniverPresetDocsDrawingZhCN, 
      UniverPresetDocsAdvancedZhCN, 
    ),
  },
  presets: [
    UniverDocsCorePreset(),
    UniverDocsDrawingPreset(), 
    UniverDocsAdvancedPreset({ 
      universerEndpoint: 'http://localhost:3010', 
    }), 
  ],
})

如果你拥有 Univer 的商业许可证，请参考在客户端使用许可证进行配置。

预设与配置

UniverSheetsAdvancedPreset 配置项：

interface IUniverSheetsAdvancedPresetConfig {
  // Univer Server 的端口地址
  universerEndpoint?: string
}

插件模式

安装

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

使用

import { UniverDocsExchangeClientPlugin } from '@univerjs-pro/docs-exchange-client'
import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client'
import ExchangeClientZhCN from '@univerjs-pro/exchange-client/locale/zh-CN'
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.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      ExchangeClientZhCN, 
    ),
  },
})

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)

如果你拥有 Univer 的商业许可证，请参考在客户端使用许可证进行配置。

插件与配置

UniverExchangeClientPlugin 配置项：

interface IUniverExchangeClientConfig {
  // Univer Server 的配置
  downloadEndpointUrl?: string
  uploadFileServerUrl?: string
  importServerUrl?: string
  exportServerUrl?: string
  getTaskServerUrl?: string
  signUrlServerUrl?: string
  // 最大超时时间，单位为毫秒
  maxTimeoutTime?: number
}

Facade API

导入

插件模式提示

仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。

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

导入 `.docx`

导入 `.docx` 文件并获取 `unitId`

注意事项

该方法依赖协同服务：导入后会在服务端创建文档并返回 unitId。如果未启用协同，请使用快照导入。

在启用协同编辑的时候，每个文档都有一个唯一的 unitId。使用 univerAPI.importDOCXToUnitIdAsync 传入 file 参数会返回 unitId，可以通过 unitId 来访问文档。 file 参数可以是一个 File 对象，也可以是远程文件的 URL。

// 接受 File 对象
const unitId = await univerAPI.importDOCXToUnitIdAsync(file)
// 或者接受远程文件的 URL
// const unitId = await univerAPI.importDOCXToUnitIdAsync('https://example.com/filename.docx');

// 配合协同编辑自动加载数据一同使用 https://docs.univer.ai/zh-CN/guides/docs/features/collaboration#loading-collaborative-documents
const url = new URL(window.location.href)
url.searchParams.set('unit', unitId)
url.searchParams.set('type', '1') // 1 的意思是 String(UniverInstanceType.UNIVER_DOC)
window.location.href = url.toString()

// 或者调用API: univerAPI.loadServerUnit(unitId, 1) 加载文档，具体参数参考 https://reference.univer.ai/zh-CN/classes/FUniver#loadserverunit

导入 `.docx` 文件并获取 `IDocumentData`

快照导入不依赖协同服务，适合本地/单人/离线场景。需要协同文档请使用 unitId 导入。

使用 univerAPI.importDOCXToSnapshotAsync 导入 .docx 文件，会返回 IDocumentData 格式的文档数据。

// 接受 File 对象
const snapshot = await univerAPI.importDOCXToSnapshotAsync(file)
// 或者接受远程文件的 URL
// const snapshot = await univerAPI.importDOCXToSnapshotAsync('https://example.com/filename.xlsx');

// 通过快照创建一个新的文档
univerAPI.createUniverDoc(snapshot)

导出 `.docx`

通过 `unitId` 导出 `.docx` 文件

注意事项

unitId 导出依赖协同服务。如果未启用协同，请使用快照导出。

在启用协同编辑的时候，每个文档都有一个唯一的 unitId。使用 univerAPI.exportDOCXByUnitIdAsync 传入 unitId 参数会返回 File 对象。

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

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

// 下载文件
downloadFile(file, 'univer', 'docx')

通过 `IDocumentData` 导出 `.docx` 文件

快照导出不依赖协同服务，适合仅在本地处理数据的场景。

使用 univerAPI.exportDOCXBySnapshotAsync 传入 IDocumentData 会返回 File 对象。

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

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

// 下载文件
downloadFile(file, 'univer', 'docx')

目录