报表参数

最后更新: 2026/6/1

定义和使用报表参数，实现动态查询条件传入

概述

报表参数允许用户在运行时动态传入查询条件（如时间范围、部门等）。参数值可用于 SQL 语句、表达式及数据集过滤条件。

参数类型

类型	说明	格式示例
`String`	字符串	`"技术部"`
`Number`	数字	`100`
`Boolean`	布尔值	`true`
`Date`	日期	`"2024-01-01"`（`yyyy-MM-dd`）
`DateTime`	日期时间	`"2024-01-01 00:00:00"`
`List`	列表（多选）	`["A", "B"]`

在 SQL 中引用参数

在 SQL 语句中使用 $参数名 引用报表参数：

SELECT dept, emp_name, amount
FROM sales
WHERE order_date >= $startDate
  AND order_date <= $endDate
  AND dept = $dept

注意：SQL 参数格式为 $参数名（单个 $ 前缀），而非 :参数名 或 #{参数名}。

在表达式中引用参数

在表达式中同样用 $参数名 访问参数值：

// 格式化日期参数
formatDate($startDate::date('yyyy-MM-dd'), "yyyy年MM月dd日")

// 参数空值保护
$dept == null ? "全部部门" : $dept

// 参数条件判断
if(isNull($minAmount), true, amount >= $minAmount)

默认值

参数可配置默认值，支持静态值和表达式两种方式：

场景	示例
静态默认值	字符串 `"技术部"`，日期 `"2024-01-01"`
表达式默认值（动态）	`monthStart(now(), 'yyyy-MM-dd')`（本月第一天）
动态表达式：月初	`monthStart()`
动态表达式：年初	`yearStart()`
动态表达式：当前用户	`userAccount()`

在数据集过滤条件中引用参数

在单元格的数据集过滤条件中，将 rightValueType 设为 Parameter，rightValue 填写参数名（不加 $）：

// 过滤条件配置示例（JSON）
{
  "joinType": "and",
  "itemType": "common",
  "leftValue": "dept",
  "operator": "equals",
  "rightValueType": "Parameter",
  "rightValue": "dept"
}

参数在 URL 中传入

通过 URL 查询字符串传入参数，用于外部系统嵌入报表时自动带入条件：

http://localhost:8088/report/view/report-001?startDate=2024-01-01&endDate=2024-12-31&dept=技术部

提示：URL 传参时，showQueryForm=false 可隐藏查询面板，直接用 URL 参数运行报表。