参数分类

在 VeryReport 复杂报表设计器 中，参数用于在运行时传入不同取值，驱动数据过滤、动态标题与交互查询。本文说明参数的分类、各自定义方式，以及如何通过 $param / ${param} 读取参数值。

相关文档：参数报表 · 参数联动 · 参数报表快速入门 · 帮助文档首页

1. 概述

1.1 适用版本

1.2 应用场景

按「谁定义、何时生效」，VeryReport 将参数分为三类：

• 数据集参数：写在数据集 SQL / API 中，取数时由引擎替换；

• 模版参数：在模版上显式声明，可供参数面板绑定、表达式引用；

• 系统内置参数：无需在模版中定义，预览时由系统自动注入（如当前登录名）。

三类参数共用同一命名空间：同名时以运行时合并规则决定最终值（见下文优先级）。

1.3 功能简介

设计器路径一般为 /report/designer，菜单入口为 数据应用 → 报表。参数面板可绑定数据集参数与模版参数；系统内置参数可在 SQL 或表达式中直接引用参数名。

2. 数据集参数

2.1 定义方式

在模板数据集（数据库查询 / API 等）中，通过宏 ${参数名} 声明参数。引擎在执行前将最终参数值替换进语句，再交给数据源执行。

SELECT area, salesperson, amount
FROM sales
WHERE area = '${area}'

保存后点击 刷新参数，参数列表中出现 area，并可设置默认值。一条 SQL 可写多个 ${}。

2.2 特点

• 用到了才出现：不写 ${} 则不会产生该数据集参数；

• 库侧过滤：适合数据量大、条件稳定的场景；

• 同名合并：多个数据集中的同名参数视为同一参数。

3. 模版参数

3.1 定义方式

打开设计器菜单 设置 → 模版参数 → 新增参数，填写：

• 参数名：建议字母、数字、下划线（如 area、startDate）；

• 数据类型：字符串、日期、数字等；

• 默认值：常量（表达式能力视版本而定）。

3.2 特点

• 先声明再使用：适合统一默认值、跨多个数据集共用同一条件；

• 可被参数面板控件绑定，预览时由用户选择后点「查询」生效；

• 可在单元格表达式、标题中用 $参数名 引用（见第 5 节）。

3.3 与数据集参数的关系

推荐流程：

1. 数据集 SQL 写好 ${area} → 自动出现数据集参数 area；

2. 在模版参数中声明同名 area 并设默认值；

3. 参数面板拖下拉框 → 绑定参数 选择 area（分组下拉会标注「模版 + 数据集」）。

绑定参数下拉中，模版参数与数据集参数同名时只保留一条，避免重复绑定。

4. 系统内置参数

系统内置参数无需在模版或数据集中事先定义。预览 / 查询报表时，服务端会把当前会话相关值自动放入参数 Map，可直接在 SQL 的 ${} 或表达式的 $ 中引用。

4.1 内置参数一览

说明：产品中用于标识当前用户的内置参数名为 vr_loginName，而不是 username。若在 SQL 中写 ${username} 且未另行定义同名参数，将无法得到登录名。

4.2 使用示例

按当前登录人过滤明细（实际值字段以业务表为准）：

SELECT *
FROM orders
WHERE creator = '${vr_loginName}'

在单元格中展示当前登录名：

$vr_loginName

4.3 注意事项

• 内置参数不出现在「模版参数」列表中，也无需在参数面板绑定（除非业务上要用控件覆盖，一般不推荐覆盖登录名）；

• 未登录或匿名预览时，vr_loginName 可能为空，SQL 条件需考虑空值场景；

• 不要与业务参数使用易混淆的同名（如自行定义 vr_loginName），以免覆盖系统注入值。

5. 如何取参数的值

VeryReport 提供两套引用写法，场景不同：

5.1 表达式 / 单元格：$参数名

在单元格公式、动态标题、部分过滤条件中，用 美元符号 + 参数名 读取当前参数值：

$area
$vr_loginName
$area + "区域销售"

• 取到的是参数的实际值（若下拉字典实际值为编码，则得到编码，不是显示文案）；

• 适合标题、说明文字、与表达式函数组合。

扩展与汇总场景请正确设置左主格 / 上主格（主子格关系），避免参数过滤后合计错位。

5.2 数据集 SQL / API：${参数名}

在数据集定义中，用美元花括号占位，执行前由引擎替换：

SELECT * FROM sales WHERE area = '${area}' AND creator = '${vr_loginName}'

• 替换结果再发给数据库，因此属于「库侧过滤」；

• 可与模版参数、系统内置参数、URL 传参合并后的最终值一起参与替换。

5.3 两种写法对照

6. 参数取值优先级

同一参数名存在多处来源时，运行时最终值大致遵循（高 → 低）：

系统内置参数在预览请求中自动写入参数 Map；若 URL 或面板显式传入同名键，可能覆盖内置值，请谨慎使用同名。

7. 索引与进阶

8. 常见问题

Q：想用当前登录用户过滤，参数名写 username 没效果？
A：请使用系统内置参数 vr_loginName（登录名）。产品未提供名为 username 的内置参数。

Q：$area 和 ${area} 可以混用吗？
A：可以指向同一参数。单元格/标题用 $area；数据集 SQL 用 ${area}。

Q：模版参数和数据集参数必须同名吗？
A：若希望面板绑定后同时驱动 SQL，应使用同一参数名。仅表达式使用时可只建模版参数。

Q：系统内置参数要不要在「模版参数」里再加一遍？
A：不需要。直接在 SQL 或表达式中引用即可。

9. 相关文档

• 参数报表

• 参数联动

• 参数报表快速入门

• 普通报表快速入门

• 帮助文档首页