参数报表

在 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 salesman WHERE area = '${area}'

4. 点击 刷新参数，在参数列表中看到 area，将默认值设为 华东。

5. 点击 预览 确认能取出华东数据，再点确定保存数据集。

如下图所示：

4.2 表格样式设计

1. 依次填写表头。

2. 依次拖入相应的字段到单元格。

3. 对表格进行样式美化。

如下图所示：

4.3 参数添加控件

1. 点击设计器顶部 Tab 参数面板，进入参数面板编辑。

2. 从控件栏拖入：下拉框、查询按钮（可选重置按钮）。

3. 将下拉框的控件名称设为 area（与数据集参数同名），即完成参数绑定。

4. 标签文案设为「区域：」。

5. 为下拉框配置数据字典（数据库表「VRDemo」的「salesman」字段，实际值与显示值均为area）。

注意：使用数据集参数时，下拉框的数据字典不要直接引用会随同一参数循环依赖的 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. 相关文档

• 参数报表快速入门

• 普通报表快速入门

• 行式报表

• 交叉报表

• 产品介绍：复杂报表

• 帮助文档首页