导入 & 导出

预设模式插件模式

预设信息

@univerjs/preset-sheets-advanced

需要服务端支持

是

注意事项

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

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

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

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

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

预设模式

安装

@univerjs/preset-sheets-advanced 的 UniverSheetsAdvancedPreset 预设在运行时依赖 UniverSheetsDrawingPreset 预设，请先安装 @univerjs/preset-sheets-drawing。

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

使用

import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'
import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN'
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'
import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN'
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.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: merge(
      {},
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsDrawingZhCN, 
      UniverPresetSheetsAdvancedZhCN, 
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), 
    UniverSheetsAdvancedPreset({ 
      universerEndpoint: 'http://localhost:3010', 
    }), 
  ],
})

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

预设与配置

UniverSheetsAdvancedPreset 配置项：

interface IUniverSheetsAdvancedPresetConfig {
  // Univer Server 的端口地址
  universerEndpoint?: string
  exchangeClientOptions?: {
    // 导入后工作表的最小行数
    minSheetRowCount?: number
    // 导入后工作表的最小列数
    minSheetColumnCount?: number
    /**
     * 导出是否启用服务器端公式计算。启用后，每次导出都会触发服务端公式计算。解决如下问题：
     * 1. WPS 等办公软件打开文件时公式无默认值
     * 2. EXCEL 不启用编辑，无法看到公式计算结果
     * 3. 数组公式存在前缀@，导致无法展开计算结果
     * 注意，服务端配置文件需要配置 SSC_SERVER_ENABLED=true。
     */
    enableServerSideComputing?: boolean
  }
}

插件模式

安装

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

使用

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

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

插件与配置

UniverExchangeClientPlugin 配置项：

interface IUniverExchangeClientConfig {
  // Univer Server 的配置
  downloadEndpointUrl?: string
  uploadFileServerUrl?: string
  importServerUrl?: string
  exportServerUrl?: string
  getTaskServerUrl?: string
  signUrlServerUrl?: string
  // 最大超时时间，单位为毫秒
  maxTimeoutTime?: number
  options?: {
    // 导入后工作表的最小行数
    minSheetRowCount?: number
    // 导入后工作表的最小列数
    minSheetColumnCount?: number
    /**
     * 导出是否启用服务器端公式计算。启用后，每次导出都会触发服务端公式计算。解决如下问题：
     * 1. WPS 等办公软件打开文件时公式无默认值
     * 2. EXCEL 不启用编辑，无法看到公式计算结果
     * 3. 数组公式存在前缀@，导致无法展开计算结果
     * 注意，服务端配置文件需要配置 SSC_SERVER_ENABLED=true。
     */
    enableServerSideComputing?: boolean
  }
}

Facade API

导入

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

注意事项

此方法仅适用于启用了协同编辑的文档导入。

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

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

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

window.location.href = url.toString()

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

导入 `.xlsx` 文件并获取 `IWorkbookData`

使用 univerAPI.importXLSXToSnapshotAsync 导入 .xlsx 文件，会返回 IWorkbookData 格式的文档数据。

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

// 通过快照创建一个新的工作簿
univerAPI.createWorkbook(snapshot)

导出

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

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

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

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

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

通过 `IWorkbookData` 导出 `.xlsx` 文件

使用 univerAPI.exportXLSXBySnapshotAsync 传入 IWorkbookData 会返回 File 对象。

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

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

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

在 Node.js 服务端进行数据转换

Univer 服务端提供了导入导出的 API，但是服务端转化的数据和 Univer 格式不一致。如果使用我们的前端导入导出插件 @univerjs-pro/exchange-client'，数据已经默认转化，无需额外处理，如果你直接使用服务端导入导出 API，需要使用以下方法转化数据。

Snapshot 转化为 `IWorkbookData`

导入后得到的 Snapshot JSON 数据需要转化为 IWorkbookData 格式的数据才能在 Univer 中使用。

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

// json 数据包含 snapshot 和 sheetBlocks
const workbookData = transformSnapshotJsonToWorkbookData(json)

`IWorkbookData` 转化为 Snapshot

导出前需要将 IWorkbookData 格式的数据转化为 Snapshot JSON 数据，才能传给服务端进行导出。

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

const snapshotJson = transformWorkbookDataToSnapshotJson(workbookData)

目录