本文是ERIS报表系统的基础理论一篇，主要包含下面几个方面的内容：

  1. 什么是参数
  2. 参数的基本属性
  3. 报表如何处理参数
  4. 如何配置报表参数
  5. 报表参数的展现方式
  6. 自定义报表中的参数处理
  7. 参数表达式
  8. FAQ

1、什么是参数

参数即是报表的查询的条件，用户可以使用报表系统提供的参数输入界面输入参数值对报表进行过滤。

对于数据源为数据库的报表，参数等同于SQL语句中的占位符，在同一张报表中，相同的占位符标识相同的参数，且没有大小写区分。

对于自定义数据源的报表，参数是由数据源决定如何处理的，所以，参数是由数据源决定的，这点在后面的章节进行详细描述，本节只描述数据源为数据库的报表中参数的处理。

例如在以下SQL语句中，@fieldValue和@fieldValue2作为报表的参数存在， 其中@fieldValue这个参数被使用了两次，当作相同的参数处理。

select * from table_name
where filedName=@fieldValue
and filedName2=@fieldValue2
and filedName3=@fieldValue

参数标识符是大小写不敏感的，@fieldValue2和@FiEldValUe2作为相同的参数处理。 在报表系统中，使用"@"，"#"和":"作为SQL的参数标识符前缀。

数据库作为数据源报表是基于标准的JDBC进行数据库查询，所以SQL语句和参数的规格也应该和JDBC所约束的一致。在报表系统中，对SQL语句进行了一次预先分析，相比标准的JDBC有以下几点增强：

  1. 支持多行的SQL语句，使用"\r\n"或者"\n"进行换行处理。
  2. 在SQL语句中可以使用注释，支持标准的行注释和块注释。
  3. 支持参数标识符，相同的标识符作为同一个参数处理。

关于这几点增强，请参考相关文章《ERIS:底层通用平台功能介绍和使用手册》

2、参数的基本属性

因为在自定义报表处理中，参数的含义可以根据不同的需要而变更，所以以下针对数据库作为数据源的报表参数进行详细描述。参数的基本属性包含：

  • 参数的占位符：参数实际的标识。SQL语句中的原始占位符，如前面的示例，参数@fieldValue 本属性的值恒定为"@fieldValue"。
  • 参数名称：参数显示的名称。提供在前端显示的参数名称，如前面的示例，参数@fieldValue 显示的名称比较晦涩，可以将此参数的名称设置为"地区代码"类似的描述性的信息，方便用户查询报表的时候输入参数。
  • 数据类型：参数值的数据类型。数据类型直接决定了用户选择参数的控件和参数的行为，例如在SQL语句"@CITY+1"中的参数@CITY数据类型为字符串、数字的时候，其表现是迥异的。
  • 字典类型：在用户输入报表参数的时候，为了方便用户输入，系统可以使用值-名称对对数据进行描述，一般称之为字典或者码表。报表系统中将字典和码表进行统一配置和存储，方便字典在不同的报表中复用。一般而言，有字典的参数提供给用户的选择控件是一个下拉列表。
  • 是否使用字符串拼接：在使用字符串拼接的情况下，在SQL语句中直接体现为对SQL语句的字符串拼凑，本属性一般用于在SQL语句中动态表名使用，例如SQL语句"Select * from @TableName"，对于参数值，用户输入什么则在该位置替换成什么。
  • 是否是单选参数：参数是否是单选参数，默认的情况下，允许用户输入多个参数值。
  • 是否是固定参数值：对于报表而言，参数是否是固定了值，不允许用户在查询其间进行修改。本属性一般用于报表需要根据用户权限过滤特定数据的时候，例如四川省的用户只能查看四川的数据，这个参数值是由用户本身的属性确定的，在用户登录到系统的Session有效期内是不能变更的。
  • 是否是可选参数：参数是否可选。可选参数是指用户如果不输入参数值则使用默认的过滤，一般而言是本参数过滤条件失效。
  • 参数默认值：默认的参数值。
  • 参数备选值列表：允许用户输入的参数值列表。
  • 参数临界最大值：允许用户输入的参数值的最大值。
  • 参数临界最小值：允许用户输入的参数值的最小值。
  • 参数显示模式：参数的显示模式是值以编码的方式对参数的最终选择控件进行配置，不同的配置模式显示的参数选择子不一样，在下面的章节中，我们详细描述如何配置这些选择子。
  • 参数备注信息：参数的描述信息。

3、报表如何处理参数

以下使用HTML输出模式描述报表系统如何处理参数。处理参数包含两个部分工作：

  1. 将参数列出来提供用户进行输入值。
  2. 收集用户输入的参数值并提交给数据源处理器处理，并依此生成最终的报表数据返回给用户。

3.1提供参数输入界面

报表系统使用下面的流程对参数进行呈现

  1. 取得报表定义的参数列表，对参数列表中的各个参数进行下列步骤的操作。
  2. 取得参数的SelectorMode的值
  3. 取得Selector的处理标识，如果SelectorMode为空则根据数据类型和字典代码取得默认的Selector,基本规则为
    1. 当有字典的代码捆绑在参数上的时候，使用下拉列表作为参数选择框，下拉列表中的各个选项就是字典的各个值。如果是可选参数，则自动在下拉列表中增加一个空的选项，显示标题为"忽略此参数"。
    2. 日期时间类型的数据使用文本输入框，点击文本输入框弹出选择日期的控件，输入的字符串格式为YYYY-MM-DD
    3. 整数类型和浮点数类型使用普通文本输入框，当焦点离开输入框之后对数据进行校验，非数字则报错。
    4. 其他类型使用默认的文本输入框，不对输入值进行校验。
  4. 当有Selector的定义的时候，查找内存中Selector的对象处理函数，调用这些函数进行渲染。
  5. 输出参数输入脚本给客户。

3.2收集参数供数据源处理

收集参数的操作比较复杂，涉及到集中参数类型的交叉使用。收集参数值使用如下策略进行收集：

  1. 检查用户是否已经设置了参数值，如果已经设置则完成参数收集。
  2. 如果参数是固定参数，则直接从默认参数脚本中取得参数，如果没有取得参数，则报错。
  3. 如果参数设置了默认参数值脚本，则按照默认参数值脚本初始化参数。
  4. 如果参数是必选参数，而且没有取得参数值的情况下会报错，一般这种情况会导致直接转向参数输入界面。

参数值收集之后，会被用到数据库查询当中，数据库查询对参数的使用步骤如下：

  1. 分析SQL语句取得SQL参数列表。
  2. 根据SQL参数列表中的参数取得报表参数中对应的参数。
  3. 如果没有取得对应的报表参数则报错。
  4. 检查是否设置了参数值，如果设置了参数值则：
    1. 如果是拼接字符串参数，直接替换参数标识符所在的位置，拼接SQL语句。
    2. 如果是普通参数，检查是否输入了多个参数，如果是则检查是否需要修改SQL语句，之后使用JDBC的setXXX函数进行设置。多选的情况下SQL语句修改的规则如下
      1. 检查参数的前面操作符
      2. 操作符为等于则转换成IN
      3. 操作符为不等于则转换成Not In
      4. 操作符为IN和Not In则保持不变
  5. 如果没有设置参数值且参数为可选参数则修改SQL语句以忽略这个参数，忽略参数的规则非常简单，将这个子句设置成1=1。

4、报表参数配置

和报表的其他各个部分一样，我们可以使用XML、JSON和数据库对报表参数进行配置，由于JSON是使用在HTML输出器中，数据库则是使用的规范的表格存储报表参数，所以本节只描述XML配置报表参数的细节。

在配置中，我借用了"别名"一词对报表XML配置进行说明，例如某个XML节点的属性为"Name"，如果其别名为"Title"则<Node Name="Name">和<Node title="Name">表达的意思是完全相同的。

报表参数的XML定义路径结构如下

Report->Parameters[->Group]->Param

其中Group节点是可选的，在后面的章节中，我会详细描述Group节点所做的功能。

Param节点对参数进行实际配置，其XML属性有：

  • Param/Parameter:参数占位符，STRING类型值，不可为空，必须设置。
  • Name/Title:参数显示名称，STRING类型值，不可为空，必须设置。
  • DictId/Dict:数据字典代码，STRING类型值，默认为空，不使用字典。
  • DataType:数据类型标识，常量标识，默认为STRING，标识参数是字符串类型，具体值参考数据类型定义。
  • ReplaceValue/IsReplaceValue/Replace/InPlace:是否使用拼接字符串方式，BOOLEAN值，默认为false，可选值true和false。
  • SingleSelect/IsSingleSelect:是否单选，默认为false，BOOLEAN值，可选值true和false。
  • DefaultValue/Value:默认值设置，STRING类型，默认为空，格式参考本章最后的默认值设置。
  • Notes/Comment/Desc/Description:参数描述信息，STRING类型，默认为空。
  • FixedValue/Fixed/IsFixedValue:是否是固定参数值，默认为false，BOOLEAN值，可选值true和false。
  • Optional/IsOptional:参数是否可选，默认为false，BOOLEAN值，可选值true和false。
  • Selector/SelectorMode:参数选择模式，字符串，参考本章最后一节。
  • ValuesList/ValuesLimited/AllValues:参数备选值列表，STRING类型，默认为空，格式参考本章最后的默认值设置。
  • MaxValue/Max:参数的临界值，最大值，STRING类型，默认为空，格式参考本章最后的默认值设置。
  • MinValue/Min:参数的临界值，最小值，STRING类型，默认为空，格式参考本章最后的默认值设置。

以下为三个参数的配置Sample:

<report>
<parameters>
<param param="@city" name="选择地域:" dict="province" DataType="int" singleselect="false"
selector="dict(mode:fake,group:10)" optional="true" defaultValue="1" />
<group title="选择KPI统计的时间区域" width="30px" mode="text(width:100px)">
<param param="@beginDate" name="开始时间:" datatype="date" defaultValue="" optional="true"/>
<param param="@endDate" name="结束时间:" datatype="date" defaultValue="=lastYearDate()" optional="true"/>
</group>
</parameters>
</report>

5、报表参数的展现方式

报表参数的展现方式是在报表XML配置的Selector/SelectorMode中配置的，使用编码的字符串对配置进行编码，这样可以动态的增加展现方式，系统默认支持两种报表参数选择子：文本框和下拉列表，下文详细介绍这两种方式的配置脚本。Selector的格式为：

函数名(参数1：参数值，参数2：参数值….)

函数名直接指定了参数选择子的类型，以下为两种选择子的别名：

  1. Combox/Select/Dict：下拉列表选择子
  2. TextBox/Text/Input：文本框

以下为两种参数选择子的参数列表

5.1 TextBox选择子参数

  1. Mode：Mode参数指定TextBox的输入类型，默认的情况下是根据参数类型决定输入框的表现，可以使用Mode强制修改这个值。Mode的可选值列表如下：
    1. Datetime：日期选择，并选择时间，输入的格式为YYYY-MM-DD HH:MS:SS
    2. Time：时间选择，输入格式为 HH:MS:SS
    3. Date：日期选择，输入格式为YYYY-MM-DD
  2. Group：分组标识是为了更好的组织参数的展现行为，系统将相同分组标识的参数放在一行显示，否则放在多行显示。
  3. Width：宽度标识，指定输入框的宽度，可以使用标准的HTML度量，例如像素使用px作为后缀，点使用pt作为后缀，字数使用em作为后缀，也可以使用百分比作为宽度标识。
  4. Class：CSS风格标记。
  5. Validate：Boolean类型的值，指定是否需要进行客户端校验值，默认的情况下是True。
  6. GroupTitle：分组的标题，在分组上加一个标题行。

5.2 Combox选择子参数

  1. Mode：附加显示风格，默认为空，显示标准的HTML Select标签。Mode的可选值列表如下：
    1. Flat：使用展开的层模拟下拉列表选择。
    2. Fake：使用层直接模拟下拉列表的样式。
  2. Group：分组标识是为了更好的组织参数的展现行为，系统将相同分组标识的参数放在一行显示，否则放在多行显示。
  3. GroupTitle：分组的标题，在分组上加一个标题行。
  4. Values：直接指定下拉列表的值对，格式为：ID|Name;ID|Name例如：

    Combox(Values:ID1|名称1;ID2|名称2;ID3)

    显示的下拉列表中包含三个值，ID1、ID2、ID3，注意最后一个ID3显示的文本也是ID3，因为ID3没有配置竖线后面的名称。

在Mode等于Flat的模式下，以下参数生效：

  1. Width：设置模拟输入框的宽度，可以使用标准的HTML度量，例如像素使用px作为后缀，点使用pt作为后缀，字数使用em作为后缀，也可以使用百分比作为宽度标识。
  2. Inline：Boolean类型值，不显示模拟层，直接在同一行显示输入值，默认为False。
  3. ShowDiv：Boolean类型值，在初始化的时候是否显示模拟层，默认为True。
  4. AddButton：Boolean类型值，是否增加"清除"和"全选"两个按钮，默认True。

5.3 XML配置中的Group配置

在XML配置中的Group可以设置一个分组，所有下级的Param都设置相同的Group标识，Group节点还可以设置以下默认参数：

  1. Width：设置模拟输入框的宽度，可以使用标准的HTML度量，例如像素使用px作为后缀，点使用pt作为后缀，字数使用em作为后缀，也可以使用百分比作为宽度标识。
  2. Title/GroupTitle：分组的标题，在分组上加一个标题行。
  3. Mode/Selector/SelectorMode：分组内各个参数的Mode默认值。

注意：分组内的Group标识是自动设置的。

6、自定义报表的参数处理方式

对于自定义报表的配置和使用，请参考二次开发手册。

在自定义报表中，因为外接程序具有对报表的所有操作权，所以引擎并不严格限制自定义报表如何处理参数。

7、参数中表达式

参数中可以使用表达式对参数值进行动态赋值，目前版本中，参数表达式支持从用户信息中取得资料。参数表达式一般出现在参数值设置的几个地方：默认参数值、参数值备选列表、参数最大值和最小值。

当在这些参数配置中使用等于号作为前置标识的时候，报表引擎认为这个参数使用的是表达式动态赋值，每次在用户发起查询的时候，引擎会执行表达式进行参数动态赋值。如下两个参数定义：

<param name="ParamA" defaultValue="=AValue"/>
<param name="ParamB" defaultValue="BValue"/>

参数ParamA的默认参数值是一个表达式，表达式的内容是"Avalue",表明一个叫做Avalue的变量；而参数ParamB设置的默认参数值是一个常量字符串"BValue"，ParamB的参数默认值恒定为字符串"BValue"转换的参数对应类型。

参数表达式中还有一种特殊情况，就是数组的支持，数组是使用"["开头，使用"]"作为结尾，数组元素之间使用逗号分割。每个数组元素可以是常量、变量，也可以是表达式。

8、FAQ

1、问：SQL语句中在设置Like的时候可选参数分析错误是为什么？

答：SQL分析器存在一定的局限，不能完全分析出子句，需要使用括号，使用 Afield like ('A'||@Param||'B' ) 方式。