finereport 动态参数

下面我将从概念、类型、核心组件、创建步骤、进阶应用和最佳实践六个方面，全面地为你解析 FineReport 的动态参数。

什么是动态参数？

动态参数，顾名思义，其值不是在报表设计时写死的，而是在报表运行时由用户（或系统）动态输入或选择，并传递给报表，从而控制报表的数据查询、过滤、显示等行为。

它就像一个“遥控器”，用户可以通过这个遥控器来改变报表的显示内容。

核心价值：

• 交互性： 让报表从静态展示变为动态探索。
• 灵活性： 无需修改报表模板,即可适应不同的查询需求。
• 用户体验： 用户可以快速、精准地获取自己关心的数据。

动态参数的类型

FineReport 提供了多种类型的参数控件,以满足不同的交互场景。

核心组件：参数面板与数据集

动态参数的威力主要体现在参数面板和数据集的联动上。

1. 参数面板

   • 这是用户交互的界面元素，你拖拽一个“参数面板”到报表的参数面板区域,然后为其配置一个参数。
   • 你创建一个名为 province 的参数，然后给它绑定一个“参数面板”控件。

2. 数据集

   • 这是报表的数据来源，通常是 SQL 查询。
   • 关键在于，SQL 语句中需要使用参数占位符来接收参数面板传递过来的值。

联动原理： 用户在前端参数面板中选择了一个值（江苏省”），这个值会传递给报表模板中的 province 参数，数据集在执行 SQL 查询时，会用“江苏省”替换掉 SQL 语句中的 ${province} 占位符,最终查询出江苏省的数据。

创建动态参数的详细步骤（以最常见的参数面板为例）

假设我们要做一个销售报表,用户可以选择不同的省份来查看该省的销售情况。

步骤 1：创建数据集并使用参数

1. 在 FineReport 设计器中,打开你的报表模板。

2. 点击菜单栏的 数据集 -> 数据集,打开数据集管理窗口。

3. 新建一个数据集，选择数据库，然后编写 SQL 语句。

   • 关键： 在 SQL 的 WHERE 条件中使用 ${参数名} 的形式。

   SELECT
       city,
       product_name,
       sales_amount
   FROM
       sales_data
   WHERE
       1=1
       -- 使用 ${province} 作为参数占位符
       AND province = ${province}

   注意：

   • 如果参数可能为空（即用户不选择任何值），最好使用 AND province = ${province} OR ${province} IS NULL 这样的写法,避免查询出错。
   • 参数名 ${province} 必须与后面在参数面板中定义的参数名完全一致。

步骤 2：设计报表布局

1. 将数据集中的字段（city, product_name, sales_amount）拖拽到报表的单元格中,形成一个基本的表格。

步骤 3：添加并配置参数控件

1. 点击菜单栏的 模板 -> 模板参数,打开模板参数窗口。

2. 点击 新增,创建一个参数。

   • 参数名： province (必须与数据集中的占位符一致)
   • 显示名称： 省份
   • 控件类型： 选择 参数面板

3. 选中刚刚创建的 province 参数，在右侧的“控件设置”中,进行关键配置：

   • 数据字典： 这是参数面板选项的来源，点击右侧的 按钮。
   • 在弹出的“数据字典”窗口中，选择 数据库查询。
   • SQL 语句： 编写一个查询所有省份的 SQL，注意，这个查询不需要使用参数。

     SELECT DISTINCT province FROM sales_data ORDER BY province

   • 显示列： 选择 province。
   • 实际值列： 也选择 province (因为显示值和实际值是同一个)。
   • 提交方式： 选择 实时提交 或 按钮提交。
     • 实时提交： 用户选择后立即刷新报表,体验流畅。
     • 按钮提交： 用户需要点击一个“查询”按钮才刷新报表，适合复杂报表,避免频繁刷新。

4. （可选）添加“查询”按钮：

   • 如果选择了“按钮提交”，还需要在参数面板区域拖入一个按钮控件。
   • 选中按钮，在右侧的“事件”中，添加一个“点击”事件，选择 提交所有参数。

步骤 4：预览效果

1. 点击工具栏的 预览 按钮。
2. 在报表上方，你会看到一个下拉框,里面列出了所有省份。
3. 当你选择“江苏省”时，报表会立即刷新,只显示江苏省的销售数据。

至此,一个基本的动态参数报表就完成了。

进阶应用

联动参数

场景：先选择省份,再选择该省份下的城市。

实现方法：

1. 创建两个参数： province 和 city。
2. 配置省份参数 (province)：

   和上面例子一样，数据字典 SQL 查询所有省份。

3. 配置城市参数 (city)：
   • 数据字典的 SQL 需要根据省份参数来动态生成。
   • SQL 语句写法：

     SELECT DISTINCT city FROM sales_data WHERE province = '${province}'

   • 关键： 在“控件设置”中，勾选 依赖参数，并选择 province。
4. 预览： 当你选择一个省份后,城市下拉框的选项会自动更新为该省份下的城市。

默认参数

可以为参数设置一个默认值，这样报表在首次加载时就会显示默认的数据。 在“模板参数”窗口中，选中参数，在“控件设置”的“默认值”一栏输入你想要的默认值，江苏省。

动态SQL

如果筛选条件非常复杂，使用多个 ${param} 会很麻烦，可以使用动态SQL，将整个 WHERE 条件作为参数传递。

1. 创建一个参数 whereCondition，类型为 文本框。
2. 在数据集的 SQL 中，使用这个参数：

   SELECT ... FROM sales_data WHERE ${whereCondition}

3. 在报表的参数面板，可以添加多个控件（如复选框、文本框等），然后用 JavaScript 拼接出完整的 WHERE 条件字符串，最后赋值给 whereCondition 参数,并触发提交。

最佳实践与注意事项

1. 命名规范： 参数名最好使用英文或拼音，避免使用中文,以防在某些情况下出现编码问题。
2. SQL 注入防护： 对于 TextEditor（文本框）这类用户自由输入的控件，一定要警惕 SQL 注入风险，FineReport 在处理 ${param} 时会进行预编译，能有效防止大部分注入，但对于拼接 SQL 的场景,仍需谨慎。
3. 性能考虑：
   • 参数面板的数据集（用于生成选项列表）应尽量简单,查询速度快。
   • 避免在报表中放置过多、过复杂的动态参数,以免导致页面卡顿。
4. 用户体验：
   • 为参数控件添加清晰的“显示名称”和“提示信息”。
   • 合理使用“默认值”和“重置”功能。
   • 对于数据量大的下拉框，可以考虑使用“分页加载”或“搜索”功能。
5. 文档化： 在复杂的报表模板中，可以添加注释，说明每个参数的用途和依赖关系,方便后续维护。

希望这份详细的指南能帮助你完全掌握 FineReport 的动态参数功能！