Merge pull request #4822 from VisActor/feat/excel-multiply-sheet-import

feat: vtable-sheet support excel multiple sheets

Author: fangsmile

common/changes/@visactor/vtable/feat-excel-multiply-sheet-import_2025-12-16-09-22.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat: support import multiply sheets from excel file\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

common/changes/@visactor/vtable/feat-multiply-sheets-export_2025-12-15-09-04.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat: excel export multiply sheets\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

docs/assets/api/en/SheetAPI.md

@@ -75,15 +75,16 @@ Save all data as a configuration
 Export the current sheet to a file
 
 ```
-  exportSheetToFile: (fileType: 'csv' | 'xlsx') => void
+  exportSheetToFile: (fileType: 'csv' | 'xlsx', allSheets: boolean = true) => void
 ```
 
 ### importFileToSheet(Function)
 
 Import a file to the current sheet
 
 ```
-  importFileToSheet: () => void
+  /** clearExisting Whether to clear existing sheets (default true means replace mode). Set false to append mode */
+  importFileToSheet: (options: { clearExisting?: boolean } = { clearExisting: true }) => void
 ```
 
 ### exportData(Function)

docs/assets/api/zh/SheetAPI.md

@@ -75,15 +75,16 @@ VTableSheet组件支持的方法如下：
 导出当前sheet到文件
 
 ```
-  exportSheetToFile: (fileType: 'csv' | 'xlsx') => void
+  exportSheetToFile: (fileType: 'csv' | 'xlsx', allSheets: boolean = true) => void
 ```
 
 ### importFileToSheet(Function)
 
 导入文件到当前sheet
 
 ```
-  importFileToSheet: () => void
+  /** clearExisting 是否清除现有的 sheet（默认 true 表示替换模式）.设置false表示追加模式 */
+  importFileToSheet: (options: { clearExisting?: boolean } = { clearExisting: true }) => void
 ```
 
 ### exportData(Function)

docs/assets/guide/en/plugin/table-export.md

@@ -170,4 +170,10 @@ By default, the exported file will not be automatically downloaded, and you need
 By default, the exported file name is `export`; if you need to customize the file name, you can set `fileName` to the file name
 
 ## Usage Example
-Please refer to [table export](../../demo/export/table-export)
+Please refer to [table export](../../demo/export/table-export)
+
+## vtable-sheet usage
+
+In VTableSheet, you can refer to [VTableSheet export](../sheet/import_export).
+
+Because the electronic spreadsheet needs to support exporting multiple sheets, so this plugin extends the interface ability to export all sheets, and specifically adds the exportMultipleVTablesToExcel method.

docs/assets/guide/en/sheet/import_export.md

@@ -1,10 +1,72 @@
 # Import and Export Capabilities
-The import and export functionality in VTable-Sheet relies on export plugins from VTable's plugin package @visactor/vtable-plugins.
+Import and export capabilities in VTable-Sheet rely on plugin packages from @visactor/vtable-plugins.
 
-Export plugin: @visactor/vtable-plugins/table-export-plugin, refer to the tutorial documentation: [Table Export](../plugin/table-export)
+Export plugin: @visactor/vtable-plugins/table-export-plugin, refer to the tutorial documentation: [table export](../plugin/table-export)
 
-Import plugin: @visactor/vtable-plugins/excel-import-plugin, refer to the tutorial documentation: [Table Import](../plugin/excel-import)
+Import plugin: @visactor/vtable-plugins/excel-import-plugin, refer to the tutorial documentation: [table import](../plugin/excel-import)
 
-Since VTable plugins only work on a single table instance, VTableSheet's current import and export capabilities are limited. It can only export data from the current sheet or import external data files into the current sheet. The export and import capabilities of VTableSheet will be expanded and improved in the future.
+If you want to modify the plugin configuration, you can configure the parameters of the import and export plugins through VTablePluginModules.
 
-If you want to modify the plugin configuration options, you can configure various parameters for the import and export plugins through VTablePluginModules.
+Import and export capabilities usually need to be used together with menu functionality, so you need to configure menu functionality, which can be referred to [menu functionality](./menu.md).
+
+## Export sheet
+Export the current sheet, you can configure menuKey as VTableSheet.TYPES.MenuKey.EXPORT_CURRENT_SHEET_CSV to export a csv file, or configure menuKey as VTableSheet.TYPES.MenuKey.EXPORT_CURRENT_SHEET_XLSX to export an excel file.
+
+Export excel file supports exporting all sheets, you can configure menuKey as VTableSheet.TYPES.MenuKey.EXPORT_ALL_SHEETS_XLSX to export an excel file.
+
+Example:
+
+```typescript
+    mainMenu: {
+      show: true,
+      items: [
+        ......
+        {
+          name: 'Export',
+          items: [
+            {
+              name: 'Export CSV',
+              menuKey: TYPES.MainMenuItemKey.EXPORT_CURRENT_SHEET_CSV,
+              description: 'Export current sheet data to csv'
+            },
+            {
+              name: 'Export XLSX',
+              menuKey: TYPES.MainMenuItemKey.EXPORT_CURRENT_SHEET_XLSX,
+              description: 'Export current sheet data to xlsx'
+            },
+            {
+              name: 'Export All Sheets',
+              menuKey: TYPES.MainMenuItemKey.EXPORT_ALL_SHEETS_XLSX,
+              description: 'Export all sheets to xlsx'
+            }
+          ],
+          description: 'Export current sheet data'
+        }
+      ]
+    }
+```
+
+It also supports calling the export function through APIs, which can be referred to [API](../../api/SheetAPI#Methods.exportSheetToFile).
+
+## Import sheet
+
+Import sheet, you can configure menuKey as VTableSheet.TYPES.MenuKey.IMPORT to import a csv file or excel file.
+
+Example:
+
+```typescript
+mainMenu: {
+  ......
+  items: [
+    {
+      name: 'Import',
+      menuKey: VTableSheet.TYPES.MenuKey.IMPORT,
+      description: 'Import data to current sheet'
+    }
+  ]
+}
+```
+
+It also supports calling the import function through APIs, which can be referred to [API](../../api/SheetAPI#Methods.importFileToSheet).
+
+Import supports excel files and csv files, and supports multi-sheet import for excel files.

docs/assets/guide/zh/plugin/table-export.md

@@ -169,4 +169,10 @@ const tableExportPlugin = new VTablePlugins.TableExportPlugin({
 默认情况下，导出文件名称为`export`；如果需要自定义文件名，可以设置`fileName`为文件名
 
 ## 用法示例
-可参考[表格导出](../../demo/export/table-export)
+可参考[表格导出](../../demo/export/table-export)
+
+## vtable-sheet中使用
+
+在VTableSheet中使用时，可以参考[VTableSheet导出](../sheet/import_export)。
+
+因为电子表格需要支持导出多个sheet，所以这个插件扩展导出所有sheet的接口能力，具体增加了exportMultipleVTablesToExcel方法。

docs/assets/guide/zh/sheet/import_export.md

@@ -1,10 +1,72 @@
 # 导入导出能力
-VTable-Sheet中导入导出依赖VTable的插件@visactor/vtable-plugins中的导出插件包来实现的。
+VTable-Sheet中导入导出依赖VTable的插件@visactor/vtable-plugins中的插件包来实现的。
 
 导出插件：@visactor/vtable-plugins/table-export-plugin ，参考教程文档：[表格导出](../plugin/table-export)
 
 导入插件：@visactor/vtable-plugins/excel-import-plugin, 参考教程文档：[表格导入](../plugin/excel-import)
 
-因为VTable的插件只作用于单个表格实例，所以VTableSheet目前的导入导出能力不强，只能将当前sheet的数据导出，或将外部数据文件导入到当前sheet。后续会扩展完善 VTableSheet 的导出和导入能力。
+如果想要修改插件的配置项，可以通过VTablePluginModules配置导入和导出插件的各个参数。
 
-如果想要修改插件的配置项，可以通过VTablePluginModules配置导入和导出插件的各个参数。
+导入导出能力一般要配合菜单功能一起使用，所以需要配置菜单功能，具体可以参考[菜单功能](./menu.md)。
+
+## 导出sheet
+导出当前sheet，可以在mainMenu配menuKey为VTableSheet.TYPES.MenuKey.EXPORT_CURRENT_SHEET_CSV来导出csv文件，或者配menuKey为VTableSheet.TYPES.MenuKey.EXPORT_CURRENT_SHEET_XLSX来导出excel文件。
+
+导出excel文件支持全部sheet导出，可以在mainMenu配menuKey为VTableSheet.TYPES.MenuKey.EXPORT_ALL_SHEETS_XLSX来导出excel文件。
+
+具体如：
+
+```typescript
+    mainMenu: {
+      show: true,
+      items: [
+        ......
+        {
+          name: '导出',
+          items: [
+            {
+              name: '导出csv',
+              menuKey: TYPES.MainMenuItemKey.EXPORT_CURRENT_SHEET_CSV,
+              description: '导出当前sheet数据到csv'
+            },
+            {
+              name: '导出xlsx',
+              menuKey: TYPES.MainMenuItemKey.EXPORT_CURRENT_SHEET_XLSX,
+              description: '导出当前sheet数据到xlsx'
+            },
+            {
+              name: '导出全部xlsx',
+              menuKey: TYPES.MainMenuItemKey.EXPORT_ALL_SHEETS_XLSX,
+              description: '导出所有sheet到xlsx'
+            }
+          ],
+          description: '导出当前sheet数据'
+        }
+      ]
+    }
+```
+
+也支持通过API调用导出功能，具体可以参考[API](../../api/SheetAPI#Methods.exportSheetToFile)。
+
+## 导入sheet
+
+导入sheet，可以在mainMenu配menuKey为VTableSheet.TYPES.MenuKey.IMPORT来导入csv文件或excel文件。
+
+具体如：
+
+```typescript
+mainMenu: {
+  ......
+  items: [
+    {
+      name: '导入',
+      menuKey: VTableSheet.TYPES.MenuKey.IMPORT,
+      description: '导入数据到当前sheet'
+    }
+  ]
+}
+```
+
+也支持通过API调用导入功能，具体可以参考[API](../../api/SheetAPI#Methods.importFileToSheet)。
+
+导入支持excel文件及csv文件，针对excel文件支持多sheet导入。