参数报表

在 VeryReport 复杂报表设计器 中，参数用于在运行时传入不同取值，动态过滤数据，实现用户与报表的实时交互。本文介绍参数报表的概念、配置流程，并以数据集参数完成「按地区查询销量」示例。

相关文档：参数报表快速入门 · 普通报表快速入门 · 行式报表 · 帮助文档首页 · 产品介绍：复杂报表

1. 概述

1.1 适用版本

1.2 应用场景

参数指在报表运行时赋不同取值、从而得到不同查询结果的变量。VeryReport 引入参数后，可以按条件动态过滤数据，常见能力包括：

• 参数查询：按地区、日期、机构等条件取出不同范围的数据。例如查询某地区销售额，「地区」即可作为参数；传入不同地区，预览结果随之变化。
• 参数传递：超链传参、组件之间传参、URL 带参打开报表等，例如点击汇总行钻取到明细页并自动带入当前主键。

1.3 功能简介

按作用范围，参数通常可分为：

• 数据集参数：写在数据集 SQL 中，格式为 ${参数名}，在数据库查询时即完成过滤，数据量大时效率更高；
• 模版参数：报表级变量，可在表达式、单元格过滤、标题中引用（如 $地区）；
• 全局参数：跨模板复用的公共参数（视平台配置而定）。

同名参数存在时，一般遵循优先级：数据集参数 > 模版参数 > 全局参数；赋值方式上常见为：参数控件 > URL 传参 > 默认值。

设计器路径一般为 /report/designer，菜单入口为 数据应用 → 报表。可切换顶部 Tab 参数面板 布局控件；菜单 设置 → 模版参数 管理模版参数。

2. 实现参数查询步骤

实现参数查询的一般流程如下：

1. 定义参数：确定参数名称与默认值。数据集参数在 SQL 中用 ${para} 声明；模版参数在「模版参数」对话框中新增。
2. 参数添加控件：控件是参数交互载体。将控件名称与参数名保持一致即可完成绑定，预览时在控件中输入/选择的值会作为参数值参与查询。
3. 设置参数面板样式：调整控件位置、对齐、标签文案、查询/重置按钮布局与面板背景，保证查询区清晰易用。

3. 数据集参数使用说明

定义模板数据集（数据库查询）时，在 SQL 中加入 ${para} 宏即可声明数据集参数。${} 的求值结果会拼接到 SQL 上，再交给数据库执行；一条 SQL 中可写多个 ${}，对应多个参数。

${} 内可使用设计器支持的公式（如 if、len）以及字符串拼接；其中未作为函数名或常量出现的变量名，即为数据集参数。

SELECT * FROM 销量 WHERE 地区 = '${area}'

上例中的数据集参数为 area。写好 SQL 后，在数据集对话框点击 刷新参数，下方参数列表出现 area，即为定义成功；填写默认值后可再点 预览 验证取数。

注：尽量避免在 ${} 内直接嵌套裸的 { / }，以免解析失败。数据集参数不与某一个数据集「独占绑定」——多个数据集中的同名参数视为同一参数，以后一次赋值为准。

3.1 简单应用

按地区过滤：

SELECT * FROM 销量 WHERE 地区 = '${area}'

多选（结合 IN）时，注意与数据库语法对齐，例如：

SELECT * FROM 销量 WHERE 地区 IN ('${area}')

若目标 SQL 为 IN ('华东','华北')，则参数值应输入为 华东','华北，再与两侧引号拼接成合法语句。

3.2 带公式的应用

参数为空时查全部，非空时按地区过滤：

SELECT * FROM 订单 WHERE 1=1 ${if(len(area) == 0,"","and 货主地区 = '" + area + "'")}

• len(area) == 0：不拼接额外条件，结果等价于 WHERE 1=1；
• 否则拼接 and 货主地区 = '华东' 等形式。

3.3 定义多个参数

SELECT * FROM 订单 WHERE 1=1
${if(len(area) == 0,"","and 货主地区 = '" + area + "'")}
${if(len(province) == 0,"","and 货主省份 = '" + province + "'")}

上例定义了 area、province 两个数据集参数。

3.4 嵌套应用

SELECT * FROM 销量 WHERE 1=1 ${if(len(area)!=0," and 地区='"+area+"'",if(len(product)== 0,""," and 产品='"+product+"'"))}

优先按地区过滤；地区为空时再按产品过滤；两者皆空则返回全量（在 WHERE 1=1 下）。

4. 示例：按地区查询销量

以下以「销量」明细为例，使用数据集参数 area + 参数面板下拉框，实现按地区查询。

4.1 定义数据集参数

1. 进入 数据应用 → 报表，新建或打开普通报表模板。
2. 左侧 数据集 → 模板数据集 → ＋ 新建 → 数据库查询。
3. 命名为 ds1，选择数据源，SQL 填写：

SELECT * FROM 销量 WHERE 地区='${area}'

4. 点击 刷新参数，在参数列表中看到 area，将默认值设为 华东。
5. 点击 预览 确认能取出华东数据，再点确定保存数据集。

4.2 表格样式设计

1. 合并标题区（如 A1:C1），输入「地区销售查询」或使用动态标题 $area + "销售明细"（若同时配置了同名模版参数，也可引用模版参数）。
2. A2、B2、C2 分别作表头：地区、销售员、销量。
3. 将 ds1 字段拖入 A3、B3、C3；明细行一般保持纵向扩展。
4. 选中销量格 C3，右侧属性将聚合类型设为求和（按扩展分组汇总）。
5. 如存在分组或交叉场景，请正确设置左主格 / 上主格（主子格关系），保证扩展后单元格坐标唯一、汇总不错位。

提示：仅做「参数过滤后的清单」时，保证纵向扩展与对齐即可；若扩展后汇总错位，优先检查主子格是否指向正确的主格。

4.3 参数添加控件

1. 点击设计器顶部 Tab 参数面板，进入参数面板编辑。
2. 从控件栏拖入：标签、下拉框、查询按钮（可选重置按钮）。
3. 将下拉框的控件名称设为 area（与数据集参数同名），即完成参数绑定。
4. 标签文案设为「地区：」。
5. 为下拉框配置数据字典（数据库表「销量」的「地区」字段，实际值与显示值均为地区）。

注意：使用数据集参数时，下拉框的数据字典不要直接引用会随同一参数循环依赖的 ds1（否则可能造成循环引用）。应使用独立字典数据集，或未带该过滤参数的库表/全局数据集。

4.4 效果预览

4.4.1 PC 端

保存模板后点击 分页预览：

• 下拉选择「华东」，点查询 → 仅展示华东地区销售明细；
• 下拉选择「华北」，点查询 → 仅展示华北地区销售明细。

4.4.2 移动端

使用手机浏览器或企业门户打开同一预览链接。参数面板在小屏上通常置于报表上方；选择条件后点查询即可。列较多时可左右滑动查看。

5. 索引与进阶

6. 常见问题

Q：刷新参数后看不到参数？
A：检查 SQL 中是否使用 ${参数名} 写法；宏是否写在字符串引号场景中但仍可被解析；点击「刷新参数」后再看列表。

Q：预览查询无数据？
A：确认控件名与参数名一致；默认值是否与库中实际地区文案完全一致（含空格）；SQL 字符串引号是否配对。

Q：下拉框选项为空或报错？
A：数据字典不要循环引用带同一参数的 ds1；换用独立查询或源表字段。

Q：数据集参数和模版参数怎么选？
A：数据量大、条件稳定 → 优先数据集参数（库侧过滤）；需要在标题、单元格公式、多数据集共用同一条件且数据量可控 → 可用模版参数 + 过滤。

Q：汇总行数字不对？
A：检查扩展方向、聚合类型，以及主子格（左主格 / 上主格）是否指向正确主格。

7. 相关文档

• 参数报表快速入门
• 普通报表快速入门
• 行式报表
• 交叉报表
• 产品介绍：复杂报表
• 帮助文档首页