导航：LuckReport专栏

本文转载自 W3Cschool，原文链接：ureport2参数，版权归原平台所有，仅用于技术交流学习，禁止商用。

一、快速了解

项目简介

Luck-Report 是一款基于开源项目 UReport2 重构的 Java 高性能报表引擎，通过迭代单元格可以实现任意复杂的中国式报表。相较于 UReport2，Luck-Report 在技术架构上进行了全新升级，后端基于 SpringBoot 框架开发、前端采用 Vue 框架构建，技术选型贴合当下主流项目开发标准，可精准适配各类实际开发需求。

Luck-Report 提供了全新的基于网页的报表设计器，可以在 Chrome、Firefox、Edge 等各种主流浏览器运行（IE 浏览器除外）。使用 Luck-Report，打开浏览器即可完成各种复杂报表的设计制作。

Luck-Report 基于 Apache-2.0 开源协议开源

在线体验

• 体验地址：https://www.quzhe.top/luck-report/report/designer
• 源码地址：https://gitee.com/LuckyPools/luck-report
• 文档地址：https://www.quzhe.top/luck-report-blog/report

二、参数

参数指的是从报表外部传入报表的值，在 Luck-Report 中，三种类型的数据源都支持参数。直接连接数据库和内置数据库连接两种方式本质上一样，都是采用 SQL 方式从数据库中获取报表数据，所以对于这种类型的数据源参数传递只需要在 SQL 层面配置好相关参数即可；对于 Spring Bean 类型的数据源，就更为简单，只需要在对应在方法中获取对应的参数即可。我们首先来看看 SQL 取数据方式如何配置参数。

# SQL 数据集参数

对于 SQL 方式数据集参数传递方式，实际上就是给 SQL 添加查询条件，Luck-Report 中 SQL 参数传递采用的是命名参数的方式，这点与 Spring 中 NamedParameterJdbcTemplate 中采用命名参数的写法完全一致，所以如果您用过 Spring 中的 NamedParameterJdbcTemplate，那对命名参数一定很熟悉。

示例	说明
select * from sys_user where dept_id=:deptId	查询条件为 dept_id=:deptId，运行时引擎将采用名为 deptId 的参数值来填充 SQL
select * from sys_user where age > :age and dept_id in (:deptIds)	这个 SQL 中条件有两个，同样运行时引擎将尝试从外部参数中获取对应的值来填充 SQL

打开报表设计器，添加一个数据库连接方式数据源（直接连接数据库或内置数据库连接两种方式任选其一），添加一个 SQL 数据集，即可在弹出的窗口中定义 SQL 及相关参数。

在我们定义好含有命名参数的 SQL 后，接下来我们需要，在下面的参数配置区域进行配置 SQL 中用到的命名参数，当然如果你的 SQL 中没用到命名参数，那就不需要配置了。

参数各字段	说明
参数名	对应的命名参数名称，比如上面的 deptId 等
数据类型	当前参数在数据库中定义的数据类型。Luck-Report 中对应的数据类型有六种，分别是：String、Integer、Float、Boolean、Date 和 List。
默认值	当前外部没有为这个命名参数提供值的时候将采用这里提供的默认值来填充 SQL。
还需要注意的是，如果 SQL 中有命名参数，那一定义配置好参数的默认值，否则将无法为对应的 SQL 数据集生成对应的表字段。

|

关于参数的数据类型要求配置参数时定义好参数的数据类型， 是为了与数据库中定义的字段的数据类型匹配，在运行时外部传入的参数或在外部未传入参数而采用的默认值时，引擎会根据参数配置的数据类型将采用的数据值进行自动转换，以期与目标数据类型吻合。比如，参数为日期类型，外部可传入对应的日期类型的对象或普通字符串，如果是字符串，要求是 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss 格式，否则引擎将无法解析成日期对象，同样参数类型为 Date 的参数默认值也必须是 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss 格式的字符串。如果参数是 List 类型，那么外部可以传入一个 List 对象，或一个以逗号分隔的字符串，如果是一个以逗号分隔的字符串，那么引擎将以逗号为分隔符，将字符串转换成一个 ArrayList 对象，List 类型的参数多用在存在 in 条件的 SQL 中。

设计好带有参数的报表后，我们可以直接预览，默认预览显示的数据将是参数配置时参数默认值对应的数据，这时我们可以在预览报表的 URL 后面手工添加对应的参数名，以使报表呈现我们需要的数据。在 URL 后面添加参数是最简单、最直接的一种为带参数的报表提供外部参数的方法，报表一旦检测到外部有对应的参数传入，则不再取这个参数对应的默认值来填充 SQL。

SQL 数据集中的 SQL 支持表达式（表达式语法见 Luck-Report 表达式），参数格式为：${表达式}，也就是说，在 ${} 中输入的内容引擎认为是表达式，否则认为是标准 SQL。一旦在 ${} 中输入表达式，引擎会尝试进行语法检查。在 SQL 表达式中，我们可以对传入参数进行判断，这样就可以实现诸如当有参数传入 SQL 时，就取该参数过滤后的结果集，如果没有该参数传入时则取所有数据集需求，示例如下图所示：

表达式中返回 SQL 的注意事项我们在使用表达式返回 SQL 时，如果 SQL 中包含单引号包裹的字符串，那么需要加上 “” 来为单引号转义，否则会出现语法错误，如下面的表达式：

在上面的表达式中，return 后面的 SQL 中 dept_id=‘D11’ 就用来“\”为单引号转义。

# Spring Bean 数据源参数

关于 Spring Bean 数据源的详细配置，请参考 Luck-Report数据源.md，要将一个 Spring Bean 的方法定义某个数据集的数据来源，那么方法必须要有三个参数，依次是 String、String、Map，最后一个 Map 参数就是外部传入报表的参数集合，Luck-Report 会将外部传入的各种参数都收集到这个 Map 中，我们只需要根据需求从 Map 中获取即可。

在上面的代码中，我们尝试从 Map 中获取名为 salary 的参数，如果存在则采用这个参数。

# 查询表单设计

Luck-Report 设计器提供了一个查询表单设计器，通过这个设计器，可实现在网页中对 SQL 里配置的参数参数配置相应的查询表单。具体做法就是我们首先需要配置一个 SQL 数据集，并为其配置相应的查询参数，如下图所示：

接下来点击报表模版设计器工具栏上如下图所示按钮：

点击后就会弹出如下图所示的表单设计器窗口，在这个窗口就进行相应的查询表单设计即可：

设计器设计方式比较简单，那就是采用直接拖曳方式，将布局或输入组件拖到画布上即可。对于输入类型的组件来说，在将其拖曳到画布后，可通过点击将其选中，然后切换到 “属性” 页即可对这个输入组件的属性进行调整，需要注意的是，所有的输入组件都需要配置其绑定的查询参数，否则预览页将不能提交查询，如下图所示：

这里要选择的绑定查询参数，就是我们在 SQL 数据集里配置的参数查询，如果不配置，那么这里将无法选择。