diff --git a/content/guides/pro/api.ja-JP.mdx b/content/guides/pro/api.ja-JP.mdx index ac9ff1ef..b1d115cf 100644 --- a/content/guides/pro/api.ja-JP.mdx +++ b/content/guides/pro/api.ja-JP.mdx @@ -31,11 +31,21 @@ title: API type: 'string', required: true, description: '作成者 ID', + }, { + name: 'idempotencyKey', + type: 'string', + required: false, + description: 'v0.20.0から導入されたオプションの冪等キー、文字数は<=64である必要があります', + }, { + name: 'metaData', + type: 'string', + required: false, + description: 'v0.20.0から導入されたオプションの元数据、ユーザー定義の情報で、作成されたunitに紐づけられ、その後の同期イベントやUSIP呼び出しで透過されます。全バイト数は<=1024である必要があります', }], example: `curl http://localhost:8000/universer-api/snapshot/{type}/unit/-/create \\ -X POST \\ -H 'Content-Type: application/json' \\ - --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID"}'`, + --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID","idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`, }} response={{ type: 'application/json', @@ -223,7 +233,7 @@ title: API ## ファイルとインポート/エクスポート -### ファイルアップロード +### ファイルアップロード [#upload-file] -### インポート +### インポート [#import-file] -### エクスポート +### エクスポート [#export-file] -### 変換結果の取得 +### 変換結果の取得 [#get-task-result] -### ファイル取得 +### ファイル取得 [#get-file] -### Import +### Import [#import-file] -### Export +### Export [#export-file] -### Get Task Result +### Get Task Result [#get-task-result] -### Get File +### Get File [#get-file] -### 导入 +### 导入 [#import-file] -### 导出 +### 导出 [#export-file] -### 获取转换结果 +### 获取转换结果 [#get-task-result] -### 获取文件 +### 获取文件 [#get-file] -### 匯入 +### 匯入 [#import-file] -### 匯出 +### 匯出 [#export-file] -### 取得轉換結果 +### 取得轉換結果 [#get-task-result] -### 取得檔案 +### 取得檔案 [#get-file] { + const formData = new FormData() + formData.append('file', file) + const res = await fetch( `${BASE_URL}/universer-api/stream/file/upload?size=${file.size}`, { @@ -51,7 +70,7 @@ async function uploadFile(file: File): Promise { // 認証ヘッダーを追加してください。例： // cookie: '_univer=XXXXXX', }, - body: file, + body: formData, }, ) @@ -145,6 +164,7 @@ async function importFile(params: ImportParams): Promise { ```typescript interface ExportParams { unitID: string + jsonID: string type: 1 | 2 // 1 = ドキュメント, 2 = スプレッドシート sscSwitch?: boolean } diff --git a/content/guides/pro/import-export.mdx b/content/guides/pro/import-export.mdx index 7a055cab..5d2881d6 100644 --- a/content/guides/pro/import-export.mdx +++ b/content/guides/pro/import-export.mdx @@ -12,37 +12,56 @@ Import/export is provided by the server and allows converting Office files to Un ## Import Flow -1. Upload the file to object storage and get `fileID` -2. Call the import API with `outputType` +1. [Upload the file](/guides/pro/api#upload-file) to object storage and get `fileID` +2. Call the [import](/guides/pro/api#import-file) API with `outputType` - `1`: import as a unit document - `2`: import as JSON -3. Poll task status: +3. Poll [task status](/guides/pro/api#get-task-result): - `pending`: keep polling - `done`: get `import.unitID` or `import.jsonID` - `failed`: read `error.message` -4. If importing JSON, follow [Server-side data conversion](/guides/docs/features/import-export#server-side-data-conversion) +4. Document loading + - If importing as a unit document, load directly with `import.unitID`, see [Collaboration](/guides/sheets/features/collaboration) section + - If importing as JSON, use `import.jsonID` to [Get File](/guides/pro/api#get-file) download URL, then process the JSON with [Server-side data conversion](/guides/sheets/features/import-export#server-side-data-conversion) before loading ![import](./import-export/import.png) ## Export Flow -1. Call export API with `unitID` to get `taskID` -2. Poll status: +The export flow for unit collaborative documents: + +1. Call [export](/guides/pro/api#export-file) API with `unitID` to get `taskID` +2. Poll [task status](/guides/pro/api#get-task-result): - `pending`: keep polling - `done`: get `export.fileID` - `failed`: read `error.message` -3. Use `export.fileID` to get a download URL +3. Use `export.fileID` to [Get File](/guides/pro/api#get-file) download URL ![export](./import-export/export.png) +The export flow for non-collaborative documents: + +1. [Upload](/guides/pro/api#upload-file) the file generated from frontend snapshot JSON to object storage and get `fileID` +2. Call [export](/guides/pro/api#export-file) API with `jsonID` to get `taskID`; `jsonID` is the `fileID` from the previous step +3. Poll [task status](/guides/pro/api#get-task-result): + - `pending`: keep polling + - `done`: get `export.fileID` + - `failed`: read `error.message` +4. Use `export.fileID` to [Get File](/guides/pro/api#get-file) download URL + ## Implementation Example +The API calls for import/export are already integrated in the frontend, see [Facade API](/guides/sheets/features/import-export#facade-api) for details. + The snippets below demonstrate a complete TypeScript workflow using `fetch`. Replace `BASE_URL` with your Univer server endpoint and include the required auth header (for example `cookie` or `Authorization`) in every request. ### 1. Upload a file ```typescript async function uploadFile(file: File): Promise { + const formData = new FormData() + formData.append('file', file) + const res = await fetch( `${BASE_URL}/universer-api/stream/file/upload?size=${file.size}`, { @@ -51,7 +70,7 @@ async function uploadFile(file: File): Promise { // Add your auth header here, e.g. // cookie: '_univer=XXXXXX', }, - body: file, + body: formData, }, ) @@ -145,6 +164,7 @@ async function importFile(params: ImportParams): Promise { ```typescript interface ExportParams { unitID: string + jsonID: string type: 1 | 2 // 1 = doc, 2 = sheet sscSwitch?: boolean } diff --git a/content/guides/pro/import-export.zh-CN.mdx b/content/guides/pro/import-export.zh-CN.mdx index 65ca81dd..5d6581a6 100644 --- a/content/guides/pro/import-export.zh-CN.mdx +++ b/content/guides/pro/import-export.zh-CN.mdx @@ -12,37 +12,56 @@ title: 导入导出服务 ## 导入流程 -1. 上传文件到对象存储，获取 `fileID` -2. 调用导入接口，设置 `outputType` +1. [上传文件](/guides/pro/api#upload-file)到对象存储，获取 `fileID` +2. 调用[导入](/guides/pro/api#import-file)接口，设置 `outputType` - `1`：导入为 unit 文档 - `2`：导入为 JSON -3. 轮询任务状态： +3. 轮询[任务状态](/guides/pro/api#get-task-result)： - `pending`：继续轮询 - `done`：获取 `import.unitID` 或 `import.jsonID` - `failed`：查看 `error.message` -4. 若导入为 JSON，需按[服务端数据转化](/guides/docs/features/import-export#服务端数据转化)处理后再加载 +4. 文档加载 + - 若导入为 unit 文档，直接使用 `import.unitID` 加载，使用见[协同编辑](/guides/sheets/features/collaboration)章节 + - 若导入为 JSON，使用 `import.jsonID` [获取文件](/guides/pro/api#get-file)下载链接，拿到 JSON 后按[服务端数据转换](/guides/sheets/features/import-export#server-side-data-conversion)处理后再加载 ![import](./import-export/import.png) ## 导出流程 -1. 通过 `unitID` 调用导出接口，获取 `taskID` -2. 轮询任务状态： +unit 协同文档导出方式： + +1. 通过 `unitID` 调用[导出](/guides/pro/api#export-file)接口，获取 `taskID` +2. 轮询[任务状态](/guides/pro/api#get-task-result)： - `pending`：继续轮询 - `done`：获取 `export.fileID` - `failed`：查看 `error.message` -3. 使用 `export.fileID` 获取文件下载链接 +3. 使用 `export.fileID` [获取文件](/guides/pro/api#get-file)下载链接 ![export](./import-export/export.png) +非协同文档导出方式： + +1. [上传](/guides/pro/api#upload-file)前端 snapshot json 生成的文件到对象存储，获取 `fileID` +2. 通过 `jsonID` 调用[导出](/guides/pro/api#export-file)接口，获取 `taskID`；`jsonID` 为前一步上传文件的 `fileID` +3. 轮询[任务状态](/guides/pro/api#get-task-result)： + - `pending`：继续轮询 + - `done`：获取 `export.fileID` + - `failed`：查看 `error.message` +4. 使用 `export.fileID` [获取文件](/guides/pro/api#get-file)下载链接 + ## 实现示例 -以下代码展示了使用 `fetch` 的完整 TypeScript 实现。请将 `BASE_URL` 替换为你的 Univer 服务端点，并在每次请求中带上认证信息（例如 `cookie` 或 `Authorization`）。 +前端已经集成了导入导出的 API 调用，详见 [Facade API](/guides/sheets/features/import-export#facade-api)。 + +以下代码展示了使用 `fetch` 进行接口调用的完整 TypeScript 实现。请将 `BASE_URL` 替换为你的 Univer 服务端点，并在每次请求中带上认证信息（例如 `cookie` 或 `Authorization`）。 ### 1. 上传文件 ```typescript async function uploadFile(file: File): Promise { + const formData = new FormData() + formData.append('file', file) + const res = await fetch( `${BASE_URL}/universer-api/stream/file/upload?size=${file.size}`, { @@ -51,7 +70,7 @@ async function uploadFile(file: File): Promise { // 在此添加认证信息，例如 // cookie: '_univer=XXXXXX', }, - body: file, + body: formData, }, ) @@ -145,6 +164,7 @@ async function importFile(params: ImportParams): Promise { ```typescript interface ExportParams { unitID: string + jsonID: string type: 1 | 2 // 1 = 文档, 2 = 表格 sscSwitch?: boolean } diff --git a/content/guides/pro/import-export.zh-TW.mdx b/content/guides/pro/import-export.zh-TW.mdx index 25e3def2..139974c7 100644 --- a/content/guides/pro/import-export.zh-TW.mdx +++ b/content/guides/pro/import-export.zh-TW.mdx @@ -12,37 +12,56 @@ title: 匯入匯出服務 ## 匯入流程 -1. 上傳檔案到物件儲存，取得 `fileID` -2. 呼叫匯入 API，設定 `outputType` +1. [上傳檔案](/guides/pro/api#upload-file)到物件儲存，取得 `fileID` +2. 呼叫[匯入](/guides/pro/api#import-file) API，設定 `outputType` - `1`：匯入為 unit 文件 - `2`：匯入為 JSON -3. 輪詢任務狀態： +3. 輪詢[任務狀態](/guides/pro/api#get-task-result)： - `pending`：持續輪詢 - `done`：取得 `import.unitID` 或 `import.jsonID` - `failed`：查看 `error.message` -4. 若匯入為 JSON，需依[服務端資料轉換](/guides/docs/features/import-export#服務端資料轉換)處理後再載入 +4. 文件載入 + - 若匯入為 unit 文件，直接使用 `import.unitID` 載入，使用見[協同編輯](/guides/sheets/features/collaboration)章節 + - 若匯入為 JSON，使用 `import.jsonID` [取得檔案](/guides/pro/api#get-file)下載連結，拿到 JSON 後按[服務端資料轉換](/guides/sheets/features/import-export#server-side-data-conversion)處理後再載入 ![import](./import-export/import.png) ## 匯出流程 -1. 以 `unitID` 呼叫匯出 API，取得 `taskID` -2. 輪詢狀態： +unit 協同文件匯出方式： + +1. 以 `unitID` 呼叫[匯出](/guides/pro/api#export-file) API，取得 `taskID` +2. 輪詢[任務狀態](/guides/pro/api#get-task-result)： - `pending`：持續輪詢 - `done`：取得 `export.fileID` - `failed`：查看 `error.message` -3. 使用 `export.fileID` 取得下載連結 +3. 使用 `export.fileID` [取得檔案](/guides/pro/api#get-file)下載連結 ![export](./import-export/export.png) +非協同文件匯出方式： + +1. [上傳](/guides/pro/api#upload-file)前端 snapshot json 生成的檔案到物件儲存，取得 `fileID` +2. 以 `jsonID` 呼叫[匯出](/guides/pro/api#export-file) API，取得 `taskID`；`jsonID` 為前一步上傳檔案的 `fileID` +3. 輪詢[任務狀態](/guides/pro/api#get-task-result)： + - `pending`：持續輪詢 + - `done`：取得 `export.fileID` + - `failed`：查看 `error.message` +4. 使用 `export.fileID` [取得檔案](/guides/pro/api#get-file)下載連結 + ## 實作範例 +前端已經整合了匯入匯出的 API 呼叫，詳見 [Facade API](/guides/sheets/features/import-export#facade-api)。 + 以下程式碼展示使用 `fetch` 的完整 TypeScript 實作。請將 `BASE_URL` 替換為你的 Univer 伺服器端點，並在每次請求中帶上認證資訊（例如 `cookie` 或 `Authorization`）。 ### 1. 上傳檔案 ```typescript async function uploadFile(file: File): Promise { + const formData = new FormData() + formData.append('file', file) + const res = await fetch( `${BASE_URL}/universer-api/stream/file/upload?size=${file.size}`, { @@ -51,7 +70,7 @@ async function uploadFile(file: File): Promise { // 在此添加認證資訊，例如 // cookie: '_univer=XXXXXX', }, - body: file, + body: formData, }, ) @@ -145,6 +164,7 @@ async function importFile(params: ImportParams): Promise { ```typescript interface ExportParams { unitID: string + jsonID: string type: 1 | 2 // 1 = 文件, 2 = 試算表 sscSwitch?: boolean } diff --git a/content/guides/sheets/features/import-export.ja-JP.mdx b/content/guides/sheets/features/import-export.ja-JP.mdx index b8ad145c..1f0c0c58 100644 --- a/content/guides/sheets/features/import-export.ja-JP.mdx +++ b/content/guides/sheets/features/import-export.ja-JP.mdx @@ -96,6 +96,7 @@ const { univerAPI } = createUniver({ ``` Univer の商用ライセンスをお持ちの場合は、設定方法について [クライアントでのライセンス](/guides/pro/license#in-preset-mode) を参照してください。 + ### プリセットと設定 `UniverSheetsAdvancedPreset` の設定オプションは以下のとおりです。 @@ -221,7 +222,7 @@ interface IUniverExchangeClientConfig { } ``` -## Facade API +## Facade API [#facade-api] ### インポート @@ -249,16 +250,14 @@ const unitId = await univerAPI.importXLSXToUnitIdAsync(file) // またはリモート ファイル URL を受け取る // const unitId = await univerAPI.importXLSXToUnitIdAsync('https://example.com/filename.xlsx'); -// 共同編集と併用して自動的にデータを読み込む -// https://docs.univer.ai/en-US/guides/docs/features/collaboration#loading-collaborative-documents +// 共同編集と併用して自動的にデータを読み込む https://docs.univer.ai/en-US/guides/docs/features/collaboration#loading-collaborative-documents const url = new URL(window.location.href) url.searchParams.set('unit', unitId) url.searchParams.set('type', '2') // 2 は UniverInstanceType.UNIVER_SHEET を意味します window.location.href = url.toString() -// あるいは API: univerAPI.loadServerUnit(unitId, 2) を呼び出してドキュメントを読み込みます -// パラメーターの詳細は https://reference.univer.ai/en-US/classes/FUniver#loadserverunit を参照 +// あるいは API: univerAPI.loadServerUnit(unitId, 2) を呼び出してドキュメントを読み込みます，パラメーターの詳細は https://reference.univer.ai/en-US/classes/FUniver#loadserverunit を参照 ``` #### `.xlsx` ファイルをインポートして `IWorkbookData` を取得 @@ -319,7 +318,7 @@ const file = await univerAPI.exportXLSXBySnapshotAsync(snapshot) downloadFile(file, 'univer', 'xlsx') ``` -## Node.js サーバーでのデータ変換 +## Node.js サーバーでのデータ変換 [#server-side-data-conversion] Univer サーバーはインポート/エクスポートの API を提供しますが、サーバー側で変換されたデータ形式は Univer の形式とは一致しません。`@univerjs-pro/exchange-client` プラグインには、Node.js サーバーで利用できるデータ変換ユーティリティ関数が含まれています。 diff --git a/content/guides/sheets/features/import-export.mdx b/content/guides/sheets/features/import-export.mdx index 071c28e9..3664125b 100644 --- a/content/guides/sheets/features/import-export.mdx +++ b/content/guides/sheets/features/import-export.mdx @@ -222,7 +222,7 @@ interface IUniverExchangeClientConfig { } ``` -## Facade API +## Facade API [#facade-api] ### Importing @@ -318,7 +318,7 @@ const file = await univerAPI.exportXLSXBySnapshotAsync(snapshot) downloadFile(file, 'univer', 'xlsx') ``` -## Converting Data on the Node.js Server +## Converting Data on the Node.js Server [#server-side-data-conversion] Univer server provides APIs for import and export, but the data format converted on the server does not match the Univer format. The plugin `@univerjs-pro/exchange-client` includes utility functions for data transformation that can be used on a Node.js server. diff --git a/content/guides/sheets/features/import-export.zh-CN.mdx b/content/guides/sheets/features/import-export.zh-CN.mdx index 050ed934..291d9179 100644 --- a/content/guides/sheets/features/import-export.zh-CN.mdx +++ b/content/guides/sheets/features/import-export.zh-CN.mdx @@ -222,7 +222,7 @@ interface IUniverExchangeClientConfig { } ``` -## Facade API +## Facade API [#facade-api] ### 导入 @@ -318,7 +318,7 @@ const file = await univerAPI.exportXLSXBySnapshotAsync(snapshot) downloadFile(file, 'univer', 'xlsx') ``` -## 在 Node.js 服务端进行数据转换 +## 在 Node.js 服务端进行数据转换 [#server-side-data-conversion] Univer 服务端提供了导入导出的 API，但是服务端转化的数据和 Univer 格式不一致。插件 `@univerjs-pro/exchange-client` 内置了数据转换的工具函数，可以在 Node.js 服务端使用。 diff --git a/content/guides/sheets/features/import-export.zh-TW.mdx b/content/guides/sheets/features/import-export.zh-TW.mdx index 48d78239..e3286e92 100644 --- a/content/guides/sheets/features/import-export.zh-TW.mdx +++ b/content/guides/sheets/features/import-export.zh-TW.mdx @@ -222,7 +222,7 @@ interface IUniverExchangeClientConfig { } ``` -## Facade API +## Facade API [#facade-api] ### 匯入 @@ -318,7 +318,7 @@ const file = await univerAPI.exportXLSXBySnapshotAsync(snapshot) downloadFile(file, 'univer', 'xlsx') ``` -## 在 Node.js 服務端進行資料轉換 +## 在 Node.js 服務端進行資料轉換 [#server-side-data-conversion] Univer 服務端提供了匯入匯出的 API，但是服務端轉化的資料和 Univer 格式不一致。外掛 `@univerjs-pro/exchange-client` 內建了資料轉換的工具函式，可以在 Node.js 服務端使用。