查询表单概述
查询表单是网格报表与单据模板预览页顶部的条件输入区，每个控件绑定一个报表参数；本文介绍设计入口、画布操作、查询与重置行为和表单校验规则。
概述
查询表单是报表预览页顶部的条件输入区。设计者在「查询表单设计」对话框里把控件（输入框、下拉框、日期框等）摆在画布上，并把每个控件绑定到一个报表参数；使用者在预览页填写条件、点击「查询」后，控件的值作为参数值提交给服务端，数据集 SQL、单元格表达式和过滤条件再按参数取数。
查询表单只是参数的输入界面，参数本身（名称、类型、默认值）在「查询参数设置」里定义。没有绑定控件的参数照样可用，取值来自默认值、URL 传参或预览时的「参数调试」抽屉，见 参数类型、默认值与传参。
适用范围：网格报表（.mrg）和单据模板。仪表盘不使用这套查询表单，设计器顶栏也没有「查询表单设计」按钮，仪表盘用自带的过滤栏。
功能入口
- 设计器顶栏左侧「查询参数设置」：打开「报表参数配置」对话框，先在这里定义参数。
- 设计器顶栏左侧「查询表单设计」：打开「查询表单设计」对话框（宽 1200px，可全屏），在这里摆控件。
- 设计器右上角「预览」：在新标签页打开预览页，查看查询表单在使用者眼里的样子。
操作步骤
定义参数并放置控件
- 点击「查询参数设置」，在「报表参数配置」对话框中点「添加参数」，填写「参数名称」，选择「参数类型」，按需设置默认值，点「确定」。
- 点击「查询表单设计」。对话框顶部是组件库工具栏，中间是画布，右侧是「组件属性」面板。
- 点击工具栏上的控件名称，或把控件拖到画布上，控件被添加到画布。新添加的控件处于「未绑定」状态，工具栏右侧的红色标签会显示「N个未绑定」。
- 选中控件，在右侧「组件属性」的「基本信息」里填写「组件标签」，在「绑定参数」下拉里选择参数。下拉里只列出类型兼容的参数，没有兼容参数时会提示「没有兼容的参数，支持类型：…」，各控件支持的参数类型见 查询表单控件。
- 在「组件属性」「样式配置」「位置信息」中调整其他属性。
- 需要「查询」「重置」按钮时，从组件库添加「查询按钮」「重置按钮」两个控件。
- 点击对话框底部「确定」，配置写回报表；最后在设计器顶栏「保存」。
如果确定时仍有控件未绑定参数，设计器会询问「组件"…"未绑定参数，是否继续保存？」。如果控件与所绑参数的类型不兼容，会提示「组件"…"的类型与绑定参数类型不匹配」并阻止确定。
用参数快速生成控件，或用控件快速生成参数
- 已经定义了参数、还没有控件：点画布工具栏「生成组件」，为所有尚未绑定控件的参数按参数类型各生成一个控件。
- 已经摆好了控件、还没有参数：点「生成参数」，为所有未绑定参数的控件按控件类型创建同名参数并完成绑定。新参数的名称取自控件标签，重名时追加
_1、_2。
画布工具栏
| 按钮 | 作用 |
|---|---|
| 排列 | 自动排列画布上的全部控件 |
| 预览 | 打开「查询界面预览」对话框，可点「验证表单」检查输入 |
| 复制 / 粘贴 | 复制、粘贴选中的控件，快捷键 Ctrl+C、Ctrl+V |
| 保存模板 | 把当前控件保存为查询表单模板，可选择包含哪些控件，填写模板名称和描述 |
| 导入模板 | 从已保存的模板导入控件，导入模式为「追加到现有组件后」或「替换所有现有组件」 |
| 生成组件 | 根据参数自动生成控件 |
| 生成参数 | 根据控件自动生成参数 |
| 校验规则 | 配置表单级跨字段校验，见下文 |
控件位置由「位置信息」中的 X 坐标、Y 坐标、宽度、高度（单位 px）决定；拖动控件时画布提供对齐辅助线，并在 3px 范围内自动吸附。预览页按设计时的坐标绝对定位摆放控件，不会自动换行。
使用者看到的行为
| 操作 | 行为 |
|---|---|
| 点击「查询」按钮 | 先检查必填控件，未填时弹出「请填写必填项」，列出未填控件的名称，不发起查询；再检查表单校验规则；通过后取数并刷新报表 |
| 点击「重置」按钮 | 清空所有控件的值（值为数组的控件回到空数组，其余置为未填），并直接重新查询；重置不做必填检查。未填的参数由服务端按参数默认值补齐，而数组值（如多选）以空数组提交，不会回到默认值；重置后控件本身显示为空，不会回填默认值 |
| 预览页工具栏「查询」按钮 | 用当前控件的值重新取数，效果与「查询」按钮控件一致 |
| 点击查询区下方的收缩按钮 | 收起或展开查询区，提示文字为「收起查询」「展开查询」 |
需要强调的两点：
- 控件的「是否必填」只在点击「查询」时检查，检查结果用弹窗展示，不会在控件旁显示红字。
- 首次打开预览页是否自动取数，由报表设置中的「打开报表自动查询」决定，也可以被 URL 参数
search覆盖，见 报表预览。
表单校验规则
「校验规则」用于需要同时读取多个参数才能判断的规则。点击画布工具栏「校验规则」打开「表单校验规则」对话框，点添加后可配置「日期区间」规则。
| 属性 | 说明 | 取值/默认值 |
|---|---|---|
| 开始字段 | 开始日期所绑定的参数 | 必选；候选项来自类型为「日期框」的控件已绑定的参数 |
| 结束字段 | 结束日期所绑定的参数 | 必选；不能与开始字段相同 |
| 提示文案 | 校验不通过时的提示 | 默认「开始时间不能晚于结束时间」 |
规则在点击「查询」时执行：开始晚于结束时拦截查询，报表区域显示「查询失败」和提示文案。任一端为空时不拦截，是否必填交给控件自己的「是否必填」。日期比较按本地时间进行，日期与日期时间可以混合比较。
提示：「日期范围」控件自带起止顺序保证，另有「最长跨度」属性，不需要这条规则，见 查询表单控件。
示例
为一张按日期区间和科室过滤的报表配置查询表单。
- 「查询参数设置」中添加三个参数：
startDate（日期）、endDate（日期）、dept（字符串）。 - 数据集 SQL 写为：
SELECT dept, SUM(amount) AS amount
FROM sales
WHERE order_date BETWEEN $startDate AND $endDate
AND dept = $dept
GROUP BY dept
- 「查询表单设计」中添加两个「日期框」，分别绑定
startDate、endDate；添加一个「输入框」绑定dept；再添加「查询按钮」「重置按钮」。 - 点「校验规则」，添加一条日期区间规则，开始字段选
startDate，结束字段选endDate。 - 确定、保存，点「预览」。把开始日期选得比结束日期晚，点「查询」，报表区域显示「查询失败：开始时间不能晚于结束时间」。
注意事项
注意：控件绑定的参数类型必须在兼容列表内，例如「开关」只能绑布尔类型参数，「日期范围」只能绑字符串类型参数。类型对应表见 查询表单控件。
注意：控件的取值键是所绑参数的名称；没有绑定参数的控件以控件 ID 作键，其值不会对应到任何报表参数。
提示：一个参数应只被一个控件绑定。同一参数绑定多个控件时，它们共用同一个值。
