日期控件与时间范围筛选

在报表中添加“时间选择器”，可以让查看人员在发布后的页面选择日期或时间范围，并刷新关联图表。设计人员负责配置输出格式、查询参数和联动关系；查看人员只需要选择日期。

配置顺序：定义开始、结束参数 → 生成查询密文 → 配置图表或公共数据池 → 添加时间选择器 → 设置输出格式 → 绑定参数 → 保存并预览。

本页适用于已提供“时间配置 → 联动输出格式”的 GoView 版本。看不到该选项时，请先由维护人员确认前端版本；旧版本日期控件默认输出毫秒时间戳。

选择日期来源

需求	配置方式	时间计算位置
查看人员自行选择起止时间	时间选择器联动两个 CLIENT 参数	GoView 将选择结果传给后台
打开页面时默认选中最近一段时间，之后允许修改	时间选择器的“动态”默认值，并联动 CLIENT 参数	按打开页面时的浏览器时间加减偏移量
报表始终查询今天、本月，无需用户选择	模板使用 SERVER_DATE 参数	每次查询由后台按指定时区计算

控件的“动态默认值”与模板的 SERVER_DATE 是两种机制。 动态默认值不会因为图表定时刷新就持续滚动；SERVER_DATE 每次查询重新计算，不能由前端选择结果覆盖。服务器日期的设置见服务器日期参数。

准备范围查询

以下以 MySQL 的日期时间字段为例。example_order、create_time 是示例名称，请替换为实际表、字段，并先在数据源“查询数据”中调试。

SELECT COUNT(*) AS order_count
FROM example_order
WHERE create_time >= :startTime
  AND create_time < :endTime

在查询调试和生成密文时使用一致的参数定义：

参数名	类型	值来源	必填	用途
startTime	DATETIME	CLIENT	是	包含此时刻的开始边界
endTime	DATETIME	CLIENT	是	不包含此时刻的结束边界

本次动态参数示例：

[
  {"name":"startTime","value":"2026-09-01T00:00:00"},
  {"name":"endTime","value":"2026-09-19T00:00:00"}
]

这组条件覆盖 9 月 1 日至 18 日全天。结束条件是“小于 19 日零点”，不需要用 23:59:59 猜测数据库的时间精度。

调试完成后，按生成查询密文取得完整 RQ2. 密文。GoView 图表选择对应数据源，粘贴密文，并填写上述动态参数 JSON，具体入口见配置报表数据查询。

GoView 报表查询中的开始与结束动态参数

图中仅展示参数填写位置，查询密文特意留空。实际查询必须先粘贴对应数据源的有效密文，再点击“保存 & 发送请求”；不能直接用截图中的空密文发送。

仅更换开始、结束参数的实际值，不需要重新生成密文；改变参数名、类型、值来源或查询模板时需要重新生成。

添加时间选择器

在 GoView 设计器组件面板中找到“时间选择器”，添加到画布。
选中控件，在右侧“时间配置 → 基础 → 类型”中选择“日期范围”或“日期时间范围”。需要选择到时、分、秒时使用“日期时间范围”。
在“默认值”中选择静态、动态或无。静态填写固定日期；动态分别设置开始、结束的偏移量和单位；无表示初始没有选定日期。
在“联动输出格式”中选择与查询参数类型一致的格式。上例选择“日期时间（带 T，DATETIME）”。
核对“输出示例”，再配置联动关系。

日期时间范围及带 T 的 DATETIME 输出配置

右侧“输出示例”显示实际传出的 dateStart、dateEnd。控件显示的日期可以带空格，而发送值按所选输出格式带 T；这两个位置的显示格式不必相同。

动态默认值按浏览器本地时间计算。例如“日期范围”开始偏移 -6 天、结束偏移 1 天，配合前面的左闭右开查询，可表示包含今天的最近 7 个自然日；控件会将日期范围的动态默认值取到对应日期零点。月份、季度、年份类型使用相应周期起点。

日期选择器内部一直使用毫秒时间戳；输出格式只决定发送给关联参数的值。格式化跟随浏览器时区，不会自动换算成后台时区。跨时区使用报表时，需与维护人员确认数据库的时间约定。

设置输出格式

选项	输出示例	输出值类型	报表参数类型
毫秒时间戳（默认）	所选时刻的毫秒数	数字	LONG；字段或模板也须按毫秒处理
日期时间	`2026-09-19 23:33:01`	字符串	通常为 STRING
日期时间（带 T）	`2026-09-19T23:33:01`	字符串	DATETIME
日期	`2026-09-19`	字符串	DATE
自定义格式	按输入格式生成	字符串	按实际格式匹配，通常为 STRING

带空格的日期时间不能直接作为 DATETIME 参数。 当前后台的 DATETIME 要求 2026-09-19T23:33:01 这种带 T 的字符串。前端无法从密文判断参数类型，也不会替用户修改模板定义。

如果 ES 日期字段实际存储的是 2026-09-19 23:33:01 这类字符串，可以按查询方式和字段映射选用 STRING 参数及“日期时间”输出；不能只根据字段名称判断类型。详见ES 查询说明。

自定义格式

选择“自定义格式”，输入格式表达式，例如：

自定义格式输入框、标记说明与实时输出示例

格式表达式	输出示例
`YYYY-MM-DD HH:mm:ss`	`2026-09-19 23:33:01`
`YYYY/MM/DD`	`2026/09/19`
`YYYYMMDD`	`20260919`
`YYYY-MM-DD[T]HH:mm:ss`	`2026-09-19T23:33:01`
`YYYY-MM-DD HH:mm:ss.SSS`	`2026-09-19 23:33:01.123`

控件使用 Day.js 的格式标记：YYYY 年、MM 月、DD 日、HH 24 小时、mm 分钟、ss 秒、SSS 毫秒。月份 MM 与分钟 mm 不同，年份请用大写 YYYY。 普通字母作为固定文本时放在 [...] 中。

支持的完整标记为 YY YYYY M MM MMM MMMM D DD d dd ddd dddd H HH h hh m mm s ss SSS Z ZZ A a。格式不能为空、最长 128 个字符，不支持 JavaScript 或插件扩展标记。主后台 SERVER_DATE 的格式选项与这里的自定义表达式不同，不要把 Java 的 yyyy-MM-dd 原样复制到控件中。

输入错误时，配置面板显示原因，日期控件显示错误状态并提供悬停提示；修正前不发送新的日期联动值。目标图表原有参数和定时刷新不会因此自动清空或停止。

绑定图表或公共数据池

选中时间选择器，进入右侧事件设置，展开“组件交互”，点击“新增”。
触发事件选择“选择完成”。
绑定目标选择需要刷新的图表，或选择对应公共数据池。
在“关联目标请求参数 → Params”中完成下表绑定。

目标查询参数	选择的控件输出	含义
startTime	dateStart（开始时间）	按所选格式输出开始值
endTime	dateEnd（结束时间）	按相同格式输出结束值

选择完成事件及 startTime、endTime 参数绑定

下拉列表使用“开始时间”“结束时间”等中文说明，分别对应上方输出表中的 dateStart、dateEnd。图中柱状图为组件自带演示数据，仅演示配置位置，不表示日期查询已成功执行。

报表查询的可绑定名称来自目标配置中的“动态参数 JSON”，不需要先切换到普通请求中创建 Params。若显示“暂无数据”，先检查目标是否已配置报表查询、参数 JSON 是否有效，以及 startTime、endTime 是否已经填写。

单日期控件只有 date 输出，绑定到模板相应的单日期参数。范围查询使用 dateStart、dateEnd 两个独立值；daterange 是兼容旧设计的“开始毫秒数-结束毫秒数”字符串，后台不会自动将它拆成两个日期。

多个图表共用公共数据池时，将时间选择器绑定到该数据池即可让使用其结果的图表一起更新。各图表仍需配置自己的数据映射，见数据映射与公共数据池。

保存与发布后使用

点击设计器顶部“保存”，保留控件、输出格式、查询和联动设置。
从顶部“预览”进入页面，选择一组时间，核对图表刷新和筛选结果。设计画布内选择日期不会直接执行组件联动。
再选择另一组范围，确认数据随选择变化；使用独立图表或公共数据池时分别检查实际目标。
重新打开设计器，确认输出格式和参数绑定仍然存在。
核对访问角色后发布，查看人员从已发布页面选择日期。发布步骤见查看与发布。

结束边界始终按所选值传入，控件不会自动改成当天末尾或次日零点。清空后传 null；如果模板参数必填，后台可能拒绝查询，不会自动改查今天或全部数据。

旧设计兼容

升级前创建的时间选择器没有输出格式设置时，继续输出毫秒时间戳；无需为了本次格式功能批量迁移旧项目。旧控件的参数名、联动绑定及 daterange 毫秒拼接方式保留。

切换输出格式不会改变已选中的时刻，也不会重新计算动态默认日期。只有设计人员主动选择字符串格式后，date 或 dateStart、dateEnd 的值类型才随之变化，应同时核对原有目标接口或模板能否接收。

这里的兼容指日期控件与联动设置；先前已停用的旧数据库查询协议仍按旧查询配置处理人工迁移，不能与本次日期格式升级混为一谈。

选择日期来源​

准备范围查询​

添加时间选择器​

设置输出格式​

自定义格式​

绑定图表或公共数据池​

保存与发布后使用​

旧设计兼容​