深色模式
常见问题
按症状找。每条都是「看到什么 → 为什么 → 怎么办」。
页面上写着「这张报表还没有发布」
链接指向的是已发布版,这张报表只有草稿。
处理: 打开报表,点右上角「发布」,再回来打开这个链接。只是想在发布前自己看一眼,用 &version=draft。
iframe 一片空白
按顺序排查:
- 混合内容:宿主是
https://、报表地址是http://,浏览器直接拦掉。两边都上 HTTPS。 - 被 frame-ancestors 挡了:报表服务配了
embed.allowedOrigins但没包含你们的域名。浏览器控制台会写明拒绝原因。处理:把宿主域名加进去重启报表服务。 - 不在授权域名里(SaaS 镜像部署):宿主站点或报表服务的域名不在授权里。直接在浏览器打开报表地址,页面会写明授权给谁、能用哪些域名。处理:换用授权域名,或找供应商换授权。
- 被 X-Frame-Options 挡了:反向代理往回加了这个头。报表服务自己不发,去代理上关掉。
sandbox属性太紧:加了sandbox就得带allow-scripts allow-same-origin,否则页面里的脚本跑不起来。- 报表 id 写错:直接在浏览器里打开那条链接,页面会写明是报表不存在还是版本不存在。
链接里的筛选条件没生效
页面顶上有没有一条提示,写着某个参数名不是这张报表的筛选条件?有就是 id 拼错了,核对报表筛选栏里的条件 id。
没有提示但值不对,看链接参数里各类型的写法:区间要写 起,止,多选用逗号分隔,值要 URL 编码。
iframe 里出现了第二条滚动条
宿主没有按报表报上来的高度调 iframe。监听 height 消息,见五分钟接入第四步。
高度消息收不到
- iframe 还没加载完:等
ready之后再做事。 e.origin判断写错:报表服务的 origin 要写成https://report.example.com这种不带路径的形式。- 页面根本没嵌在 iframe 里:直接打开查看页时不会发消息,只有被嵌时才发。
发了 setParams 没反应
- 发早了。
ready到了再发,或者把消息排队,等ready后补发。 source写错了。宿主发的必须是{ source: 'conch-report-host', … }。targetOrigin写错了。postMessage(msg, 'https://report.example.com')里的 origin 必须和 iframe 的 origin 一致。- 条件被锁了。
lock里的条件、以及数据快照版的全部条件,都不接受修改。
报表内容改了,页面上还是旧的
链接跟的是当前发布版,改完草稿要重新发布。链接上钉了 &version=v2 的话,发布多少次都不会变——这是钉版本的用途。
数字对不上
先确认两边口径一致:链接里的条件和你们系统里那个报表页的条件是不是同一组值(月份是不是同一个月、门店是不是同一批)。
口径一致还对不上,让做报表的人在报表里点「发布」前的检查,或在对话里直接问「这个数怎么算出来的」——报表服务会把口径说清楚。宿主侧改不了算法。
导出按钮不见了
三种可能:
- 用了
&chrome=0,页头连同导出一起去掉了。宿主自己做按钮,调导出接口。 - 报表规格里关掉了导出格式。
- 当前在数据快照版且规格关掉了导出。
小程序 web-view 里能嵌吗
能,但只能用链接参数:小程序的 web-view 收不到也发不出 postMessage,高度也不能自适应(web-view 默认铺满整屏)。条件要变就换 src。域名要先在小程序后台配成业务域名。
能不能不用 iframe
能,用自定义元素:引一个脚本、写一个 <conch-report> 标签,报表直接画在你们页面里。能力跟 iframe 那种完全一样,参数名也一一对应。
如果你问的是「不嵌任何东西、直接拿数据自己画」——也能,调取数接口拿 columns / rows 自己渲染。代价是筛选栏、穿透明细、导出、图表配色这些都要自己实现一遍,而且报表改版时你们的页面不会跟着变。先用现成的两种嵌法,确有必要再自己画。
一个页面能嵌几张报表
没有限制,两种形态都是各自独立取数。
- iframe:一张报表一个 iframe。监听消息时用
e.source === frame.contentWindow区分是哪一个发来的。 - 自定义元素:一张报表一个标签,每个元素自己一份状态,条件互不影响;运行时整页只加载一份,比多个 iframe 轻。
页面上同时放四五张以上时,注意它们会同时向数据库发查询,留意库的压力。
报表服务挂了页面会怎样
iframe 里显示浏览器自己的错误页或一句打不开。宿主可以在 ready 上做超时:10 秒没收到 ready 就在 iframe 上盖一层「报表暂时打不开」的提示,别让用户对着空白发呆。
筛选栏查询与重置
筛选栏提供“查询”和“重置”。默认先修改条件,再点击查询一次性应用;重置恢复参数默认值并刷新。宿主锁定的条件和数据快照不能被重置修改。未提交的条件不会影响导出,导出使用已应用的筛选值。
规格中 filter 节点支持 queryMode: "manual" | "auto",省略时为 manual;auto 保留条件变化后自动查询。现有报表同样显示查询/重置按钮。节点内局部筛选的行为保持不变。
日期快捷选项与分段筛选
参数设置 display: "datePresets"(仅 daterange)可显示今天、昨天、近7天、近1月、自定义。日期按浏览器本地日期计算,近7天包含今天,近1月为最近30天,区间两端均包含。display: "segments"(仅 select)显示可切换的胶囊按钮。
type: "multiselect" 配合 display: "tree" 可按分类展开后选择多个明细,选项查询需提供 source.parentField。分类仅展开,叶子可多选;选择分类不会自动勾选全部子项。参数值为叶子 ID 数组,SQL 用 (:items_empty = 1 OR item_id IN (:items)),空选表示不限。iframe 与 Web Component 使用相同控件和参数规则。
选项查询必须同时返回分类根节点(上级值为 NULL)与引用分类 ID 的明细节点,不能只给明细行填分类名称。服务端在生成及运行时检查父节点缺失、重复 ID、父子循环和截断结果;无效选项查询返回 error,不返回会被静默平铺的行。分组多选非空结果必须包含实际的父子关系;空结果允许没有选项。
设计器创建新报表时,会先展示拟采用的筛选和展示方案;点击“确认,按此方案生成”并继续后才接受生成结果。选择“需要调整方案”可继续描述修改。业务映射或口径不明确、需要更换用户要求的控件时,应先复核;元数据搜索无匹配仅表示当前可见范围未找到,不代表业务不存在。小幅样式修改无需重复确认。
选项数量来自 source.countField,全部数量来自 source.totalField(查询第一行),未配置或暂无结果不显示数量。数量查询仍走普通查询的权限与安全闸,需自行定义业务口径,不能根据截断明细推算。选项查询不能引用自身参数,其他条件查询后再刷新数量。
参数 layoutRow 从0开始,同号同行。新旧报表默认控件保持兼容;将已有报表改成快捷筛选需修改对应参数规格或在对话里要求修改。两行筛选区由布局归一化预留高度;窄屏可继续换行。
常用报表积木模板
图表可以用 template 选择 column、bar、line、area、pie、donut、scatter、stackedColumn、stackedArea、heatmap,绑定 xField/yField,堆叠另填 seriesField,热力图另填 valueField;不填spec时由模板展开并校验。日期xType用temporal,xLabel/yLabel设中文业务标签。已有spec优先保留,更换模板需要移除或重建旧spec。
文本variant提供plain/heading/note/info/success/warning/danger/divider。所有节点支持tooltip(问号浮层)、hint(灰字)及badge={text,tone},tone固定为neutral/info/success/warning/danger。属性面板可直接设置。文本只支持安全Markdown,不能执行HTML和脚本。
KPI支持unit与targetField;目标必须为正数。表格支持紧凑density、striped、rowNumbers,columns.display=badge配statuses状态映射,progress使用0~100百分数。导出保留标签及数值单位。现有报表兼容,新样式需选用模板或由对话修改配置。
如何分析高频报表?
正式查看加载完成后记录一次访问,预览与数据刷新不计数。管理员可调用 GET /api/usage/reports?days=7 或 days=30,获取当前租户及报表空间内的打开次数、使用人数和最近访问时间,结果按次数排序。两种嵌入形态一致;统计失败不阻塞查看,不记录业务明细或筛选条件。
表格能显示比例与悬停详情吗?
支持。比例列使用 display: ratio 与 denominatorField;结构化详情使用 detail.titleFields/descriptionField/itemsField,日期标签由查询返回JSON数组。summary.fields绑定完整筛选口径的汇总列,不对当前页求和;可选summary.titleField显示动态摘要。每类组件的选择示例已接入模型目录,规格与字段还会校验。浮层详情需要导出时,应另声明为表格列或使用穿透导出。
能维护生成报表的提示词吗?
管理员在「设置 → 提示词流程」维护需求拆解、数据源查找、可行性判断、询问与信息收集、生成、验证与自动修复六阶段指导词,可保存草稿、发布、并排对比历史与回退。按租户生效,所有文字模型共用;草稿不影响生成。六阶段共同注入现有设计代理,流程图不是六次独立模型调用或实时轨迹。SQL 安全、规格校验和数据隔离仍由程序控制。图片理解与审计提示词暂不在此页面维护。
