报表预览与查看参数
说明设计器预览与报表查看页的工具栏、查询流程，以及通过 URL 传参、隐藏工具栏、指定分页方式和调试参数的方法。
概述
报表设计完成后，通过预览页检查数据、查询表单和版式。同一个页面组件还用于正式的报表查看：设计器预览地址为 /report-preview/<报表ID>，查看地址为 /report-view/<报表ID>。两者的区别是，预览页读取报表的草稿版本，并在设计器打开时带上参数调试入口；查看页读取已发布版本。
预览页与查看页都支持通过地址栏参数控制查询条件、工具栏和展示方式，便于把报表嵌入其他系统或分享带条件的链接。
功能入口
- 设计器顶栏「预览」：在新标签页打开
/report-preview/<报表ID>?paramDebug=1。 - 设计器内有未保存的更改时，点击「预览」会弹出提示框「检测到报表有未保存的更改，需要先保存才能预览。是否立即保存？」，按钮为「保存并预览」和「取消」。
- 报表查看：
/report-view/<报表ID>，需要先发布报表。 - 正式包使用 hash 路由，地址形如
/#/report-view/<报表ID>?...，参数写在#之后的查询串中，查看页会按此方式读取。
工具栏
工具栏从左到右依次为下列控件，是否显示由报表设置和报表类型决定。
| 控件 | 说明 | 显示条件 |
|---|---|---|
| 「打印」 | 下拉菜单：「打印预览 (全部页)」「打印预览 (当前页)」「插件打印 (全部页)」「插件打印 (当前页)」 | 报表设置中「打印按钮」未关闭；不是数据浏览报表；「当前页」两项仅在分页查看时出现 |
| 「续打」 | 打开续打对话框 | 仅主分行格配置了续打字段的单据报表 |
| 「导出」 | 下拉菜单：「导出Excel」「导出Word」「导出PDF」「导出CSV」「导出OFD」 | 报表设置中「导出按钮」未关闭 |
| 「分页」/「全部」 | 切换分页查看与全部显示 | 连续纸报表不显示；报表不允许查看全部时只有「分页」 |
| 「数据浏览报表」标签 | 提示当前为数据浏览报表 | 报表设置中开启「数据浏览报表」 |
| 「查询」 | 按当前查询条件重新取数 | 始终显示 |
| 页码 | 分页查看且总页数大于 1 时显示 | 分页查看 |
| 「列」 | 临时隐藏明细列，不改模板、不影响导出 | 数据浏览报表且列数大于 1 |
多个工作表的报表，导出菜单会标注范围，例如「导出Excel (全部Sheet)」「导出CSV (当前Sheet)」，并追加「导出Excel (仅当前Sheet)」等三项。数据浏览报表的导出菜单只有「导出明细Excel」。单据类报表只有 Word 和 PDF 两种导出。
工具栏右侧的计时图标点击后显示「时间耗费统计」。导出与打印的详细说明见导出与打印。
查询流程
- 打开预览页或查看页时，是否立即出数由报表设置「打开报表自动查询」决定：选「是」（默认）时打开即取数；选「否」时页面先显示「输入查询条件后查询」，等待点击「查询」。
- 有查询表单时，查询表单显示在报表内容上方。填写条件后点击表单中的「查询」，或点击工具栏「查询」。
- 查询后按分页设置显示第一页。分页查看时使用页码切换页；切换到「全部」则一次显示全部内容。
报表设置中的「默认查看方式」有「分页查看」和「全部」两个取值，决定打开时的初始方式。URL 参数 viewMode 指定后，以 URL 为准。
URL 参数
以下参数写在地址的查询串中。
| 参数 | 说明 | 取值/默认值 |
|---|---|---|
parameters |
报表参数，值为 JSON 对象，键为参数名 | 例如 {"regions":["华东","华南"],"asOf":"2026-06-30"}，需 URL 编码；无默认值 |
showQueryForm |
是否显示查询表单 | 值为 false 时隐藏；其他情况显示 |
hideToolbar |
是否隐藏工具栏 | true 隐藏；未传时取报表设置中「工具栏」的配置 |
search |
打开时是否立即取数，覆盖「打开报表自动查询」 | true 或 false；未传时按报表设置 |
viewMode |
初始查看方式 | pagination（分页）或 all（全部） |
sheet |
多工作表报表打开时定位的工作表 | 工作表 ID |
showSheetTabs |
是否显示工作表页签 | 值为 false 时隐藏；默认显示；仅多工作表时才有页签 |
paramDebug |
显示参数调试入口 | 1 或 true；设计器预览自动携带 |
parameters 中各类型参数的写法：
- 字符串、数值、布尔值直接使用 JSON 对应类型。
- 日期参数使用
yyyy-MM-dd字符串，日期时间参数使用yyyy-MM-dd HH:mm:ss字符串。 - 集合（List）参数使用 JSON 数组，如
["华东","华南"]。集合参数的类型与在 SQL 中的用法见参数类型、默认值与传参。
工具栏或表单中修改条件后再点击「查询」，提交的是表单当前值；首次取数使用的是 URL 中的 parameters。
参数调试
设计器预览页带有 paramDebug=1。只要报表定义了参数，页面右侧就会出现悬浮标签「参数调试」，点击后打开右侧抽屉，标题为「参数调试」，并带有标签「仅预览可见」。
抽屉说明为：为报表参数临时赋值并重新出数。留空即使用服务端默认值。
| 区域/按钮 | 说明 |
|---|---|
| 「未在查询面板」 | 列出没有绑定到查询表单控件的参数，置顶显示，并标注参数类型；默认值由服务端计算的参数标注「默认由服务端计算」 |
| 「查询面板参数（可覆盖）」 | 可折叠，列出已有控件的参数，可临时覆盖 |
| 「重置为默认」 | 清空抽屉中的临时值 |
| 「重新出数」 | 用抽屉中的值重新查询 |
各类型参数的输入方式：Number 使用数字输入框；Boolean 使用 true/false 下拉；Date、DateTime 使用日期选择器；List 使用文本框，用逗号分隔（支持中英文逗号和顿号）；其他类型使用文本框。元素类型为数值的 List 参数中出现非数字项时，抽屉会提示该项不是数字，查询会失败。
普通的发布链接不带 paramDebug，终端用户看不到该入口。
示例
在设计器中预览一张带查询表单的报表，并用链接传入条件。
- 打开示例报表「员工档案表」（随产品分发的示例报表，源文件目录为
demo/reports/综合报表，初始化后按名称查找）。 - 点击顶栏「预览」，在新标签页中查看报表和查询表单。
- 「员工档案表」定义了一个 String 参数
id，查询表单中是标签为「档案编号」的输入框。在输入框中填写一个档案编号后点击「查询」，观察报表内容变化。 - 若要分享带条件的链接，用报表实际 ID 拼出地址：
/report-view/<报表ID>?hideToolbar=true&viewMode=all¶meters=%7B%22id%22%3A%22<档案编号>%22%7D。其中parameters解码后为{"id":"<档案编号>"}，<档案编号>替换为数据中实际存在的编号。 - 预期结果：页面无工具栏，以「全部」方式显示，并按传入的档案编号取数。
注意：
parameters的 JSON 必须先做 URL 编码，否则含中文、引号和&的值会被截断。
注意事项
注意：预览页读取草稿版本，查看页读取发布版本；修改后未发布时，查看页看不到改动。
注意：
showQueryForm=false只隐藏表单，不影响通过parameters传入条件。
提示：
hideToolbar未在 URL 中传入时，是否显示工具栏由报表设置「工具栏」决定。
提示：数据大屏模式下工具栏与查询表单恒隐藏，详见大屏概述与设计器界面。
