报表生成功能说明

本文档详细说明 TestWpsReportAutomation 项目中报表生成模块的功能、交互方式及使用流程。 基于 ExcelDNA 1.9 + .NET 6 的 WPS/Excel 插件，集成了 MiniExcel、MiniWord 两种报表引擎。

目录

1. 项目概述
2. 报表引擎总览
3. Ribbon 交互界面
4. MiniExcel 报表生成（三种模式）
   • 4.1 列绑定模式
   • 4.2 原生占位符模式（无分组）
   • 4.3 原生占位符模式（按区域分组）
   • 4.4 MultiSheet 多工作表示例
5. MiniWord 报表生成
6. 图片处理机制
7. 模板绑定状态管理
8. 数据源规范
9. 生成流程总结

1. 项目概述

1.1 技术栈

1.2 核心能力

• 三种 Excel 报表生成模式：列绑定、原生占位符、原生占位符+分组
• Word 报表生成：主从数据模板，支持图片
• 图片智能处理：自动解析图片路径/单元格内嵌图片，保持布局
• 模板绑定状态持久化：通过 CustomXmlPart 保存绑定配置到工作簿
• 批量生成：一次配置，多份报表输出
• 多工作表生成：MultiSheet 特性

2. 报表引擎总览

2.1 引擎对比

2.2 核心模块关系

Ribbon.xml (UI 定义)
    
RibbonController.cs (按钮事件绑定)
    
WorkbookCommands.cs (命令调度)
    

  报表生成引擎                                      
   MiniExcelTemplateBindingOps.cs (列绑定)       
   MiniExcelNativeTemplateOps.cs (原生占位符)    
   MiniWordNativeTemplateOps.cs (Word 报表)      

  辅助模块                                          
   TemplateBindingPanel.cs (列绑定交互面板)       
   TemplateBindingWorkbookState.cs (状态管理)     
   TemplateBindingImageOps.cs (图片处理)          
   SpreadsheetOpenXmlImageLayoutOps.cs (布局)     
   ReportInteraction.cs (交互对话框)              
   ReportDemoData.cs (示例数据)                   
   ExcelWorkbookDataOps.cs (数据操作)             

3. Ribbon 交互界面

插件加载后在 Excel/WPS 功能区生成一个名为 “TestWpsReportAutomation” 的选项卡，包含四个分组：

3.1 当前测试 分组

3.2 MiniWord 分组

3.3 目录 分组

3.4 运行时 分组

4. MiniExcel 报表生成（三种模式）

4.1 列绑定模式

适用场景：模板版式固定，数据源列名与模板单元格需手动映射。

4.1.1 功能流程

1. 点击 [1. 生成模板示例]  生成包含"模板"工作表的工作簿
2. 在"模板"工作表上设计好最终版式
3. 点击 [2. 列绑定设置面板]
   a. 弹出 InputBox 提示选择数据源区域
   b. 切到数据源工作表（如"原始数据_订单明细"），点击任意单元格确定
   c. 弹出列绑定面板，显示所有数据源列名
   d. 点击 [启动] 按钮，逐列点击模板中对应单元格完成绑定
   e. 可标记某列为"明细列"或"图片列"
   f. 可设置"文件名引用列"，用于命名输出文件
4. 点击 [3. 基于当前模板批量生成]
   a. 弹出文件夹选择对话框，选择输出目录
   b. 插件自动导出当前工作表为模板文件
   c. 根据绑定配置逐行读取数据源，生成多份报表
   d. 自动打开前 3 份生成结果

4.1.2 关键技术细节

• 绑定持久化：绑定配置通过 TemplateBindingWorkbookStateStore 写入工作簿的 CustomXmlPart，保存后下次打开可恢复
• 预览值：绑定过程中，选择模板单元格后会自动写入数据源的示例值作为预览
• 图片处理：标记为“图片列”的列，生成时自动解析图片路径或单元格内嵌图片并插入
• 样式保留：生成前捕获模板单元格的样式（字体、颜色、边框、行高）和公式，生成后恢复
• 文件名生成：若指定了“文件名引用列”，则按该列的值命名输出文件；否则使用默认名

4.1.3 交互面板

列绑定面板 (SourceColumnBindingView) 提供以下交互：

4.1.4 代码入口

RibbonController.OnOpenMiniExcelTemplatePreview
     WorkbookCommands.OpenMiniExcelTemplatePreview
     ReportExcelInteractionOps.OpenMiniExcelTemplatePreview

RibbonController.OnOpenTemplateBindingPanel
     WorkbookCommands.OpenTemplateBindingPanel
     TemplateBindingSessionManager.OpenFromCurrentSelection

RibbonController.OnGenerateMiniExcelReportsFromActiveTemplate
     WorkbookCommands.GenerateMiniExcelReportsFromActiveTemplate
     MiniExcelTemplateBindingOps.ExportBatchFromBoundState

4.2 原生占位符模式（无分组）

适用场景：模板中直接使用 {{TableName.ColumnName}} 语法占位，数据源为 ListObject 智能表。

4.2.1 功能流程

1. 点击 [1. 生成模板示例]  生成包含"模板_MiniExcel_原生主从"工作表的工作簿
2. 切换到"模板_MiniExcel_原生主从"工作表
3. 在工作表中已预设好占位符，如：
   - 主表字段：{{主表.报表编号}}, {{主表.公司名称}}, {{主表.制表人}}
   - 明细集合：{{订单明细.订单号}}, {{订单明细.产品名称}}
   - 回款集合：{{回款表.回款日期}}, {{回款表.回款金额}}
4. 数据源位于"原始数据_主从表示例"工作表，包含"主表""订单明细""回款表"三个 ListObject
5. 点击 [4. 基于原生占位符批量生成]
   a. 选择输出目录
   b. 插件自动导出当前工作表为模板
   c. 解析占位符，从 ListObject 读取数据
   d. 按主表每条记录生成一份独立的报表
   e. 自动打开前 3 份结果

4.2.2 占位符语法

{{主表.报表编号}}           主表的"报表编号"列值
{{订单明细.订单号}}         订单明细表的"订单号"列值（集合展开）
{{回款表.回款金额}}         回款表的"回款金额"列值（集合展开）

注意：占位符中的表名必须与 ListObject 名称完全一致，列名必须与 ListObject 表头名称完全一致。

4.2.3 主从数据关联

• 主表、明细表、回款表的第一列都是关联字段（主键/外键）
• 主表第一列 = 主键（如“报表编号”）
• 明细表第一列 = 外键（关联到主表主键）
• 生成时按主表每条记录，过滤出关联的明细和回款数据

4.2.4 代码入口

RibbonController.OnGenerateMiniExcelNativeReportsFromActiveTemplate
     WorkbookCommands.GenerateMiniExcelNativeReportsFromActiveTemplate
     MiniExcelNativeTemplateOps.ExportBatchFromNativeTemplate(..., groupOrderDetailsByRegion: false)

4.3 原生占位符模式（按区域分组）

适用场景：在上一种模式的基础上，将订单明细按“区域”列分组，每个区域独立生成一份子报表嵌入主报表。

4.3.1 与无分组模式的区别

4.3.2 代码入口

RibbonController.OnGenerateMiniExcelNativeGroupedReportsFromActiveTemplate
     WorkbookCommands.GenerateMiniExcelNativeGroupedReportsFromActiveTemplate
     MiniExcelNativeTemplateOps.ExportBatchFromNativeTemplate(..., groupOrderDetailsByRegion: true)

4.4 MultiSheet 多工作表示例

功能：演示 MiniExcel 的 MiniExcel.SaveAs(outputPath, sheets) 多工作表输出能力。

生成结果：一个包含三个工作表的 .xlsx 文件：

• 销售明细：逐行销售数据
• 区域汇总：按区域汇总的统计结果
• 报表说明：报表元数据信息

代码入口：

RibbonController.OnGenerateMiniExcelMultiSheetFeatureWorkbook
     WorkbookCommands.GenerateMiniExcelMultiSheetFeatureWorkbook
     MiniExcelWorkbookOps.GenerateMultiSheetFeatureWorkbook

5. MiniWord 报表生成

5.1 功能概述

基于 MiniWord 引擎的 Word 报表生成，支持主从数据模板和图片插入。

5.2 完整流程

1. 点击 [创建并打开模板+数据源]
   a. 选择导出目录
   b. 自动创建 Word 模板文件（.docx），包含占位符
   c. 自动创建 Excel 数据源文件（.xlsx），包含"主表""明细表""回款表"三个 ListObject
   d. 同时复制配套图片资源到同一目录
   e. 模板和数据源在同一目录，便于管理

2. 在 Word 中编辑模板（可选）
   - 修改标题、格式、表格样式
   - 保持占位符语法不变

3. 切换到 Excel 数据源工作簿
   - 确保活动工作簿是数据源工作簿

4. 点击 [基于当前模板生成]
   a. 系统自动定位上次导出的模板文件（或手动选择新模板）
   b. 从数据源工作簿读取主表、明细表、回款表数据
   c. 按主表全部"报表编号"批量生成 Word 报表
   d. 自动打开前 3 份结果

5.3 Word 模板占位符

{{主表.报表编号}}
{{主表.公司名称}}
{{主表.制表人}}
{{主表.生成时间}}
{{主表.会议主题}}
{{主表.汇报摘要}}
{{主表.封面图片}}           图片占位符
{{明细表.开始时间}}         表格内集合占位符
{{明细表.结束时间}}
{{明细表.事项}}
{{明细表.地点}}
{{明细表.现场图片}}         图片占位符
{{回款表.回款日期}}         表格内集合占位符
{{回款表.回款金额}}
{{回款表.回款方式}}
{{回款表.备注}}
{{回款表.凭证图片}}         图片占位符

5.4 图片处理

• 图片列的值可以是文件路径或 MiniWordPicture 对象
• 模板创建时预设图片占位符，生成时自动替换为实际图片
• 图片尺寸由模板中预设的 MiniWordPicture 参数控制

5.5 代码入口

创建模板+数据源：
  RibbonController.OnExportMiniWordTemplateAndDataSource
     WorkbookCommands.ExportMiniWordTemplateAndDataSource
     WordReportOps.CreateAndOpenTemplate
     WordTemplateInteropOps.CreateAndOpenTemplate (COM 创建 Word 文档)
     ReportExcelInteractionOps.CreateAndOpenWordDataWorkbook

批量生成：
  RibbonController.OnGenerateMiniWordReportFromSelection
     WorkbookCommands.GenerateMiniWordReportFromSelection
     MiniWordNativeTemplateOps.GenerateReportsFromActiveWorkbook
     WordReportOps.ExportReport

6. 图片处理机制

6.1 图片来源

6.2 处理流程

1. 模板解析阶段：
   - 识别图片列（标记为 IsImageColumn 的列）
   - 从数据源单元格读取图片字节或路径
   - 从模板中读取图片布局信息（位置、尺寸）

2. 运行时模板准备：
   - 拷贝模板文件
   - 替换占位符为实际数据
   - 记录图片占位单元格的布局参数

3. 报表生成后：
   - 打开生成的 .xlsx 文件
   - 在对应位置插入图片
   - 调整行高、列宽以匹配预设布局
   - 设置图片的锚点位置（两单元格锚点）

6.3 相关模块

7. 模板绑定状态管理

7.1 状态存储

绑定配置通过以下两层机制管理：

内存缓存 (TemplateBindingWorkbookStateCache)：

• 键：工作簿 + 工作表名称
• 值：TemplateBindingWorkbookState 对象
• 生命周期：工作簿打开期间

持久化存储 (TemplateBindingWorkbookStateStore)：

• 存储位置：工作簿文件的 CustomXmlPart
• 存储时机：工作簿保存前、关闭前
• 恢复时机：工作簿打开时

7.2 状态内容

TemplateBindingWorkbookState:
  - WorkbookName             # 工作簿名称
  - WorkbookFullName         # 工作簿完整路径
  - TemplateWorksheetName    # 模板工作表名称
  - SourceReference          # 数据源区域引用
  - FileNameReferenceColumnName  # 文件名引用列名
  - Items:                   # 绑定项列表
    - SourceColumnName       # 数据源列名
    - SampleValue            # 示例值
    - TemplateCellAddress    # 绑定的模板单元格地址
    - IsDetailColumn         # 是否明细列
    - IsImageColumn          # 是否图片列

7.3 检查绑定状态

点击 Ribbon 中的 “检查绑定状态” 按钮，可查看：

• 当前内存缓存中的绑定配置
• 工作簿 CustomXmlPart 中的持久化绑定配置

8. 数据源规范

8.1 列绑定模式数据源

• 工作表名：原始数据_订单明细
• 格式：首行为表头，后续为数据行
• 包含列：报表编号、区域、订单号、产品名称、数量、单价、备注、图片路径等

8.2 原生占位符模式数据源

• 工作表名：原始数据_主从表示例
• 使用 ListObject 智能表组织数据
• 三个智能表横向排列：

8.3 Word 数据源

• 工作表名：Word原始数据
• 使用 ListObject 智能表：
  • 主表：报表编号、公司名称、制表人、生成时间、会议主题、汇报摘要、封面图片
  • 明细表：报表编号、开始时间、结束时间、事项、地点、现场图片
  • 回款表：报表编号、回款日期、回款金额、回款方式、备注、凭证图片

9. 生成流程总结

9.1 快速体验路径

1. 安装插件  打开 Excel/WPS
2. 点击 [1. 生成模板示例]
3. 在"模板_MiniExcel_原生主从"工作表查看示例
4. 切换到"原始数据_主从表示例"查看数据源
5. 点击 [4. 基于原生占位符批量生成]  选择输出目录
6. 查看生成的报表文件

9.2 列绑定完整路径

1. 点击 [1. 生成模板示例]
2. 在"模板"工作表设计版式
3. 点击 [2. 列绑定设置面板]
4. 选择数据源区域
5. 逐列绑定模板单元格
6. 点击 [3. 基于当前模板批量生成]
7. 选择输出目录，等待生成

9.3 Word 报表完整路径

1. 点击 [创建并打开模板+数据源]
2. 选择模板导出目录
3. 在 Word 中编辑模板（可选）
4. 切换到 Excel 数据源工作簿
5. 点击 [基于当前模板生成]
6. 确认模板文件，等待生成

9.4 输出目录

• 模板目录：{插件目录}/templates/
• 输出目录：{插件目录}/output/
• 临时目录：{插件目录}/temp/
• 状态目录：{插件目录}/state/
• 可通过 Ribbon 中的“打开模板目录”和“打开输出目录”快速访问