查询表单控件

概述

「查询表单设计」的组件库共 14 种控件。除「文本」「查询按钮」「重置按钮」外，每个控件都要绑定一个报表参数，且参数类型必须在该控件支持的范围内，否则「绑定参数」下拉里看不到该参数，点击对话框「确定」时也会被拦下。

选项类控件（下拉框、多选下拉、单选组、复选组）的选项来源和联动见 下拉选项来源与联动。

控件与参数类型对应表

参数类型的中文名对应关系：字符串 String、数值 Number、布尔值 Boolean、日期 Date、日期时间 DateTime、集合 List。

所有控件的通用属性

选中控件后，右侧「组件属性」面板按分区展示。

基本信息

组件属性中的通用项

样式配置

位置信息

各控件的专有属性

文本

输入框

数值框

日期框

格式统一使用小写标记 yyyy、MM、dd、HH、mm、ss。各选择类型的默认格式与预设：

年份、年月、时间只能绑定字符串参数，面板会提示「建议绑定 String 类型参数」。控件宽度太窄时，运行时会自动隐藏日期框的清空按钮。

日期范围

一个控件同时写入起、止两个参数，适合按月或按日筛选统计区间。控件左侧是快捷项，右侧是双日历。

取值形态：

• 起始值、结束值按粒度提交为 yyyy-MM-dd（按天）或 yyyy-MM（按月），按月时「止」也是所选月份，而不是月末。
• 数据集 SQL 里用起止两个参数：

WHERE 日期 BETWEEN ${$p_start} AND ${$p_end}

• 使用者没选、也没有默认区间时，起、止参数都不下发。
• 「粒度参数」下发的值：按月粒度恒为 month；按天粒度时，起止跨度（含首尾）不超过 31 天为 day，否则为 month。
• 面板上算出的区间超过「最长跨度」的快捷项不会显示。选择的区间（包括默认区间）超过最长跨度时，点击「查询」被拦截，报表区域提示「控件标签最长 N 个月」（按天粒度为「N 天」）。

内置快捷项，按粒度过滤后显示：

按月粒度下，「本月」是当月，「近 N 个月」是含当月的最近 N 个月。

树形下拉

「树形配置」分区的属性：

数据来源为「自定义」时，点「编辑树形数据」打开「树形数据编辑」对话框，用「添加根节点」「全部展开」「全部收起」维护节点。数据来源为「数据集」时：

多选树的下拉面板顶部有「全选」「反选」「清空」和「已选 x / y」计数。

注意：设计器不提供树形下拉的懒加载配置。

多选下拉

选项配置见 下拉选项来源与联动。专有属性：

下拉面板顶部有「全选」「反选」「清空」和「已选 x / y」计数；输入关键字搜索后，这三个按钮只作用于当前过滤出的选项。选项用虚拟滚动渲染，选项很多时也只渲染可见的行。

下拉框、单选组、复选组

这三个控件除了通用属性外只有选项配置，见 下拉选项来源与联动。复选组可绑定集合、布尔值参数，单选组可绑定字符串、数值、布尔值参数。

开关

开关只有通用属性中的「是否必填」「是否禁用」。绑定布尔值参数，提交 true / false；绑定字符串或数值参数时，SQL 里的布尔比较不会成立，因此设计器只允许绑布尔值参数。

搜索选择

适合医生、药品、患者等数据量大的字典：点开弹窗，输入关键字搜索，在分页表格中勾选记录，并可把整行的其他字段带回别的参数。

可绑定的参数类型随选择模式变化：单选绑字符串或数值；多选且值类型为数组时只能绑集合；多选且值类型为字符串时只能绑字符串。多选数组配合集合参数时，SQL 里写 IN (${$参数名})，占位符会按选中的个数展开。

选择模式为多选时，字段映射的结果跟随值类型：数组模式写回数组，字符串模式按分隔符拼接。

弹窗中的操作：输入关键字后按回车或点「搜索」；单选时点击一行后点「确定」；多选时勾选多行，可点「清空已选」，再点「确定」。

查询按钮与重置按钮

两个按钮没有可配置的属性，按钮文字固定为「查询」「重置」，行为见 查询表单概述。

示例

用日期范围控件做「近 12 个月各科室收入」的筛选：

1. 「查询参数设置」中添加两个字符串参数 p_start、p_end。
2. 「查询表单设计」中添加「日期范围」控件，「绑定参数」选 p_start，「止参数」选 p_end，「粒度」选「按月」，「默认区间」保持「近 12 个月」，「最长跨度」填 24。
3. 新建 SQL 数据集，数据源选 demo（系统初始化时自动导入演示数据所用的数据源，本例要求演示数据已导入），SQL 使用 demo_销售订单 表的 年月 列（格式 yyyy-MM 的文本，演示数据内置）：

SELECT 所在大区, SUM(订单金额) AS 金额
FROM demo_销售订单
WHERE 年月 BETWEEN ${$p_start} AND ${$p_end}
GROUP BY 所在大区

4. 保存并预览。打开报表即按默认区间查询；改选区间超过 24 个月时，点击「查询」被拦截，提示「日期范围最长 24 个月」（提示中的名称取控件的「组件标签」）。

提示：演示表 demo_销售订单 的数据范围为 2023 至 2025 年，默认区间「近 12 个月」以当前系统日期计算，可能落在数据范围之外；此时改选 2024 年内的月份即可看到数据。

注意事项

注意：控件类型与参数类型不兼容时无法保存。例如日期范围只能绑字符串参数，因为月份没有对应的日期形态。

注意：搜索选择的「值字段」未选时，弹窗查不到任何记录；设计器只给出提示，不会阻止保存。

注意：多选值绑定字符串参数时以逗号拼接，值本身含逗号会被拆开。需要精确传值时绑集合参数。

相关文档

• 查询表单概述
• 下拉选项来源与联动
• 参数类型、默认值与传参
• SQL 参数与动态语法
• 数据集