finereport 日期参数

下面我将从基础概念、创建方法、常用技巧、进阶应用四个方面，全面地为您介绍 FineReport 的日期参数。

基础概念

在 FineReport 中，参数是报表与用户进行交互的桥梁，用户通过设置参数的值，来影响报表中数据的查询和显示。

日期参数就是专门用来接收用户输入的日期或日期范围的参数，它通常用于以下场景：

1. 动态筛选数据：筛选“某一天”、“某一周”、“某一个月”或“自定义日期范围”的订单数据。
2. 作为报表标题显示为“2025年10月销售业绩”。
3. 作为计算基准：计算“与去年同期相比的增长率”。

如何创建和使用日期参数

创建日期参数主要分为两步：定义参数 和 在报表中使用参数。

步骤 1：定义参数

1. 打开 FineReport 的设计器，在报表的参数面板中，点击 号添加新参数。

2. 在弹出的“参数设置”对话框中，配置以下关键属性：

   • 名称：给参数起一个唯一的名字，date_param，这个名字会在公式和SQL中用到。
   • 显示名称：在报表界面中给用户看的名称，请选择日期”。
   • 控件类型：这是最关键的一步，决定了用户如何输入日期，对于日期参数，常用以下几种：
     • 日期：提供一个文本框和一个日期选择器图标，用户可以直接输入或点击选择日期。这是最常用的类型。
     • 日期范围：提供两个日期框，用于选择一个起始日期和结束日期，非常适合筛选“一段时间内”的数据。
     • 下拉框：可以预设一些固定的日期选项，如“、“昨天”、“本周”、“本月”、“本季度”、“本年”等，让用户快速选择。
     • 单选按钮组：与下拉框类似，以按钮组的形式展示预设选项。
   • 数据类型：通常选择 日期 或 日期时间。
   • 缺省值：设置参数的默认值，这对于用户首次打开报表时非常有用。
     • 可以是固定值,如 2025-10-01。
     • 也可以是动态函数,如：
       • TODAY()：今天的日期。
       • YEARDATE()：今年的第一天。
       • MONTHDATE()：本月的第一天。
       • WEEKDATE()：本周的第一天（周日或周一，取决于系统设置）。
   • 校验规则：可以设置日期的格式或范围限制，防止用户输入无效值。

示例：创建一个“日期范围”参数

1. 在参数面板添加新参数。
2. 名称：date_range
3. 显示名称：查询日期范围
4. 控件类型：日期范围
5. 数据类型：日期
6. 缺省值：可以设置为 MONTHDATE() 到 TODAY()，默认查询本月至今的数据。

步骤 2：在报表中使用参数

定义好参数后,就需要将它应用到数据查询或展示中。

在 SQL 查询中使用（最常用）

在数据集的 SQL 语句中，使用 语法来引用参数。

示例：查询订单表，并根据 date_range 参数筛选数据

假设你的 SQL 模板如下：

SELECT
    order_id,
    customer_name,
    order_date,
    amount
FROM
    orders
WHERE
    -- 重点在这里：使用 ${} 引用参数
    order_date >= '${date_range}' AND order_date <= '${date_range_end}'

注意：

• 对于“日期范围”类型的参数，FineReport 会自动生成两个参数：date_range (起始日期) 和 date_range_end (结束日期)。
• 强烈建议：在 SQL 中使用 >= 和 <=，而不是 > 和 <，这样可以避免边界数据（比如0点或24点的数据）被遗漏。

在公式中使用

在报表单元格的公式中,同样可以使用 ${参数名} 来获取参数值。

示例：在报表标题中显示当前查询的日期范围

在 A1 单元格中输入如下公式：

=${date_range} 至 ${date_range_end} 销售报表

当用户选择日期范围后,标题会动态更新。

在图表或条件格式中使用

日期参数也可以作为图表的筛选条件,或者用于设置条件格式的判断依据，其方法与在 SQL 中类似，都是通过 ${参数名} 来引用。

常用技巧与最佳实践

使用日期函数处理参数

有时,我们不需要精确的日期，而是需要根据参数值计算出“年”、“月”、“周”等，FineReport 提供了丰富的日期函数。

• YEAR(${date_param})：获取参数中的年份。
• MONTH(${date_param})：获取参数中的月份。
• WEEK(${date_param})：获取参数中的周数。

示例：按月统计销售额

SQL 模板可以写成：

SELECT
    MONTH(order_date) AS order_month,
    SUM(amount) AS total_sales
FROM
    orders
WHERE
    -- 假设 date_param 是一个“日期”类型的参数，用户选择某一天
    YEAR(order_date) = YEAR('${date_param}') AND MONTH(order_date) = MONTH('${date_param}')
GROUP BY
    order_month

参数联动

日期参数可以与其他参数联动,实现更复杂的交互。

示例：选择年份后，月份下拉框才可用

1. 创建一个年份参数 year_param（控件类型为下拉框，选项为固定年份或动态生成）。
2. 创建一个月份参数 month_param（控件类型为下拉框）。
3. 选中 month_param 参数，在右侧的“控件”设置中，找到控件可见性或可用性的设置。
4. 设置其条件为：year_param 不为空，这样，只有先选择了年份，月份下拉框才会变为可选状态。

参数默认值的灵活设置

除了使用内置函数,还可以使用公式来设置更智能的默认值。

• 默认显示最近7天：
  • 起始日期：DATEADD("dd", -7, TODAY())
  • 结束日期：TODAY()
• 默认显示上个月：
  • 起始日期：MONTHDATE(MONTHADD(TODAY(), -1))
  • 结束日期：MONTHADD(TODAY(), -1)

处理日期格式问题

• 数据库与 FineReport 的格式：确保数据库中的日期字段是 DATE 或 DATETIME 类型，FineReport 在处理 语法时，会自动将参数值转换为数据库可识别的格式，通常无需手动转换。
• 显示格式：在单元格或图表标签中显示日期时，可以使用 TEXT() 函数来格式化。
  • =TEXT(${date_range}, "yyyy年MM月dd日") 会将日期显示为 2025年10月27日。

进阶应用

日期参数与模板填报结合

在填报报表中,日期参数可以用来指定数据录入的周期，一个日报表，默认日期参数为 TODAY()，用户每天打开报表，只需要填写当天的数据即可。

日期参数与定时调度结合

在设置定时调度任务时,可以将日期参数的值设置为调度运行时的日期，创建一个“昨日数据汇总”的定时任务，参数的值可以设置为 DATEADD("dd", -1, TODAY())。

动态参数面板

对于非常复杂的日期筛选,可以创建一个包含多个日期参数（如开始日期、结束日期、对比日期等）的参数面板，并利用参数面板的显隐性功能，让用户通过复选框等方式决定使用哪些筛选条件。

掌握 FineReport 的日期参数，是制作交互式、动态化报表的关键一步，通过灵活运用以上方法和技巧，您可以创建出满足各种复杂业务需求的报表。