导入导出集成

要在 Univer 中打开 Excel 文件，需要先把文件转换成编辑器能读取的文档数据；导出时，再把编辑后的数据转换成 Excel 文件。这个转换过程由服务端的 @univerjs-pro/exchange-node 模块完成，前端负责上传文件、打开文档和下载结果。

不需要多人编辑

例如，用户上传一份 Excel，在页面上修改后，再下载为 Excel 文件。

1. 前端上传文件，服务端将它转换成 Univer 文档数据并返回。
2. 前端用这些数据打开表格，用户在页面中编辑。
3. 导出时，前端把编辑后的数据交给服务端，服务端生成 Excel 文件供用户下载。

这种方式不需要协同服务。前端 API 中的“快照”就是这里的文档数据；快照导入导出仍需要服务端完成文件转换。如果还要提供“保存后下次继续编辑”，需要由你的应用保存这些数据。

转换模块的安装和用法见 Office 文件导入导出。如果只在 Node.js 中批量处理文件，也可以直接从这篇文档开始。

需要多人编辑同一份文档

例如，用户导入一份 Excel 后，将文档分享给同事，大家共同编辑，之后随时导出。

1. 服务端转换上传的文件，并将转换结果保存为一份协同文档。
2. 服务端返回这份文档的 ID。前端根据 ID 打开文档，其他用户也通过同一个 ID 加入编辑。
3. 导出时，服务端读取这份文档的最新内容，生成 Excel 文件供用户下载。

前端 API 中的 unitId 就是这个文档 ID。请先按协同集成接通协同编辑，再运行 Exchange 导入导出示例。示例同时提供前端、服务端和文件转换代码，可以对照它们完成接入。

导出前要等待当前编辑同步到服务端，否则刚刚修改的内容可能不会出现在文件中。读取和转换协同文档的具体做法见协同扩展模块中的“服务端 Office Exchange”。

接入页面上的导入、导出按钮

服务端转换完成后，还需要让页面上的按钮调用它。

• 使用 Univer 自带菜单或 Facade API： 按 Exchange 示例注册 File Endpoint 和 Exchange Endpoint，再配置前端插件。
• 使用自己的上传、下载按钮： 调用业务接口，导入完成后打开返回的文档数据或文档 ID，导出完成后下载文件。

各产品的前端配置见 Sheets、Docs、Slides、Boards、Bases 和 PDFs。上述协同示例演示 Sheets；其他产品支持哪些文件格式，请先查看 Office 文件导入导出并核对所用版本。

接入后检查

用一份实际业务文件走完“导入 → 修改 → 导出”，再用办公软件打开结果，确认修改、公式、图片和布局符合需要。协同场景还要确认其他用户能打开同一份文档，并且服务重启后内容仍然存在。

上线前，限制上传大小，并处理转换失败和超时。上传、任务查询和下载都需要检查用户权限，权限接入可参考身份与权限。

导出失败与许可证限制

导出可能在提交请求时失败，也可能在任务轮询时失败。HTTP 请求成功不代表文件已生成，还需检查协议中的 error.code 和任务状态。Exchange 客户端会通过 IExchangeService.requestState$ 保留服务端导出错误；自定义导出界面可在发起操作前订阅。

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)})

通过 @univerjs/protocol 中具名的 ErrorCode 判断错误，不要解析翻译后的提示文字。保留服务端消息用于诊断。网络失败、无效任务响应和轮询超时可能只报告通用错误，不能据此认定许可证被拒绝。移除编辑器时调用 subscription.unsubscribe() 释放订阅。

自定义后端或代理应保留结构化错误响应，并将失败任务标为失败，而不是一直返回 pending。增大 maxTimeoutTime 只延长任务轮询时间，不会增加导出额度或改变授权范围。

OLE 附件

Sheets、Docs 和 Slides 将导入的 OLE 原文件与预览图分别保留。用户可以下载可用的原文件，并在权限允许时重命名某个附件实例或删除附件。图片和 PDF 可预览；Office 预览通过 Exchange 转换为 JSON，并在临时只读编辑器中打开，不创建持久化子文档。不会运行原生 Office 应用或宏。

在注册 Exchange 之前，将 ole 加入已有的 UniverDrawingPlugin 配置。以下路由由应用实现，应指向文档界面；可根据 getLink 的第二个参数（文档类型）选择路由。Exchange 提供 Office 转换和协同状态检测。使用 UUID 引用的附件还需配置 ole.attachmentIo，提供带鉴权的 upload(file, targetUnitId) 和 read(attachment, signal) 回调。Office 预览需要对应渲染器，或自定义 previewOffice / createOfficePreview 回调。

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

将 Office 附件转换为在线文档，需要宿主已启用协同、具有编辑权限，并配置转换能力和 getLink。转换创建独立文档，将其标识保存到附件上，后续打开时复用该文档。编辑在线文档不会覆盖附件原始字节。缺失、外部引用或不支持的附件保留相应状态，不会变成可编辑的 Office 对象。

导出默认使用 oleAttachmentSource: 'original'。设为 'online' 时，仅在本次导出中嵌入已转换在线文档当前已确认的版本，不改写保存的原附件。导出前应等待同步完成，后端需校验被引用文档的访问权限。Docs/Slides 导出 API 将该选项作为第二个参数，Sheets 作为第四个参数；snapshot 版本使用相同参数位置。参见导出 API。

转换已持久化的附件时，Exchange 提交 fileID 和所属的 sourceUnitID。导入后端须验证两者关系及调用者权限，再按引用转换。任务轮询可返回 progress.stage：reading、converting、creating 或 done。自定义转换界面可参考附件导入与进度 API。