参数类型、默认值与传参

概述

报表参数是报表运行时的输入变量。参数独立于查询表单存在：查询表单只是其中一种输入方式，没有绑定控件的参数照样可以被 SQL、表达式和数据集过滤条件引用。运行时，服务端把各来源传入的参数值与报表里定义的参数逐个合并，得到最终生效的参数值。

本文说明参数的定义、类型、默认值和来源。参数在 SQL 与表达式里的引用写法，见 SQL 参数与动态语法 与 数据集。

功能入口

设计器顶栏左侧「查询参数设置」，打开「报表参数配置」对话框。对话框顶部有「添加参数」按钮和「共 N 个参数」计数，参数以表格形式编辑。

操作步骤

1. 点击「添加参数」新增一行。
2. 在「参数名称」列填写名称。名称不能为空，也不能与其他参数重名。
3. 在「参数类型」列选择类型；类型为「集合」时，同一格内多出一个元素类型下拉。
4. 在「默认值模式」列选择默认值的给法，在「默认值」列填写默认值。
5. 在「备注说明」列填写说明，点「确定」保存。

属性说明

参数类型

日期与日期时间参数接收字符串，系统自动识别常见日期格式，无法识别时得到空值。建议按 yyyy-MM-dd、yyyy-MM-dd HH:mm:ss 传值。

元素类型

类型为「集合」时可设置元素类型：

编码类的值（如 001）应使用文本元素，数值元素会把 001 变成 1。

默认值模式

日期预设列表：

参数值的来源与合并

服务端按报表里定义的参数逐个合并：

1. 传入了该参数的值（值不为 null）：使用传入值；
2. 没传值：使用默认值（固定值、表达式或日期预设的计算结果）；
3. 传入值按参数类型转换。

由此得到两条规则：

• 报表里没有定义的参数名，即使传入也会被丢弃，不报错、无日志。参数名必须与「报表参数配置」里的「参数名称」完全一致。
• 「重置」按钮清空的控件没有传值，服务端按默认值补齐；数组值以空数组提交，不回到默认值。

集合参数

集合参数用于「多选」「IN 条件」。

输入写法

在「默认值」、预览「参数调试」抽屉等文本输入处，集合参数按以下规则解析：

• 用半角逗号 ,、全角逗号 ， 或顿号 、 分隔，逐项去除首尾空白并忽略空项，1，2、3 得到三项；
• 也可以写 JSON 数组，如 ["A","B"]；
• 空文本得到空集合。

多选下拉绑定集合参数时提交数组；绑定字符串参数时提交逗号分隔的字符串。

在 SQL 中使用

SELECT * FROM demo_客户
WHERE 所在大区 IN (${$regions})

IN 里只写一个集合参数占位符，运行时按元素个数展开为对应个数的占位符：

字符串常量里的 ? 不算占位符。存储过程不做展开，多值集合传给存储过程会明确报错。

示例

为客户明细报表增加「多选大区」条件，并设置一个动态日期默认值。

1. 「报表参数配置」中添加参数：regions，类型「集合」，元素类型「文本元素」，默认值填 华东，华北（全角逗号也可以）；asOf，类型「日期」，默认值模式「日期预设」，选「本月月初」。
2. 数据集 SQL：

SELECT 客户名称, 所在大区, 注册日期
FROM demo_客户
WHERE 所在大区 IN (${$regions})
  AND 注册日期 >= ${$asOf}

3. 「查询表单设计」中添加「多选下拉」绑定 regions，选项类型「直连SQL字典」，SQL 为 SELECT DISTINCT 大区 AS label, 大区 AS value FROM demo_地区；添加「日期框」绑定 asOf；添加「查询按钮」。
4. 预览：首次打开按默认值 华东、华北 和本月月初出数；取消一个大区再点「查询」，IN 条件随之减少一项。
5. 点「重置」并查询：asOf 按预设日期补齐，regions 以空集合提交，结果为空。

注意事项

注意：${$参数名} 与裸写的 $参数名 在数据集 SQL 中都表示参数引用，值以预编译占位符绑定，不会拼入 SQL 文本。${参数名}（没有内层 $）是未定义的变量，会求值为空。

注意：控件绑定的参数类型必须兼容，见 查询表单控件。

提示：日期预设只对日期、日期时间类型有效；其他类型选择表达式模式，用表达式函数计算默认值。

相关文档

• 查询表单概述
• 查询表单控件
• 报表预览
• SQL 参数与动态语法
• 数据集