ファイル交換の統合

Excel を Univer で開くには、エディターが読めるデータへ変換します。出力時は編集後のデータを Excel に戻します。サーバーの @univerjs-pro/exchange-node が変換し、ブラウザーはアップロード、表示、結果のダウンロードを行います。

共同編集を使わない場合

例えば Excel をアップロードし、ページ上で編集して Excel としてダウンロードします。

1. ブラウザーがファイルを送り、サーバーが Univer データに変換して返します。
2. ブラウザーがそのデータでスプレッドシートを開き、編集可能にします。
3. 出力時は編集後のデータをサーバーに送り、ダウンロード用 Excel を生成します。

この処理に共同編集サービスは不要です。ブラウザー API の「スナップショット」がここで扱うデータです。スナップショットの入出力にもサーバー変換は必要です。作業を保存して後で再開するには、アプリケーション側でそのデータも保存してください。

変換モジュールの導入と利用は Office ファイルの入出力を参照してください。Node.js でファイルを処理するだけの場合も同じページから始めます。

共同編集を使う場合

例えば Excel を取り込み、同僚と共有して共同編集し、後で出力します。

1. サーバーがファイルを変換し、結果を共同編集ドキュメントとして保存します。
2. サーバーが 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 アプリケーションで開き、変更、数式、画像、レイアウトを確認してください。共同編集では他のユーザーも同じドキュメントを開けることと、サーバー再起動後の保持も検証します。

配置前に容量制限、変換失敗、タイムアウトを処理してください。アップロード、タスク照会、ダウンロードにはアクセス検証が必要です。ID と認可を参照してください。

エクスポート失敗とライセンス制限

エクスポートは要求送信時にもタスクのポーリング中にも失敗します。HTTP 成功だけでは完了を判断できません。プロトコルの error.code とタスク状態を確認してください。Exchange クライアントは IExchangeService.requestState$ でサーバーのエクスポートエラーを伝えるため、独自 UI は操作前に購読できます。

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 より前に、既存の UniverDrawingPlugin 設定へ ole を追加してください。以下のルートはアプリ側のドキュメント画面を指します。必要なら getLink の第 2 引数（ドキュメント種別）で切り替えます。Exchange は Office 変換と共同編集状態の判定を提供します。UUID 参照の添付には、認可付きの upload(file, targetUnitId) と read(attachment, signal) を持つ ole.attachmentIo も必要です。Office プレビューには対応レンダラー、または独自の previewOffice / createOfficePreview が必要です。

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

Office 添付をオンラインドキュメントへ変換するには、共同編集中のホスト、編集権限、変換機能、getLink が必要です。独立したドキュメントを作成してその識別情報を添付に保存し、以後は再利用します。オンライン側を編集しても元の添付バイト列は上書きしません。欠落、外部参照、未対応の添付はその状態を保持します。

エクスポートの既定値は oleAttachmentSource: 'original' です。'online' は、変換済みオンラインドキュメントの現在の確定済みバージョンを今回の出力にだけ埋め込み、保存済みの原本は変更しません。同期完了を待ち、バックエンドで参照先へのアクセスを認可してください。Docs/Slides のエクスポート API は第 2 引数、Sheets は第 4 引数に渡します。snapshot 版も同じ位置です。エクスポート APIを参照してください。

永続化された添付ファイルでは、Exchange は fileID と所有元の sourceUnitID を送信します。バックエンドは参照による変換前に、その関連と呼び出し元のアクセス権を検証してください。ポーリングでは progress.stage（reading、converting、creating、done）を返せます。独自 UI にはインポートと進捗 APIを利用できます。