参数报表快速入门
以示例模板「参数报表」（报表 id=369）为主线：定义模版参数 area、SQL 过滤、参数面板下拉与查询按钮、数据字典与 URL 传参。操作以 VeryReport 复杂报表设计器为准。
本文以系统示例模板「参数报表」（报表 id=369）为主线，演示预览页通过下拉框切换销售区域、点击查询刷新明细与汇总。若您已安装该示例，可在 数据应用 → 报表 中搜索「参数报表」打开设计器对照学习；也可按下列步骤从零搭建同等能力。
若尚未熟悉复杂报表基础操作，请先阅读普通报表快速入门。
1. 概述
1.1 预期效果
预览页顶部出现参数面板：左侧标签「区域」、中间下拉框（华东 / 中南 / 西南 / 华北 / 西北）、右侧「查询」「重置」按钮。选择「西南」并点击查询后，报表主体仅展示西南区域的销售员、品类与销量数据；标题可随参数动态变化（如 $area + "区域销售"）。
1.2 参数的两类来源
VeryReport 将参数分为数据集参数与模版参数，二者共用同一命名空间（同名只保留一条绑定项）：
| 类型 | 定义方式 | 典型用途 |
|---|---|---|
| 数据集参数 | 在数据集 SQL / API 中写 ${参数名}，保存后自动识别 | SQL 层过滤，如 WHERE area = '${area}' |
| 模版参数 | 设计器 设置 → 模版参数 中显式新增 | 统一默认值、跨数据集共用、动态标题 $area |
推荐流程：先在数据集 SQL 中写${area}→ 在模版参数中声明同名area并设默认值 → 参数面板拖下拉框并绑定参数。绑定参数已改为分组下拉（模版参数 / 数据集参数），无需手输参数名。
1.3 实现思路
- 主数据集 SQL 使用
${area}过滤区域； - 模版参数
area设默认值（如「华北」）； - 参数面板：标签 + 下拉（绑定
area）+ 查询 / 重置； - 下拉数据字典配置选项（自定义、数据集或数据库表）；
- 预览时点击「查询」，引擎将参数值替换进 SQL 并重算报表。
2. 制作步骤
2.1 数据与模版参数
- 新建或打开复杂报表（.vrp）。在左侧 数据集 面板创建模板数据集
ds_sales，SQL 示例：
SELECT area, salesperson, category, amount
FROM sales
WHERE area = '${area}'保存后点击 SQL 编辑器下方 刷新参数，系统识别数据集参数 area。
- 点击 设置 → 模版参数 → 新增参数：
- 参数名：
area（与 SQL 占位符一致） - 数据类型：字符串
- 默认值：
华北
此时「绑定参数」下拉中会出现 area（模版 + 数据集） 合并项。
2.2 设计报表主体
- 合并标题行，插入动态标题公式：
$area + "区域销售"- 设计表头与数据行：将
ds_sales的字段（区域、销售员、品类、销量等）拖入对应单元格，按需设置纵向扩展与求和合计（参见普通报表快速入门）。
本示例采用 SQL 层过滤，一般无需再为扩展单元格单独配置数据过滤；若需在单元格层过滤，也可在单元格属性中添加条件「数据列 = 参数 $area」。
2.3 配置参数面板
切换到设计器顶部 参数面板 Tab，从工具栏拖拽控件：
| 控件 | 示例模板中的配置 |
|---|---|
| 标签 | 标签名称「区域」 |
| 下拉 | 绑定参数 area，数据字典提供选项 |
| 查询 | 收集面板参数并重算报表 |
| 重置 | 恢复控件默认值（可选） |
- 拖入标签，标签名称 设为「区域」。
- 拖入下拉控件，在右侧属性中：
- 绑定参数：从下拉选择
area（勿与显示标签「区域」混淆）； - 数据字典：点击「配置」打开弹框，任选一种类型：
| 字典类型 | 配置要点 |
|---|---|
| 自定义 | 录入实际值与显示值，如 华东、中南、西南、华北、西北（示例模板常用此方式） |
| 数据集 | 指定字典数据集，实际值 / 显示值选对应列；可另建 SELECT DISTINCT area FROM sales 专供选项 |
| 数据库表 | 选择数据源与表，映射实际值、显示值字段 |
- 拖入查询、重置按钮。
- 选中多个控件后，使用工具栏对齐（左对齐、顶对齐、等高、等宽、水平均分等），调整字号与背景色；设计态布局与预览尽量一致。
- 参数面板「基础设置」中可勾选「首次预览不计算报表」，用户须先选条件再点查询。
提示：修改下拉选项不会自动重算报表；须点击「查询」后，${area} 才会代入主数据集 SQL。
2.4 URL 传参与嵌入
发布后可带参打开预览，例如：
/#/report/complex/preview/page/369?name=参数报表&area=西南URL 中的 area 优先级高于面板默认值，打开时会灌入下拉框，保证所见与提交一致。
3. 效果预览
- 点击 保存，再 预览 → 分页预览。
- 参数面板默认显示「华北」（或模版 / 控件默认值），表格展示华北数据。
- 切换为「西南」，点击 查询，标题与明细同步刷新。
- 在地址栏追加
&area=华东重新打开，确认 URL 传参生效。 - 确认无误后 保存并发布，供门户、分享链接或开放 API 带参访问。
4. 参数优先级
4.1 运行时最终值
| 运行时参数值（高 → 低） | 说明 |
|---|---|
| URL 传参 | 预览链接 ?area=西南 等，优先级最高 |
| 参数面板控件当前值 | 用户选择或输入后，点击「查询」提交的值 |
| 模版参数默认值 | 设置 → 模版参数中的默认值 |
4.2 首屏默认值
| 首屏默认值（高 → 低） | 说明 |
|---|---|
| URL 传参 | 打开链接时灌入控件并参与合并 |
| 参数面板控件默认值 | 控件属性中的常量或表达式默认 |
| 模版参数默认值 | 模版参数对话框中的默认值 |
| 数据集参数默认值 | 数据集定义里该参数的 defValue |
空串约定：URL 带area=（空值）视为显式清空，可覆盖下级默认，便于「查全部」类场景；具体替换规则由引擎ParamsUtils执行。
5. 控件选项联动（进阶）
若需「区域 → 省份 → 城市」等级联下拉，无需公式：为下级控件配置数据集型数据字典，字典数据集 SQL 中写入上级占位符即可，例如：
SELECT DISTINCT province
FROM sales
WHERE area = '${area}'上级下拉变更时，系统自动刷新下级选项列表并清空下级已选值；不会因此重算整张报表，仍须点击「查询」。自定义 / 数据库表型字典不参与联动。
6. 常见问题
Q：选了区域但查询后数据未过滤？
A：检查 SQL 是否为 ${area}（与绑定参数名一致）、是否点击了「查询」、以及预览 URL 是否带了冲突的 area 参数。
Q：绑定参数下拉找不到 area？
A：确认 SQL 已保存并点击「刷新参数」，或已在模版参数中新增同名参数。
Q：下拉有选项但显示空白？
A：检查数据字典的实际值 / 显示值字段映射；自定义字典需成对填写。
Q：与「普通报表」示例有何区别？
A：普通报表快速入门侧重扩展与合计；本文侧重参数驱动查询。可先完成 普通报表 再叠加参数能力。
7. 相关文档
- 普通报表快速入门
- 复杂报表填报快速入门
- 帮助中心搜索「条件格式」「单元格过滤」等扩展主题
预览报错时，设计器会给出分类提示（参数未定义、表达式错误、数据连接失败等），请检查绑定参数名、SQL 占位符与数据字典配置是否一致。