常见问题

按症状找。每条都是「看到什么 → 为什么 → 怎么办」。

页面上写着「这张报表还没有发布」

链接指向的是已发布版，这张报表只有草稿。

处理： 打开报表，点右上角「发布」，再回来打开这个链接。只是想在发布前自己看一眼，用 &version=draft。

iframe 一片空白

按顺序排查：

1. 混合内容：宿主是 https://、报表地址是 http://，浏览器直接拦掉。两边都上 HTTPS。
2. 被 frame-ancestors 挡了：报表服务配了 embed.allowedOrigins 但没包含你们的域名。浏览器控制台会写明拒绝原因。处理：把宿主域名加进去重启报表服务。
3. 被 X-Frame-Options 挡了：反向代理往回加了这个头。报表服务自己不发，去代理上关掉。
4. sandbox 属性太紧：加了 sandbox 就得带 allow-scripts allow-same-origin，否则页面里的脚本跑不起来。
5. 报表 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 的话，发布多少次都不会变——这是钉版本的用途。

数字对不上

先确认两边口径一致：链接里的条件和你们系统里那个报表页的条件是不是同一组值（月份是不是同一个月、门店是不是同一批）。

口径一致还对不上，让做报表的人在报表里点「发布」前的检查，或在对话里直接问「这个数怎么算出来的」——报表服务会把口径说清楚。宿主侧改不了算法。

导出按钮不见了

三种可能：

1. 用了 &chrome=0，页头连同导出一起去掉了。宿主自己做按钮，调导出接口。
2. 报表规格里关掉了导出格式。
3. 当前在数据快照版且规格关掉了导出。

小程序 web-view 里能嵌吗

能，但只能用链接参数：小程序的 web-view 收不到也发不出 postMessage，高度也不能自适应（web-view 默认铺满整屏）。条件要变就换 src。域名要先在小程序后台配成业务域名。

能不能不用 iframe，直接拿数据自己画

能，调取数接口拿 columns / rows 自己渲染。代价是筛选栏、穿透明细、导出、图表配色这些都要自己实现一遍，而且报表改版时你们的页面不会跟着变。先用 iframe，确有必要再自己画。

一个页面能嵌几张报表

没有限制。每张报表一个 iframe，各自独立取数。宿主监听消息时用 e.source === frame.contentWindow 区分是哪一个发来的。

页面上同时放四五张以上时，注意它们会同时向数据库发查询，留意库的压力。

报表服务挂了页面会怎样

iframe 里显示浏览器自己的错误页或一句打不开。宿主可以在 ready 上做超时：10 秒没收到 ready 就在 iframe 上盖一层「报表暂时打不开」的提示，别让用户对着空白发呆。