报表参数

概述

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

参数类型

在 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)

默认值

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

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

在单元格的数据集过滤条件中，将 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 参数运行报表。

SQL 示例集（速查）

参数一律用 $参数名（单个 $）。

基础过滤

WHERE dept = $dept                                  -- 等值
WHERE amount >= $minAmount                           -- 数值比较
WHERE order_date BETWEEN $startDate AND $endDate     -- 日期区间
WHERE dept IN ($depts)                               -- 多选(List)→ IN

模糊查询（用 ${表达式} 拼接）

WHERE name LIKE ${'%' + $keyword + '%'}

可选条件（参数为空则忽略，用 #{条件 ? 'SQL' : ''}）

SELECT * FROM orders
WHERE 1 = 1
  #{$status != null && $status != '' ? 'AND status = $status' : ''}
  #{$dept   != null ? 'AND dept = $dept' : ''}

用表达式函数算条件

WHERE create_time >= ${addDays(now(), -$days)}   -- 最近 N 天
WHERE status = $$config.status                     -- 取「脚本配置」项

分组聚合

SELECT dept AS 部门, SUM(amount) AS 金额, COUNT(*) AS 单数
FROM orders
WHERE order_date BETWEEN $startDate AND $endDate
GROUP BY dept
ORDER BY 金额 DESC

这里的 ${...}（表达式插值）与 #{...}（动态 SQL 片段）是数据集 SQL 的高级写法，完整模板见 数据集。

进阶 SQL 示例

标准 SQL 写法，参数仍用 $参数名。

CASE WHEN 分类

SELECT name,
  CASE WHEN amount >= 10000 THEN '大客户'
       WHEN amount >= 1000  THEN '中客户'
       ELSE '小客户' END AS 等级
FROM customer
WHERE create_date >= $startDate

子查询求占比

SELECT dept,
  SUM(amount) AS 金额,
  SUM(amount) * 100.0 / (SELECT SUM(amount) FROM sales WHERE yr = $year) AS 占比
FROM sales
WHERE yr = $year
GROUP BY dept

TopN（按数据库方言）

-- MySQL / PostgreSQL
SELECT * FROM orders ORDER BY amount DESC LIMIT 10
-- SQL Server
SELECT TOP 10 * FROM orders ORDER BY amount DESC
-- Oracle 12c+
SELECT * FROM orders ORDER BY amount DESC FETCH FIRST 10 ROWS ONLY

按月分组汇总

-- PostgreSQL
SELECT to_char(order_date, 'YYYY-MM') AS 月份, SUM(amount) AS 金额
FROM orders
WHERE order_date BETWEEN $startDate AND $endDate
GROUP BY 1 ORDER BY 1

行转列（交叉表，CASE WHEN 聚合）

SELECT product,
  SUM(CASE WHEN quarter = 1 THEN amount ELSE 0 END) AS Q1,
  SUM(CASE WHEN quarter = 2 THEN amount ELSE 0 END) AS Q2,
  SUM(CASE WHEN quarter = 3 THEN amount ELSE 0 END) AS Q3,
  SUM(CASE WHEN quarter = 4 THEN amount ELSE 0 END) AS Q4
FROM sales
WHERE yr = $year
GROUP BY product

多表 JOIN

SELECT o.order_no, c.name, o.amount
FROM orders o
JOIN customer c ON o.customer_id = c.id
WHERE o.order_date >= $startDate