07 报表工具 | EdgeAgent Docs

版本: v1.0 修改日期: 2026-05-29

本手册介绍 viSCADA 报表工具从需求分析到报表发布的端到端流程,覆盖模板创建、数据源与数据集配置、模板上传与验证、业务系统集成。模板语法细节不在本手册展开,统一以《viSCADA 报表语法 2.0》为准。

1 整体流程

从收到需求到报表上线,标准流程如下:

图 1 viSCADA 报表制作整体流程

步骤对照表:

步骤	操作目标	对应章节
1.需求分析	判断是否可用报表工具实现,明确数据来源	3 需求分析与模板拆解
2.模板拆解	分析父子关系、扩展方向、数据集划分	3 需求分析与模板拆解
3.创建模板文件	创建 `.xpt.xlsx` 文件与工作表	4 模板创建
4.配置数据源	创建 JDBC 数据库连接	5 数据源创建
5.创建数据集	编写 SQL 或配置 HTTP 接口	6 数据集创建
6.模板上传	上传模板文件并选择报表类型	7 模板上传与验证
7.预览验证	预览生成结果并下载报表	7 模板上传与验证
8.业务系统集成	接入业务系统预览或列表	8 业务系统集成

图 2 需求到实现的决策路径

2 术语规范

本手册涉及的核心术语如下。代码标识保留原形式,业务概念首次出现括注。

术语	代码标识	定义	权威源
「模板文件」	`.xpt.xlsx`	viSCADA 报表工具识别的模板扩展名,区别于 V1 语法	本手册 4.1
「全局工作表」	`XptWorkbookModel`	整个工作簿的初始化工作表,引入跨表共享数据集	本手册 4.2
「Sheet 初始化表」	`XptSheetModel`	与业务工作表成对出现的初始化工作表	本手册 4.2
「数据集助手」	`datasetsHelper`	通过 `inject` 获取的数据集操作 Bean	本手册 4.3
「EL 表达式」	`${...}`	单元格内取值表达式,用于引用数据集字段	《报表语法 2.0》
「展开表达式」	`*=`	单元格扩展语法前缀,后接字段名与方向	《报表语法 2.0》
「运行时对象」	`xptRt`	单元格表达式执行环境全局变量,定位单元格/行/表/工作簿	本手册 4.6
「占位符」	—	数据集 SQL 中留空的参数,生成报表时按键值对注入	本手册 6.1

📌 V1 与 V2 语法差异较大,本手册仅覆盖 V2 语法。V1 语法相关项目(如雄安报表)请参考旧版文档。

3 需求分析与模板拆解

确定使用报表工具后,必须对样板进行结构化拆解,明确:

数据划分(哪些数据属于同一数据集)
父子关系(哪些单元格控制哪些单元格的扩展)
扩展方向(向下 / 向右)

3.1 示例 1:供暖季统计报表

图 3 供暖季统计报表样板

拆解要点:

数据分为两部分:供暖季汇总统计 + 每月明细
每月明细结构一致,需按月向下扩展

3.2 示例 2:用户分类表码报表

图 4 用户分类表码报表样板

拆解要点:

用户按类型分类
同一类型下用户数量不固定,用户列表需向下扩展
每个类型下,单站点挂载的表码数量不同
每组数据按日期向右扩展

4 模板创建

模板操作基于《viSCADA 报表语法 2.0》,本章仅说明工程实践,不重复语法细节。

4.1 创建模板文件

viSCADA 支持 .xlsx 类型文件作为模板。为与 V1 版本语法区分,模板文件名必须以 .xpt.xlsx 结尾,例如 heating-monthly-report.xpt.xlsx。

⚠️ 使用 V1 语法时,模板文件必须用 Microsoft Office 创建,不得使用 WPS。WPS 会导致共享字符串不自动扩展,引起数据缺失(雄安报表历史故障原因)。V2 语法不受此限制,但仍推荐 Office。

4.2 工作表结构

模板中存在两类特殊工作表,用于承载初始化逻辑:

工作表类型	命名规则	作用范围	典型用途
「全局工作表」	`XptWorkbookModel`	整个工作簿	引入日期、天气等公共数据
「Sheet 初始化表」	`${SheetName}-XptSheetModel`	对应的 `${SheetName}` 工作表	该 Sheet 专属的数据集与变量

图 5 XptWorkbookModel 全局工作表示例

图 6 XptSheetModel 成对配置示例

📌 报表含多个业务工作表时,每个业务表都需要一个配对的 XptSheetModel,命名严格遵循 ${SheetName}-XptSheetModel。

4.3 数据引入与二次处理

数据集操作通过 datasetsHelper Bean 完成。在初始化工作表中首先引入:


const datasetsHelper = inject("datasetsHelper");

数据集操作函数:

函数	签名	说明	示例
`loadDs`	`void loadDs(String datasetName, Integer datasetId)`	获取数据集并载入单元格语法上下文	`loadDs("数据集名称", 12345)`
`getDs`	`Object getDs(Integer datasetId)`	仅获取数据集对象,不载入上下文	`let dataset = getDs(12345)`
`getFieldList`	`Object getFieldList(Integer datasetId, String field)`	获取数据集指定字段形成的子数据集	`let fieldDataset = getFieldList(12345, "key1")`
`assign`	`void assign(String datasetName, varName)`	向单元格语法上下文载入已有数据集	`assign("数据集名称", dataset)`

📌 使用 loadDs 后无需再次 assign。两者互斥:loadDs = getDs + assign。

内置工具函数:

函数	签名	说明	示例
`now`	`Timestamp now()`	当前时间戳	`let now = now()` 返回 `2024-10-10 10:45:37.993`
`today`	`LocalDate today()`	今日日期	`let today = today()` 返回 `2024-10-10`
`currentDateTime`	`LocalDateTime currentDateTime()`	当前日期时间	`let dt = currentDateTime()` 返回 `2024-10-10T10:49:38.058062`
`parseFloat`	`float parseFloat(String value)`	字符串转浮点	`let f = parseFloat("123.45")`
`parseInt`	`int parseInt(String value)`	字符串转整数	`let i = parseInt("123")`
`parseBoolean`	`boolean parseBoolean(String value)`	字符串转布尔	`let b = parseBoolean("true")`

数据集二次处理函数:

现场需求往往需要在 SQL 之外对数据再加工,主要场景包括:

按关键词合并多个数据集(中节能报表案例)
平铺数据转父子结构(华星报表案例)
通过工具函数直接处理(忻州项目案例)

函数	签名	说明	示例
`concat`	`String concat(String... part)`	字符串拼接	`let s = concat("A","B","C")`
`merge`	`Object merge(List<String> primaryKeys, List<List<Map>> datasets)`	按关键词合并数据集	`let ds = merge(["pid","aligntime"], [dsA, dsB])`

📌 merge 的主键相同时,后者覆盖前者(上例中 B 覆盖 A)。

4.4 单元格数据绑定

单元格取值支持两种表达式:

表达式	语法	示例	说明
「EL 表达式」	`${数据集.字段}`	`${userList.user_name}`	详见《报表语法 2.0》2.3.2
「展开表达式」	`*=字段名`	`*=fieldName`	前缀 `*=` 后直接跟字段

4.5 单元格扩展

对于同类数据的横向/纵向排列(如多站点、多日期),支持两种配置方式。

方式一:展开表达式

语法	等价含义
`*=^ds1!fieldName`	向下扩展,扩展对象 `ds1`,扩展字段 `fieldName`
`*=>ds1!fieldName`	向右扩展,扩展对象 `ds1`,扩展字段 `fieldName`
`*=^fieldName@entity.children`	向下扩展,沿 `entity.children` 父子路径展开

方式二:单元格批注

属性	说明	示例
「expandType」	扩展方向。`r` = 沿行展开,`c` = 沿列展开	`expandType=r`
「expandExpr」	扩展对象(数据集或 list),出现在 `=` 左边	`expandExpr=shouzhansubstations`

4.6 单元格属性

模板中单元格非独立存在,需要通过关系定位取值。工具在表达式执行环境注入全局变量 xptRt。

xptRt 属性表:

属性	说明	典型用法
`xptRt.cell`	等价 `cell`,定位当前单元格	`expandExpr=cell.rp.ev`(当前格行父格的扩展值)
`xptRt.row`	等价 `row`,定位当前行	—
`xptRt.table`	等价 `table`,定位当前表格	—
`xptRt.sheet`	等价 `sheet`,定位当前 Excel 表单	—
`xptRt.workbook`	等价 `workbook`,定位当前工作簿	—
`xptRt.field(name)`	从最近邻环境对象取字段值	`xptRt.field("user_name")`

单元格批注可配置属性:

属性	说明	示例
`rowParent` / `rp`	行父格。未指定时向左查找	`rowParent=C3`
`colParent` / `cp`	列父格。未指定时向上查找	`colParent=C3`
`expandType`	扩展方向,`r` 沿行,`c` 沿列	`expandType=r`
`expandExpr`	扩展对象,出现在 `=` 左边	`expandExpr=shouzhansubstations`
`expandValue` / `ev`	获取指定单元格的扩展对象,出现在 `=` 右边	`valueExpr=cell.rp.ev.name`
`expandIndex` / `ei`	单元格在父格中的下标,从 `0` 开始	—
`ds`	当前数据源对象	—
`field`	未指定 `expandExpr` 时,按该字段对当前数据集汇总并分组展开	—
`keepExpandEmpty`	扩展集合为空时保留单元格(值置 null),而非删除	—
`expandInplaceCount`	模板预留的展开单元格数量,小于此值不新增行列	`expandInplaceCount=12`
`exportFormula`	生成的报表单元格中保留公式	`exportFormula=true`

4.7 单元格公式

基于 Excel 原生能力,支持大多数 Excel 函数。常用函数清单:

函数	说明	示例
`SUM`	求和。对扩展单元格求和时必须有边界	`SUM(A7)`
`PRODUCT`	乘积(限制同 `SUM`)	`PRODUCT(A1:A5)`
`COUNT`	统计数字单元格数量	`COUNT(A1:A10)`
`COUNTA`	统计非空单元格数量	`COUNTA(A1:A10)`
`AVERAGE`	取平均	`AVERAGE(A1:A10)`
`MIN` / `MAX`	最小 / 最大值	`MIN(A1:A10)`
`NVL(value, defaultValue)`	空值判断,`value` 为 null 时返回 `defaultValue`	`NVL(A1, 0)`
`PROPORTION`	占比(如每月用量占全年比例)	—
`RANK`	排名	—
`ACCSUM`	累积汇总	—
`CONCAT`	文本/单元格拼接	—
`IF`	条件判断,必须用 `${}` 引用	`${IF(A1>0, "正", "负")}`

📌 单元格格式 + 数据类型必须匹配:单元格格式需为数值型,且实际数据也必须是数值,否则报错。

📌 扩展单元格的四则运算必须用 ${} 引用。正确:${C1+0.5};错误:=C1+0.5(会破坏扩展逻辑)。

5 数据源创建

确定使用 JDBC 作为数据来源时,需要在平台配置数据源。详细操作见《viSCADA 数据源配置手册》。

图 7 数据源管理界面(列表 + 详情)

操作入口: 「后台管理」 → 「数据源」

核心操作:

操作	用途	注意事项
「+ 新增数据源」	创建新数据源	填写完整必填项后「保存」才生效
「搜索框」	按名称模糊搜索	支持部分匹配
「数据源名称」	点击查看详情	进入「数据源详情」区域
「🗑 删除」	删除数据源配置	确认后不可恢复
「测试连接」	校验连接配置	仅校验,不保存
「保存」	提交新增或修改	真正落库的动作

⚠️ 「测试连接」 成功 ≠ 已保存。必须再次点击 「保存」 才会持久化配置。

6 数据集创建

viSCADA 报表工具支持三种数据集类型,详细操作见《viSCADA 数据集配置手册》:

JDBC 类型(来自数据库)
HTTP 接口(来自外部 API)
CSV 文件(来自 CSV 格式文件)

现场最常用 JDBC 与 HTTP。通过 「+」 图标新增数据集。

图 8 数据集管理界面(列表 + 新增入口)

6.1 JDBC 类型

图 9 JDBC 类型数据集配置页

字段	是否必填	示例	说明
「数据集名称」	是	`所有换热站最新数据`	识别用名称,语义明确
「数据集类型」	是	`JDBC 类型`	默认已选
「数据源」	是	`heating-prod-db`	选择已配置数据源,或点击「⚙ 去创建」跳转数据源管理
「SQL 语句」	是	`SELECT * FROM station WHERE pid = :pid`	符合 SQL 语法
「占位符配置」	否	`pid` → `1001`	键值对,为 SQL 挖空,生成报表时注入

6.2 HTTP 接口

图 10 HTTP 接口数据集配置页(含接口配置弹窗)

字段	是否必填	示例	说明
「数据集名称」	是	`一片区换热站24小时平均供温`	识别用名称
「数据集类型」	是	`HTTP 接口`	切换到此项
「数据源」	是	—	点击「⚙ 接口配置」打开配置对话框
「占位符配置」	否	—	HTTP 接口场景无意义,无需填写

7 模板上传与验证

模板使用分为两种方式:

方式	场景	触发时机
「手动生成」	非定时、按需生成	用户点击预览时
「定时生成」	周期性报表	平台定时任务自动触发

上传入口: 「运行管理」 → 「报表模板」 → 「+ 新增模板」

图 11 报表模板列表与新增入口

⚠️ 上传的模板文件必须是已解密的 .xpt.xlsx 文件。

7.1 普通报表

触发条件:报表类型选择为 「普通报表」,点击 「确定」 保存。

图 12 普通报表配置界面(模板信息 + 数据集配置)

配置步骤:

步骤	操作	字段说明
1	鼠标悬停在模板上,点击「使用模板」	跳转到数据集配置页
2	选择「数据集」	任选一个非空数据集即可(为兼容 V1 语法强制要求,V2 模板内部已完成数据集引入)
3	填写「报表名称」	默认为模板名称,每次生成前可修改
4	配置「临时全局占位符」	键值对,匹配数据集所需参数
5	点击「预览报表」	预览成功即为配置正确
6	点击「下载报表」	导出生成的报表文件

验证通过的可观测标志:

「预览报表」 页面正常加载,数据填充完整
下载的文件可用 Excel 正常打开,扩展单元格按预期展开

7.2 定时报表

触发条件:报表类型选择为 「定时报表」,需额外配置定时参数。

图 13 定时报表参数配置界面

字段	是否必填	示例	说明
「是否可重新生成」	是	`是` / `否`	是否允许对历史报表重新生成
「命名规则」	是	`月度供暖报表-{yyyyMM}`	`{}` 内写入占位符
「数据集」	是	任选一个	同普通报表,兼容用
「定时频率」	是	`日` / `周` / `月` / `年` / `自定义`	见下表

定时频率执行时间:

频率	执行时间
日报表	每日凌晨 `00:00:15`
周报表	每周一凌晨 `00:00:15`
月报表	每月 `1` 号凌晨 `00:00:15`
年报表	每年 `1` 月 `1` 日凌晨 `00:00:15`
自定义	按 Cron 表达式配置

图 14 自定义频率 Cron 配置界面

验证通过的可观测标志:

到达配置时间点后,报表列表出现按命名规则生成的新报表
点击对应条目可预览与下载

8 业务系统集成

物联提供了业务系统集成文档,详见《viSCADA 报表业务集成手册》。当前支持两种形式:

集成形式	适用场景
「指定报表直接预览」	业务页面嵌入指定报表,用户打开页面即看报表
「历史报表列表」	业务页面嵌入报表列表,用户自选历史报表查看

9 常见问题

现象	原因	建议
模板上传后预览报错 “共享字符串未扩展”	使用了 WPS 创建 V1 语法模板	改用 Microsoft Office 重新创建模板文件
扩展单元格四则运算结果异常	直接写 `=C1+0.5` 破坏了扩展	改为 `${C1+0.5}` 形式
`SUM` 对扩展单元格求和为 `0`	扩展单元格未设置边界	明确指定求和范围或使用边界单元格
数据集参数不生效	未在「临时全局占位符」中配置	按数据集 SQL 中的占位符键值补全
定时报表未按时生成	Cron 表达式错误或命名规则冲突	核对 Cron 与占位符,确认「是否可重新生成」设置
「测试连接」成功但保存后不可用	点击测试连接后未再次点击「保存」	重新进入数据源详情,点击「保存」
模板文件扩展名被识别失败	文件名不是 `.xpt.xlsx` 结尾	重命名文件,确保以 `.xpt.xlsx` 结尾

💡 本手册为工程实践文档,不覆盖语法细节。遇到语法类问题请优先查阅《viSCADA 报表语法 2.0》;遇到数据源/数据集配置问题查阅对应的权威源文档。