檔案交換整合

在 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，再設定瀏覽器外掛。
• 使用自訂按鈕： 呼叫應用程式 API。匯入後開啟回傳的文件資料或 ID，匯出後下載產生的檔案。

瀏覽器設定請參閱 Sheets、Docs、Slides、Boards、Bases與 PDFs。協同範例示範 Sheets；其他產品請查閱 Office 檔案匯入匯出，並確認使用版本支援的格式。

驗證整合

匯入實際業務檔案，編輯後匯出，再以 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。