1. 概述
1.1 版本
| 报表服务器版本 | JAR 包版本 | 功能变动 |
|---|---|---|
| 10.0.11 | 2020-12-02 |
|
1.2 应用场景
在报表的具体应用中，经常使用「控件」来实现不同的功能。根据使用方式可将控件分为填报控件和参数控件两大类，填报时使用的控件为填报控件，参数界面使用的控件为参数控件，这两种控件的类型基本相同，只是在使用方面略微有所不同。本文整理控件相关文档，用户可根据本文快速查找所需控件文档。
注：控件事件具体介绍请参见：控件事件
2. 控件分类
控件类型详细统计如下表所示：
注1：所有控件的「控件名称」均不支持为空或重复。名称要遵循规则，否则会导致模板错误，命名规则可参考：参数命名规则
注2：控件的「属性」设置界面，所有输入框类型的位置都不支持写 HTML ，如 
| 控件类型 | 具体控件 | 控件简介 | 参考文档 |
|---|---|---|---|
| 参数控件/填报控件 | 文本控件 | 用于填写或者输入短文字，一般用于昵称、名称、字数少且固定的内容的填写。
| 文本控件 |
| 文本域控件 | 相比文本控件支持换行符，当用户需要输入或编辑较长文字时可使用该控件，比如简历中的工作经验、个人特长等。
| 文本域控件 | |
| 数字控件 | 可通过该控件输入数字信息（整数、负数、小数），当用户想要使用数值时可以使用，比如填写销量，订单数量这种场景。
| 数字控件 | |
| 密码控件 | 在输入过程中不会直接显示出输入的内容，一般可通过该控件输入密码信息，录入密码。
| 密码控件 | |
| 按钮控件 | 呈现一个按钮形式，一般用于点击操作。给按钮添加一些事件导致点击后可触发某些报表操作，如点击按钮查询，点击按钮提交、删除、插入一行、展开报表等等。
| 按钮控件 | |
| 复选按钮控件 | 一个按钮，两个值，勾选和不勾选，分别对应选择与不选择，适合用于判断“是”、“否”选项的场景。
| 复选按钮控件 | |
| 单选按钮组控件 | 可以有多个按钮，每个按钮对应一个值，在多个按钮组成的按钮组中选择其中一个，适合多个选项选一个的场景，比如选择请假类型。
| 单选按钮组控件 | |
| 复选按钮组控件 | 可以有多个按钮，每个按钮对应一个值，在多个按钮组成的按钮组中可以选择多个，适合多个选项选择数可以大于 1 的场景。
| 复选按钮组控件 | |
| 下拉框控件 | 可以有多个值，展开选项后下拉选择一个值，一般用于选择某个选项信息，从多个选项中选择其中一个。
| 下拉框控件 | |
| 下拉复选框控件 | 可以有多个值，展开选项后下拉可以选择多个值，一般用于从多个选项中选择几个选项。
| 下拉复选框控件 | |
| 日期控件 | 当用户需要输入一个时间，可以使用日期控件，弹出时间面板进行选择。
| 日期控件 | |
| 下拉树控件 | 可以有多个值，展开选项后下拉选择一个值，选项值是具有多层树状结构的数据。
| 下拉树控件 | |
| 视图树控件 | 可以有多个值，选择一个值，选项值是具有多层树状结构的数据。和下拉树比较，选项不是下拉的，是直接呈现出来的。
| 视图树控件 | |
| 填报控件 | 文件控件 | 用于上传附件，比如图片，Word、PDF等附件。
| 文件控件 |
| 列表控件 | 允许多个选项值，列表展示，可选择其中的一个选项值。
| 列表控件 | |
| 网页框控件 | 一般用于在报表页面中嵌入其他网页，如报表中嵌入一个官网网页。
| 网页框控件 | |
| 参数控件 | 标签控件 | 一般可以写一些提示、标题的内容，不能输入内容，和文本框相比没有边框，只有文字。
| 标签控件 |
| 查询按钮 | 点击该按钮后可查询数据，属性和按钮一致，但是内置了查询，不用自己设置查询。
| - | |
| 预定义控件 | 一般应用于自定义比较复杂且需要重复使用控件，自己定义一个控件，之后可以重复使用。
| 控件管理 |
3. 控件与参数的绑定方式
1）在使用参数控件时，当已经完成全局参数、模板参数或数据集参数设置后，编辑参数面板，选择全部添加即可添加与参数绑定的参数控件，如下图所示：
2）编辑参数面板，选择需要的控件，设置参数控件的名称为对应的参数名也可以完成控件与参数绑定。例如：设置模板参数为货主地区，编辑参数面板，拖入下拉框控件，设置控件名称为货主地区。如下图所示：
3）填报控件与参数绑定示例可参考：JS实现使用填报页面的控件查询 。
4. 注意事项
4.1 数据字典联动会清空控件值
当前功能设计下，控件在触发数据字典联动时，会清空被联动控件的值。
4.2 有控件值的参数面板控件在初始化时就会计算数据字典
带有数据字典设置的参数面板控件，如果没有默认值，则其数据字典会在点击控件触发选项时才会计算；如果有默认值，则在控件初始化的时候就会计算数据字典。所以当数据字典的 sql 执行速度较慢的情况下，设置默认值会对模板整体加载速度有明显影响。
4.3 模糊搜索会分开匹配输入字符
下拉树、下拉框，下拉复选框带有模糊搜索功能，在匹配的时候会将多个字符拆开来进行匹配。例如输入 ABC ，则会匹配数据字典中同时有 A、B、C 且顺序一致的数据，而不是只匹配 ABC 连在一起的数据。
如果是用拼音来模糊搜索中文的话，程序会先将中文解析为拼音，之后按照上述逻辑来进行匹配。如下图所示，输入 nn ，会匹配到饼干(binggan)，因为拼音中存在2个 n 。
4.4 模糊搜索会同时从实际值和显示值中进行匹配
带有模糊搜索功能的控件，比如下拉框，下拉复选框等，如果数据字典设置了不同的实际值和显示值，在模糊搜索的时候，会根据输入字符，同时从实际值和显示值中匹配对应的数据。
4.5 文本和数字控件输入不符合校验规则的值后，会返回上一次输入的值
设置了校验规则的文本或者数字控件，当输入值不符合规则的时候，会有相应提示，并且当前输入值会被清空，返回上一次输入的值。
4.6 填报控件未进入输入状态时，输入的第一个字会变成字母
在使用单元格控件进行输入时，需要双击控件进入输入状态后，方可编辑。如果只是选中了单元格，未进入输入状态，则输入的第一个字会变成字母。
填报页面修改触发控件编辑状态的逻辑可参考：JS设置控件焦点
4.7 控件数据字典的数字丢失精度
问题描述
当控件数据字典使用的字段类型为数字类型时，例如 bigint，有可能会出现丢失精度的问题，如图所示：
解决方案
需要将数字类型转为字符串类型，例如下图所示在 sql 中进行转换。