# conch-report 接入文档（全站正文）

来源：https://report.doc.yijiangsoft.com
生成时间：2026-09-23

# 给 AI 的接入说明

这一页是写给**代码助手**的：把整页贴进上下文，或让它抓 `https://report.doc.yijiangsoft.com/md/ai.md`，它就能在宿主代码里把接入写对。内容自包含，不用再翻别的页面。

人也能读——只是密度高、没有铺垫。

> 纯文本索引：[`/llms.txt`](/llms.txt)　全站正文：[`/llms-full.txt`](/llms-full.txt)　本页原文：[`/md/ai.md`](https://report.doc.yijiangsoft.com/md/ai.md)

---

## TASK

把 conch-report 的**查看态页面**用 `<iframe>` 嵌进宿主系统的页面。宿主不引任何包、不改构建；所有输入通过 URL 查询串传入，运行期交互通过 `postMessage`。

## INPUTS（动手前必须确认，缺了就问人，不要编）

| 名称 | 例子 | 没有会怎样 |
|---|---|---|
| 报表服务地址 `ORIGIN` | `https://report.example.com` | 写不出 src |
| 报表 id `ID` | `r260922123456` | 写不出 src |
| 筛选条件 id 及取值来源 | `month` ← 页面上的月份选择器；`dept` ← 登录用户的科室 | 条件传不进去或拼错名字 |
| 哪些条件不让使用者改 | `dept` | 界面口径不对 |
| 要不要报表自带页头 | 宿主已有标题栏 → 不要 | 页面上出现两条标题栏 |

报表 id 从报表服务的报表列表页（每行的「嵌入」按钮）或 `GET /api/reports` 取。

## HARD RULES

1. **只嵌查看态**：`view=1` 必须有。少了它嵌进去的是设计器（带对话和属性面板），是错的。
2. **报表必须已发布**。没发布的报表打开只显示一句「还没有发布」；发布由做报表的人在报表服务里点，宿主侧做不了。
3. **不要在链接里放 token、密码、签名、SQL**。链接会进历史记录和 Referer。报表服务也不接受从客户端传 SQL。
4. **`lock` 不是权限**。它只把控件设成只读，改链接就能绕开。按身份限制数据必须在报表服务侧用行级范围参数做，不能靠 `lock` 交差；写代码时如果用户以为 `lock` 能限权，要明确告诉他不能。
5. **条件变化走 `postMessage`，不要重新拼 `src`**。换 `src` 会让 iframe 整页重载、图表重画一遍。首次挂载用 URL，之后用 `setParams`。
6. **`postMessage` 的 `targetOrigin` 写具体域名，不要 `'*'`**；接收侧校验 `e.origin` 和 `msg.source`。
7. **不要替用户猜条件 id**。猜错的表现是「页面上多一条提示、筛选没生效」，比报错更难被发现。

## URL CONTRACT

```
{ORIGIN}/?id={ID}&view=1[&<条件id>=<值>][&lock=…][&chrome=0][&version=…][&theme=…]
```

保留字段（其余 key 一律按报表筛选条件解析）：

| key | 值 | 含义 |
|---|---|---|
| `id` | 报表 id | 必填 |
| `view` | `1` | 必填，查看态 |
| `version` | `v3` / `draft` / 省略 | 省略=当前发布版；`draft` 仅供发布前自查，不要给客户 |
| `lock` | `a,b` 或 `all` | 这些条件只读 |
| `chrome` | `0` | 去掉报表页头（标题、版本、刷新、导出） |
| `theme` | `primary:%232c6ecb,bg:%23ffffff` | 覆盖设计令牌；名字省略 `--cr-` 前缀；**值里不能有逗号** |

条件值的写法（先 `encodeURIComponent`，用 `URLSearchParams` 就自动做了）：

| 条件类型 | 写法 | 例 |
|---|---|---|
| 文本 / 数字 / 日期 / 月份 / 单选 / 树 | `id=值` | `month=2026-08`、`day=2026-08-31`、`store=S001` |
| 日期区间 | `id=起,止` 或 `id_from=`/`id_to=` | `range=2026-01-01,2026-03-31` |
| 数字区间 | `id=小,大` 或 `id_min=`/`id_max=` | `amount=100,500` |
| 多选 | `id=a,b` 或重复 `id=a&id=b` | `store=S001,S002` |
| 不限（清掉报表默认值） | `id=`（空串） | `month=` |

链接上不写的条件 = 用报表自己的默认值。写了但报表里没有的 key 会被忽略，页面顶上列出来提示。

## POSTMESSAGE CONTRACT

报表 → 宿主，`{ source: 'conch-report', type, … }`：

| type | 附带字段 | 用途 |
|---|---|---|
| `ready` | `id`, `title`, `version` | 渲染完成；此前发给报表的消息会被丢掉 |
| `height` | `height`（px） | 内容高度变化；宿主据此调 iframe 高度，避免第二条滚动条 |
| `params` | `params`（全部条件的当前值） | 使用者或宿主改了条件 |

宿主 → 报表，`{ source: 'conch-report-host', type, … }`：

| type | 附带字段 | 用途 |
|---|---|---|
| `setParams` | `params`：条件 id → 值（只写要改的） | 改条件并重新取数 |
| `refresh` | — | 按当前条件重新取数 |
| `setTheme` | `tokens`：令牌名 → 值 | 换配色 |

`setParams` 的值用 JS 原生类型：区间 `['2026-01-01','2026-03-31']`、多选 `['S001','S002']`、不限 `null`。

## REFERENCE IMPLEMENTATION（框架无关，照这个结构写）

```js
function mountReport(container, { origin, id, params = {}, lock, chrome = true, version }) {
  const q = new URLSearchParams({ id, view: '1' })
  for (const [k, v] of Object.entries(params)) {
    if (v !== null && v !== undefined) q.set(k, Array.isArray(v) ? v.join(',') : String(v))
  }
  if (lock) q.set('lock', Array.isArray(lock) ? lock.join(',') : lock)
  if (chrome === false) q.set('chrome', '0')
  if (version) q.set('version', version)

  const frame = document.createElement('iframe')
  frame.src = `${origin}/?${q}`
  frame.style.cssText = 'width:100%;height:480px;border:0'
  container.appendChild(frame)

  let ready = false
  const queue = []
  const post = (msg) => {
    if (!ready) { queue.push(msg); return }            // ready 之前排队，别丢
    frame.contentWindow.postMessage({ source: 'conch-report-host', ...msg }, origin)
  }
  const onMessage = (e) => {
    if (e.origin !== origin || e.source !== frame.contentWindow) return
    const msg = e.data
    if (!msg || msg.source !== 'conch-report') return
    if (msg.type === 'height') frame.style.height = msg.height + 'px'
    if (msg.type === 'ready') { ready = true; queue.splice(0).forEach(post) }
  }
  window.addEventListener('message', onMessage)

  return {
    setParams: (p) => post({ type: 'setParams', params: p }),
    refresh: () => post({ type: 'refresh' }),
    setTheme: (t) => post({ type: 'setTheme', tokens: t }),
    destroy: () => { window.removeEventListener('message', onMessage); frame.remove() },
  }
}
```

Vue 3 / React 的成品组件见[宿主代码示例](/guide/examples)（原文 `/md/guide/examples.md`），结构与上面一致：`src` 只在挂载时算一次，条件变化 `watch`/`useEffect` 里发 `setParams`，`height` 存进组件状态。

## HTTP API（只有在不嵌 iframe、要自己画的时候才用）

| 方法 | 路径 | 请求体 | 回什么 |
|---|---|---|---|
| GET | `/api/reports` | — | 报表列表，`publishedVersion` 为 null 表示没发布 |
| GET | `/api/reports/{id}/view?version=` | — | 规格（**不含 SQL**）+ 初始条件 +（快照版的）数据；`409` = 没发布 |
| POST | `/api/reports/{id}/data` | `{version, params}` | `{queries:{<查询名>:{columns,columnTypes,rows,truncated,elapsedMs}}}`，单条失败带 `error` |
| POST | `/api/reports/{id}/drill` | `{version, drill, args, params}` | 穿透明细 |
| POST | `/api/reports/{id}/export/xlsx\|docx` | `{version, params[, drill, args]}` | 文件流 |
| GET | `/api/reports/{id}/versions` | — | 版本列表 |

错误统一 `{"error":"…"}`。多租户部署时租户来自请求头 `X-Conch-Tenant`，由反向代理注入，前端传不了。

## CHECKLIST（交付前逐条核对）

- [ ] `src` 里有 `id` 和 `view=1`
- [ ] 条件 id 是从报表里确认过的，不是猜的
- [ ] 条件值用 `URLSearchParams` 拼，没有手工字符串拼接
- [ ] 监听了 `height` 并调整 iframe 高度
- [ ] 校验了 `e.origin` 与 `msg.source`；`postMessage` 的 targetOrigin 不是 `'*'`
- [ ] `ready` 之前发的消息有排队补发
- [ ] 条件变化走 `setParams`，没有重拼 `src`
- [ ] 组件卸载时移除了 `message` 监听
- [ ] 宿主是 https 时报表地址也是 https
- [ ] 跟用户确认过：`lock` 不等于数据权限

## FAILURE MODES

| 现象 | 原因 | 处理 |
|---|---|---|
| 页面写「还没有发布」 | 报表只有草稿 | 让做报表的人发布；自查可用 `version=draft` |
| iframe 空白 | 混合内容 / `frame-ancestors` 不含宿主域名 / 代理加了 `X-Frame-Options` / `sandbox` 太紧 | 看浏览器控制台的拒绝原因，对号处理；`sandbox` 至少要 `allow-scripts allow-same-origin`，导出还要 `allow-downloads` |
| 条件没生效，顶上有提示 | 条件 id 拼错 | 核对报表筛选栏里的 id |
| 条件没生效，没有提示 | 值的写法不对（区间、多选、编码） | 按上面的写法表改 |
| 出现第二条滚动条 | 没监听 `height` | 加上高度同步 |
| `setParams` 无反应 | 发早了 / `source` 写错 / targetOrigin 不匹配 / 该条件被 `lock` 或快照锁了 | 按顺序排查 |
| 报表改了页面没变 | 只改了草稿没发布，或链接钉了 `version` | 重新发布；去掉 `version` |

## GLOSSARY

- **查看态**：只有筛选栏和画布的只读页面，`view=1`，宿主嵌的就是它。
- **设计器**：做报表的界面，带对话面板和属性面板，不要嵌给最终用户。
- **发布版 / 草稿**：嵌出去的链接跟发布版走；草稿是设计者正在改的那份。
- **数据快照**：发布时固化了数据的版本，打开不查库，条件只读。
- **穿透明细**：点图表或指标卡弹出的明细层，查看态里点了就有，宿主不用管。
- **设计令牌**：`--cr-*` 开头的 CSS 变量，主题只换值不改样式源码。


---

# conch-report 接入文档

把对话式报表嵌进你们自己的系统：一个 iframe，一条链接。


## 它是什么

conch-report 是独立部署的报表服务：业务人员用对话把报表做出来、发布，宿主系统把发布好的报表**嵌进自己的页面**给人看。

这份文档只讲后半截——**怎么嵌**。做报表本身在报表服务自己的界面里完成，不需要宿主参与。

## 查看态和设计器的区别

同一套渲染，两个入口。宿主要嵌的永远是查看态。

| | 设计器 `?id=xxx` | 查看态 `?id=xxx&view=1` |
|---|---|---|
| 给谁用 | 做报表的人 | 看报表的人 |
| 界面 | 对话面板、属性面板、草稿与发布按钮 | 只有筛选栏和画布 |
| 内容 | 当前草稿，边改边看 | 已发布的版本 |
| 改报表 | 能 | 不能 |
| 筛选、穿透明细、导出 | 能 | 能 |

## 接入要准备什么

1. 报表服务的地址，例如 `https://report.example.com`。
2. 要嵌的报表 id：在报表列表页每行点「嵌入」就能拿到整条链接和一段 iframe 代码。
3. 这张报表**已经发布过**。没发布的报表嵌出去只会显示一句「还没有发布」。

剩下的看[五分钟接入](/guide/quickstart)。

## 现在还不支持什么

说在前面，免得你们按错误的预期去设计：

- **查看页没有自己的登录页**。这一版靠部署位置控访问（放在内网，或由宿主反向代理并在代理上鉴权）。按 JWT 换票把宿主登录态带进来的能力在路线上，还没上线。
- **不支持让数据请求绕道宿主网关**。报表服务直连数据库取数，浏览器只跟报表服务说话。
- **数据源只支持 SQL Server、MySQL、PostgreSQL**。
- **小程序 web-view 只能用链接参数**，收不到也发不了 postMessage，详见[常见问题](/reference/faq#小程序-web-view-里能嵌吗)。


---

# 五分钟接入

下面四步，每一步都能单独验证。把 `https://report.example.com` 换成你们部署的报表服务地址。

## 第一步：拿到报表地址

打开报表服务首页，在报表列表里找到要嵌的那张，点这一行的**「嵌入」**，对话框里给出两样东西：

- 报表地址：`https://report.example.com/?id=r260922123456&view=1`
- 嵌入代码：一段可以直接粘的 `<iframe>`

`id` 是报表 id，`view=1` 表示查看态。手上只有报表 id 时，自己照这个格式拼也一样。

**报表必须先发布**
链接指向的是**当前发布版**。没发布过的报表打开只显示一句「这张报表还没有发布」。

## 第二步：粘进你们的页面

```html
<iframe
  src="https://report.example.com/?id=r260922123456&view=1"
  style="width:100%;height:720px;border:0"
  allowfullscreen
></iframe>
```

到这一步页面上就能看到报表了。`height` 先写个固定值，第四步再让它自适应。

## 第三步：把筛选条件喂给报表

报表里的每个筛选条件都有一个 id（月份 `month`、门店 `store`、科室 `dept`……），直接写进链接：

```html
<iframe src="https://report.example.com/?id=r260922123456&view=1&month=2026-08&store=S001"></iframe>
```

打开就是 2026 年 8 月、S001 这家店的数。

宿主指定的口径不想让看的人改，加 `lock`：

```
&month=2026-08&lock=month
```

被锁住的条件显示出来但改不了。更多写法看[链接参数](/guide/url)。

**条件 id 要对得上**
链接里写了、报表里没有的参数名会被忽略，页面顶上会列出来提醒你。看到提示就去核对报表筛选栏里的条件 id。

## 第四步：让 iframe 高度跟着内容走

报表页会把自己的内容高度发给宿主页面，宿主照着调 iframe 高度，页面里就不会出现第二条滚动条。

```html
<iframe id="report" src="https://report.example.com/?id=r260922123456&view=1"
        style="width:100%;height:480px;border:0"></iframe>

<script>
  window.addEventListener('message', (e) => {
    const msg = e.data
    if (!msg || msg.source !== 'conch-report') return
    if (msg.type === 'height') {
      document.getElementById('report').style.height = msg.height + 'px'
    }
  })
</script>
```

生产上把判断收紧成只认报表服务的域名：

```js
if (e.origin !== 'https://report.example.com') return
```

## 完整示例

一个能直接保存成 `.html` 打开的最小宿主页面：

```html
<!doctype html>
<html lang="zh-CN">
<head><meta charset="utf-8" /><title>经营看板</title></head>
<body style="margin:0;font-family:system-ui">
  <h2 style="padding:16px 20px;margin:0">经营看板</h2>

  <iframe id="report"
    src="https://report.example.com/?id=r260922123456&view=1&month=2026-08&chrome=0"
    style="width:100%;height:480px;border:0"></iframe>

  <script>
    const REPORT_ORIGIN = 'https://report.example.com'
    const frame = document.getElementById('report')

    window.addEventListener('message', (e) => {
      if (e.origin !== REPORT_ORIGIN) return
      const msg = e.data
      if (!msg || msg.source !== 'conch-report') return
      if (msg.type === 'height') frame.style.height = msg.height + 'px'
      if (msg.type === 'ready') console.log('报表已打开', msg.title, msg.version)
      if (msg.type === 'params') console.log('筛选条件变成了', msg.params)
    })

    // 不刷新 iframe 改条件
    function setMonth(month) {
      frame.contentWindow.postMessage(
        { source: 'conch-report-host', type: 'setParams', params: { month } },
        REPORT_ORIGIN,
      )
    }
  </script>
</body>
</html>
```

`chrome=0` 去掉了报表自带的页头（标题、刷新、导出），页头由宿主自己做。

## 接下来

- 链接还能带什么：[链接参数](/guide/url)
- 宿主怎么跟报表互相发消息：[与宿主页面通信](/guide/postmessage)
- 换成你们系统的配色：[外观与主题](/guide/theme)
- Vue / React / 后台框架里怎么写：[宿主代码示例](/guide/examples)
- 上线前要配的东西：[部署与安全](/guide/security)


---

# 链接参数

查看态的链接就是接口。除了下面这几个保留字段，链接上其余的 key **一律当成报表的筛选条件**。

```
https://report.example.com/?id=<报表id>&view=1[&其它参数]
```

## 保留字段

| 参数 | 必填 | 说明 |
|---|---|---|
| `id` | 是 | 报表 id，形如 `r260922123456` |
| `view` | 是 | 写 `1` 表示查看态；不写就是设计器 |
| `version` | 否 | 看哪一版，默认当前发布版。见下方[版本](#版本) |
| `lock` | 否 | 哪些筛选条件只显示不让改，逗号分隔；写 `all` 锁住全部 |
| `chrome` | 否 | 写 `0` 去掉报表自带的页头（标题、版本、刷新、导出） |
| `theme` | 否 | 覆盖设计令牌，见[外观与主题](/guide/theme) |

## 筛选条件

条件的 id 在报表里定义（做报表的人能在属性面板看到），宿主按 id 传值。

| 条件类型 | 链接写法 | 例子 |
|---|---|---|
| 文本 | `id=值` | `&keyword=%E6%89%8B%E6%9C%AF` |
| 数字 | `id=值` | `&min_qty=100` |
| 日期 | `id=YYYY-MM-DD` | `&day=2026-08-31` |
| 月份 | `id=YYYY-MM` | `&month=2026-08` |
| 日期区间 | `id=起,止` 或 `id_from=起&id_to=止` | `&range=2026-01-01,2026-03-31` |
| 数字区间 | `id=小,大` 或 `id_min=小&id_max=大` | `&amount=100,500` |
| 单选、树形下拉 | `id=值` | `&store=S001` |
| 多选下拉 | `id=a,b` 或重复写 `id=a&id=b` | `&store=S001,S002` |

几条规则：

- **值要做 URL 编码**。中文、空格、`&`、`#` 不编码会被浏览器截断，`encodeURIComponent()` 一下就行。
- **写空串表示「不限」**：`&month=` 会把报表里这个条件的默认值清掉，查全部。
- **链接上不写的条件用报表自己的默认值**，不会被清空。
- **区间只写一头也行**：`&range_from=2026-01-01` 就是「这天以后」。
- **数字位置写了非数字**（`&min_qty=abc`）按「不限」处理，不会报错也不会查出错数。

### 写错了会怎样

链接里写了、报表里没有这个条件 id，页面顶上会列出来：

> 链接里的 `storeid` 不是这张报表的筛选条件，已忽略。处理：核对链接里的参数名与报表筛选栏一致。

报表照常显示，只是那个条件没生效。看到这句就去核对 id 的拼写。

## 锁住条件

宿主指定的口径不该让看的人改——比如按登录用户所在门店限定数据：

```
&store=S001&lock=store
```

`store` 显示出来但是灰的，改不了。多个用逗号：`&lock=store,dept`。全部锁死：`&lock=all`。

**lock 是界面口径，不是数据权限**
`lock` 只是把控件设成只读。**它挡不住会改链接的人**——把 `lock` 去掉、把 `store` 换个值，照样能看到别的门店。

真正的数据边界在服务端：只读账号、SQL 守卫，以及按登录身份下发的行级范围参数。要做到「这个人只能看到自己门店」，得走行级范围那条路，不是靠 `lock`。

## 版本

| 写法 | 看到的内容 |
|---|---|
| 不写 | 当前发布版。报表重新发布，这条链接自动跟到新版本 |
| `version=v2` | 钉死在第 2 版，之后再发布也不变 |
| `version=draft` | 当前草稿。发布前自查用，**不要发给客户** |

**数据快照版**（发布时选了「数据快照」）打开时不查数据库，数字和筛选条件都是发布那一刻固化下来的：条件一律只读，页头没有「刷新数据」，页面上会写明「这一版是数据快照」。

## 一条完整的链接

```
https://report.example.com/?id=r260922123456&view=1
  &month=2026-08
  &store=S001,S002
  &lock=store
  &chrome=0
  &theme=primary:%232c6ecb
```

（实际使用写成一行，不要换行。）

意思是：打开这张报表的当前发布版，看 2026 年 8 月、S001 与 S002 两家店，门店条件不让改，不要报表自带的页头，主色换成 `#2c6ecb`。

## 拼链接的代码

```js
function reportUrl(base, id, params = {}, opts = {}) {
  const q = new URLSearchParams({ id, view: '1' })
  for (const [key, value] of Object.entries(params)) {
    if (value === null || value === undefined) continue
    q.set(key, Array.isArray(value) ? value.join(',') : String(value))
  }
  if (opts.lock) q.set('lock', Array.isArray(opts.lock) ? opts.lock.join(',') : opts.lock)
  if (opts.chrome === false) q.set('chrome', '0')
  if (opts.version) q.set('version', opts.version)
  if (opts.theme) q.set('theme', Object.entries(opts.theme).map(([k, v]) => `${k}:${v}`).join(','))
  return `${base}/?${q}`
}

// reportUrl('https://report.example.com', 'r260922123456',
//   { month: '2026-08', store: ['S001', 'S002'] }, { lock: 'store', chrome: false })
```

`URLSearchParams` 自己会做编码，不用再手工转义。


---

# 与宿主页面通信

链接参数管「打开时是什么样」，`postMessage` 管「打开之后要变」——改筛选条件、重新取数、换主题，都不用刷新 iframe。

所有消息都带 `source` 标记：报表发出的是 `conch-report`，宿主发来的是 `conch-report-host`。两边都按这个标记过滤，页面上别的库发的消息不会被当成指令。

## 报表 → 宿主

```js
window.addEventListener('message', (e) => {
  if (e.origin !== 'https://report.example.com') return
  const msg = e.data
  if (!msg || msg.source !== 'conch-report') return
  // ...
})
```

| `type` | 什么时候发 | 带什么 |
|---|---|---|
| `ready` | 报表打开并渲染完 | `id` 报表 id、`title` 报表名、`version` 看的是哪一版 |
| `height` | 内容高度变了（首次渲染、切筛选条件、窗口变宽变窄） | `height` 内容高度，单位 px |
| `params` | 筛选条件变了（人在筛选栏上改的，或宿主发 `setParams` 改的） | `params` 当前全部条件的值 |

```js
// 报表发出来的消息长这样
{ source: 'conch-report', type: 'ready', id: 'r260922123456', title: '门店经营看板', version: 'v3' }
{ source: 'conch-report', type: 'height', height: 872 }
{ source: 'conch-report', type: 'params', params: { month: '2026-08', store: ['S001'] } }
```

三件典型的事：

- 收到 `height` 就调 iframe 高度，页面里不会出现第二条滚动条。
- 收到 `ready` 再把加载动画去掉，或者记一笔埋点。
- 收到 `params` 把条件写回宿主自己的地址栏，用户刷新页面还能回到同一个筛选状态。

## 宿主 → 报表

```js
frame.contentWindow.postMessage(
  { source: 'conch-report-host', type: 'setParams', params: { month: '2026-07' } },
  'https://report.example.com',  // 生产上写具体域名，别用 '*'
)
```

| `type` | 作用 | 带什么 |
|---|---|---|
| `setParams` | 改筛选条件，改完自动重新取数 | `params`：条件 id → 值，只写要改的那几个 |
| `refresh` | 按当前条件重新取一次数 | 无 |
| `setTheme` | 换设计令牌 | `tokens`：令牌名 → 值，见[外观与主题](/guide/theme) |

值的写法和链接参数一致，只是这里用真正的 JS 类型，不用拼字符串：

```js
{ month: '2026-08' }                       // 月份
{ range: ['2026-01-01', '2026-03-31'] }    // 日期区间：[起, 止]
{ amount: [100, 500] }                     // 数字区间：[小, 大]
{ store: ['S001', 'S002'] }                // 多选
{ keyword: null }                          // null = 不限
```

**发早了会丢**
iframe 还没加载完时发的消息没人接。等 `ready` 到了再发，或者在 `iframe.onload` 之后发。

## 两边接起来的样子

```js
const REPORT_ORIGIN = 'https://report.example.com'
const frame = document.getElementById('report')
let ready = false
const pending = []

window.addEventListener('message', (e) => {
  if (e.origin !== REPORT_ORIGIN) return
  const msg = e.data
  if (!msg || msg.source !== 'conch-report') return

  if (msg.type === 'height') frame.style.height = msg.height + 'px'
  if (msg.type === 'ready') { ready = true; pending.splice(0).forEach(send) }
  if (msg.type === 'params') syncToAddressBar(msg.params)
})

function send(msg) {
  if (!ready) { pending.push(msg); return }
  frame.contentWindow.postMessage({ source: 'conch-report-host', ...msg }, REPORT_ORIGIN)
}

// 宿主自己的筛选器联动报表
document.getElementById('month').addEventListener('change', (e) => {
  send({ type: 'setParams', params: { month: e.target.value } })
})
```

## 用不上 postMessage 的场合

- **小程序 web-view**：不支持这套消息，只能用链接参数，条件要变就换 `src`。
- **`sandbox` 属性写死的 iframe**：加了 `sandbox` 就必须带上 `allow-scripts allow-same-origin`，否则报表里的脚本跑不起来，消息也发不出来。要用导出功能再加 `allow-downloads`。


---

# 外观与主题

报表的颜色、圆角、字体全部走 CSS 变量（设计令牌）。宿主**只换值，不改样式源码**——这样报表升级不会把你们改过的样式冲掉。

## 换法一：写在链接上

```
&theme=primary:%232c6ecb,bg:%23ffffff
```

- 写成 `名:值`，多个用逗号隔开。
- 名字可以省掉 `--cr-` 前缀：`primary` 等于 `--cr-primary`。
- `#` 在 URL 里要编码成 `%23`。
- **值里不能有逗号**（逗号是分隔符）。所以链接上用 `#2c6ecb`，不要用 `rgb(44,110,203)`。

## 换法二：发消息

值里要带逗号、或者主题要跟着宿主的深浅色切换，用这个：

```js
frame.contentWindow.postMessage({
  source: 'conch-report-host',
  type: 'setTheme',
  tokens: {
    primary: '#2c6ecb',
    bg: 'rgb(248, 249, 251)',
    '--cr-radius': '4px',
  },
}, 'https://report.example.com')
```

## 常用的令牌

改前四个就能让报表看起来像你们的系统，其余按需要挑。

| 令牌 | 管什么 | 默认值 |
|---|---|---|
| `primary` | 主色：按钮、选中态、链接 | `#2c6ecb` |
| `bg` | 页面底色 | `#f5f6f8` |
| `surface` | 卡片、组件底色 | `#ffffff` |
| `text` | 正文字色 | `#1d2330` |
| `primary-hover` / `primary-active` | 主色的悬浮态、按下态 | 深一档、再深一档 |
| `primary-soft` / `primary-border` | 主色的浅底、浅描边 | `#eaf1fc` / `#b9d0f0` |
| `surface-sunken` / `surface-hover` | 次级底色、悬浮底色 | `#fafbfc` / `#f2f4f7` |
| `border` / `border-strong` / `border-subtle` | 三档描边 | `#e3e6ea` / `#cfd4da` / `#eceff2` |
| `text-secondary` / `text-muted` | 次要文字、弱化文字 | `#4b5563` / `#8a919e` |
| `success` / `warning` / `danger` | 语义色 | 绿 / 黄 / 红 |
| `trend-up` / `trend-down` | 涨跌色（中文语境默认涨绿跌红，要互换就改这两个） | `#2f7d55` / `#b8453c` |
| `chart-1` … `chart-8` | 图表分类色板，按顺序取 | 低饱和八色 |
| `chart-seq-1` … `chart-seq-6` | 连续量色阶（热力图一类） | 单色阶 |
| `chart-axis` / `chart-grid` / `chart-label` | 坐标轴、网格线、轴标签 | 浅灰系 |
| `font-sans` / `font-mono` | 字体族 | 系统中文字体栈 |
| `radius-sm` / `radius` / `radius-lg` | 圆角三档 | `3px` / `6px` / `10px` |
| `font-size-md` / `font-size-lg` | 正文字号 | `13px` / `14px` |

**图表颜色也跟着走**
图表用的是同一套令牌，不需要单独配。改 `chart-1` 到 `chart-8` 就能让图表配色统一到你们的视觉规范上。

## 页头要不要

`&chrome=0` 去掉报表自带的页头（报表名、版本标记、刷新数据、导出）。适合宿主自己已经有标题栏和工具条的场合。

去掉之后这些能力也跟着没了：

- **刷新数据** → 宿主发 `{ type: 'refresh' }` 代替。
- **导出 Excel / Word / PDF** → 留着页头，或者由宿主调[导出接口](/reference/api#导出)。

## 窄屏与手机

宽度小于等于 760px 时，报表自动从 12 栏栅格换成**整列堆叠**，顺序按组件在画布上从上到下、从左到右排。宿主侧栏里嵌、手机 web-view 里打开都能看。

组件的高度按它在设计时占的行数留，图表不会被压扁。

## 打印和存 PDF

报表页头、提示条这些在打印时自动隐藏，打印出来的就是画布本身。让使用者用浏览器打印（或在报表页头的「导出」里选「导出 PDF」，走的也是浏览器打印）。


---

# 宿主代码示例

四种宿主形态的可用代码，复制过去改掉 `REPORT_ORIGIN` 就能跑。

## 原生 HTML

一个可复用的小封装，不依赖任何框架：

```html
<div id="box" style="width:100%"></div>

<script>
function mountReport(container, { origin, id, params = {}, lock, chrome = true, version }) {
  const q = new URLSearchParams({ id, view: '1' })
  for (const [k, v] of Object.entries(params)) {
    if (v !== null && v !== undefined) q.set(k, Array.isArray(v) ? v.join(',') : String(v))
  }
  if (lock) q.set('lock', Array.isArray(lock) ? lock.join(',') : lock)
  if (chrome === false) q.set('chrome', '0')
  if (version) q.set('version', version)

  const frame = document.createElement('iframe')
  frame.src = `${origin}/?${q}`
  frame.style.cssText = 'width:100%;height:480px;border:0'
  container.appendChild(frame)

  let ready = false
  const queue = []
  const post = (msg) => {
    if (!ready) { queue.push(msg); return }
    frame.contentWindow.postMessage({ source: 'conch-report-host', ...msg }, origin)
  }

  const onMessage = (e) => {
    if (e.origin !== origin || e.source !== frame.contentWindow) return
    const msg = e.data
    if (!msg || msg.source !== 'conch-report') return
    if (msg.type === 'height') frame.style.height = msg.height + 'px'
    if (msg.type === 'ready') { ready = true; queue.splice(0).forEach(post) }
  }
  window.addEventListener('message', onMessage)

  return {
    setParams: (params) => post({ type: 'setParams', params }),
    refresh: () => post({ type: 'refresh' }),
    setTheme: (tokens) => post({ type: 'setTheme', tokens }),
    destroy: () => { window.removeEventListener('message', onMessage); frame.remove() },
  }
}

const report = mountReport(document.getElementById('box'), {
  origin: 'https://report.example.com',
  id: 'r260922123456',
  params: { month: '2026-08' },
  lock: 'store',
})
// report.setParams({ month: '2026-07' })
</script>
```

## Vue 3

`ConchReport.vue`：

```vue
<script setup>
import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'

const props = defineProps({
  origin: { type: String, required: true },
  reportId: { type: String, required: true },
  params: { type: Object, default: () => ({}) },
  lock: { type: [String, Array], default: '' },
  chrome: { type: Boolean, default: true },
  version: { type: String, default: '' },
})
const emit = defineEmits(['ready', 'params'])

const frame = ref(null)
const height = ref(480)
const ready = ref(false)

const src = computed(() => {
  const q = new URLSearchParams({ id: props.reportId, view: '1' })
  for (const [k, v] of Object.entries(props.params)) {
    if (v !== null && v !== undefined) q.set(k, Array.isArray(v) ? v.join(',') : String(v))
  }
  const lock = Array.isArray(props.lock) ? props.lock.join(',') : props.lock
  if (lock) q.set('lock', lock)
  if (!props.chrome) q.set('chrome', '0')
  if (props.version) q.set('version', props.version)
  return `${props.origin}/?${q}`
})

function post(msg) {
  if (!ready.value) return
  frame.value?.contentWindow?.postMessage({ source: 'conch-report-host', ...msg }, props.origin)
}

function onMessage(e) {
  if (e.origin !== props.origin || e.source !== frame.value?.contentWindow) return
  const msg = e.data
  if (!msg || msg.source !== 'conch-report') return
  if (msg.type === 'height') height.value = msg.height
  if (msg.type === 'ready') { ready.value = true; emit('ready', msg) }
  if (msg.type === 'params') emit('params', msg.params)
}

onMounted(() => window.addEventListener('message', onMessage))
onBeforeUnmount(() => window.removeEventListener('message', onMessage))

// 条件变了走消息，不重新加载 iframe（重载会让图表重画一遍）
watch(() => props.params, (v) => post({ type: 'setParams', params: v }), { deep: true })

defineExpose({ refresh: () => post({ type: 'refresh' }), setTheme: (tokens) => post({ type: 'setTheme', tokens }) })
</script>

<template>
  <iframe ref="frame" :src="src" :style="{ width: '100%', height: height + 'px', border: 0 }" />
</template>
```

用：

```vue
<ConchReport
  origin="https://report.example.com"
  report-id="r260922123456"
  :params="{ month, store: myStores }"
  lock="store"
  @ready="(m) => console.log('打开了', m.title)"
/>
```

## React

```jsx
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'

export function ConchReport({ origin, reportId, params = {}, lock, chrome = true, version, onReady, onParams }) {
  const frameRef = useRef(null)
  const readyRef = useRef(false)
  const [height, setHeight] = useState(480)

  const src = useMemo(() => {
    const q = new URLSearchParams({ id: reportId, view: '1' })
    for (const [k, v] of Object.entries(params)) {
      if (v !== null && v !== undefined) q.set(k, Array.isArray(v) ? v.join(',') : String(v))
    }
    if (lock) q.set('lock', Array.isArray(lock) ? lock.join(',') : lock)
    if (!chrome) q.set('chrome', '0')
    if (version) q.set('version', version)
    return `${origin}/?${q}`
    // 首次挂载用参数拼 src；之后条件变化走 setParams，不换 src
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [origin, reportId])

  const post = useCallback((msg) => {
    if (!readyRef.current) return
    frameRef.current?.contentWindow?.postMessage({ source: 'conch-report-host', ...msg }, origin)
  }, [origin])

  useEffect(() => {
    const onMessage = (e) => {
      if (e.origin !== origin || e.source !== frameRef.current?.contentWindow) return
      const msg = e.data
      if (!msg || msg.source !== 'conch-report') return
      if (msg.type === 'height') setHeight(msg.height)
      if (msg.type === 'ready') { readyRef.current = true; onReady?.(msg) }
      if (msg.type === 'params') onParams?.(msg.params)
    }
    window.addEventListener('message', onMessage)
    return () => window.removeEventListener('message', onMessage)
  }, [origin, onReady, onParams])

  useEffect(() => { post({ type: 'setParams', params }) }, [JSON.stringify(params)]) // eslint-disable-line

  return <iframe ref={frameRef} src={src} style={{ width: '100%', height, border: 0 }} />
}
```

## 后台框架里挂一个菜单页

若依、ABP 这类后台前端，做法都是「加一个路由页，页面里就一个 iframe」，报表 id 从路由参数或菜单配置来：

```js
// 路由：/report/:id
{ path: '/report/:id', component: () => import('@/views/report/embed.vue') }
```

```vue
<script setup>
import { useRoute } from 'vue-router'
import { useUserStore } from '@/store/user'
import ConchReport from '@/components/ConchReport.vue'

const route = useRoute()
const user = useUserStore()
// 宿主按登录身份决定口径，并锁住不让改
const params = { month: new Date().toISOString().slice(0, 7), dept: user.deptCode }
</script>

<template>
  <div class="app-container">
    <ConchReport origin="https://report.example.com" :report-id="route.params.id"
                 :params="params" lock="dept" :chrome="false" />
  </div>
</template>
```

菜单里配几张报表，就把几张报表的 id 填进菜单的路由参数。要列出全部报表由宿主自己渲染列表，调[报表列表接口](/reference/api#报表列表)。

**锁住不等于限权**
上面把 `dept` 锁住只是界面上不让改。谁都可以把 iframe 的地址抄出来改掉 `dept`。真正按科室限制数据要在报表服务侧做行级范围，见[部署与安全](/guide/security#数据边界在哪)。

## 微信小程序 web-view

```json
{ "usingComponents": {} }
```

```html
<!-- pages/report/index.wxml -->
<web-view src="{{url}}"></web-view>
```

```js
// pages/report/index.js
Page({
  data: { url: '' },
  onLoad(query) {
    const base = 'https://report.example.com'
    const params = new URLSearchParams({ id: query.id, view: '1', month: query.month || '', chrome: '0' })
    this.setData({ url: `${base}/?${params}` })
  },
})
```

三点限制：

- 域名要先在小程序后台配成**业务域名**，否则 web-view 打不开。
- 收不到也发不出 postMessage：条件要变就 `setData` 换一次 `url`。
- 屏幕窄，报表会整列堆叠；组件多的看板在手机上读起来吃力，建议给手机单独做一张精简的报表。


---

# 部署与安全

上线前要定三件事：**谁能嵌**、**谁能看**、**数据到哪为止**。

## 允许哪些宿主嵌

报表服务的配置文件 `conch.config.json`：

```json
{
  "embed": {
    "allowedOrigins": ["https://hdms.example.com", "https://portal.example.com"]
  }
}
```

配了这一段，报表服务在每个响应上发 `Content-Security-Policy: frame-ancestors https://hdms.example.com https://portal.example.com`——只有这两个站点能把报表嵌进 iframe，别人嵌会被浏览器挡掉。

不配这一段就不发这个头，**任何站点都能嵌**。本地开发和演示可以不配，正式部署应当配上。改完重启报表服务生效。

**也要检查反向代理**
有些网关默认往回加 `X-Frame-Options: SAMEORIGIN`，那一条会让所有跨域嵌入失败，而且比 `frame-ancestors` 更粗暴。报表服务自己不发这个头，发了就是代理加的，去代理上关掉。

## 谁能看到报表

**这一版的查看页没有自己的登录页。** 访问控制靠部署位置来做，两种可行方案：

**一、放在内网 / 只开给宿主的网络**
报表服务不暴露到公网，只有能访问宿主系统的人能访问它。最省事，适合院内、厂内部署。

**二、由宿主反向代理，鉴权在代理上做**
把报表服务挂到宿主自己的域名下，用户的登录态（cookie）天然带上，也没有跨站 cookie 的麻烦：

```nginx
location /report/ {
    # 这里接你们自己的鉴权（auth_request / JWT 校验 / 基础认证）
    auth_request /your-auth;

    proxy_pass http://127.0.0.1:5088/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    # 多租户部署时由代理钉死租户，浏览器改不了
    proxy_set_header X-Conch-Tenant hospital-a;

    # 对话式生成走 SSE，必须关缓冲
    proxy_buffering off;
}
```

宿主页面里 iframe 就写 `src="/report/?id=...&view=1"`，同源，`frame-ancestors` 也不用配了。

**别把报表服务直接开到公网又不设任何认证**
查看态链接里只有报表 id，能猜到 id 的人就能看到那张报表的数据。公网部署一定要在前面加一道认证。

租户目前从请求头 `X-Conch-Tenant` 取，浏览器发不出这个头，所以**多租户必须在反向代理上注入**，不能指望前端传。

按登录身份把宿主的科室、区域、角色带进报表（JWT 换票）在路线上，还没上线；现在需要这类隔离的场合，按租户分开部署。

## 数据边界在哪

| 这一层 | 做了什么 |
|---|---|
| 数据库账号 | 只读账号，写操作在库上就被拒 |
| SQL 守卫 | 报表里的每条 SQL 执行前都过一遍守卫，只放行单条只读查询 |
| 查看态下发内容 | 规格里的 **SQL 正文不下发到浏览器**，查看页拿到的只有渲染要用的结构 |
| 客户端传参 | 查看态只报版本号，规格由服务端按那一版取，浏览器传来的规格不作数 |
| 行级范围 | 由服务端按调用者身份注入系统参数，SQL 里引用它做过滤 |
| 模型 | 只在设计态参与，只看表结构与字典值；**运行态没有模型**，数据从库到浏览器不经过任何模型 |

`lock=` 只是界面口径（控件只读），不是权限。会改链接的人能把它去掉。**要做到「这个人只能看到自己那部分数据」，必须落在行级范围参数上**，不能靠 `lock`。

## HTTPS

宿主是 `https://`、报表服务是 `http://`，浏览器会按混合内容直接拦掉 iframe，页面上一片空白。两边都上 HTTPS，或者都走同一个域名下的反向代理。

## 链接里别放这些

- 不要放 token、密码、签名。查看态链接会进浏览器历史、进 Referer、被人抄给同事。
- 不要放 SQL。报表服务不接受从链接或请求体传 SQL 来执行。
- 不要放能反推出别人身份的值——链接是可以改的，把 `dept=A` 改成 `dept=B` 的成本是零。

## 版本怎么发才稳

- 嵌出去的链接默认跟着**当前发布版**走。设计者改草稿不会影响生产页面，**重新发布才会更新**。
- 要在改版期间保持页面不变，把链接钉在某一版：`&version=v3`。
- 要给客户一份不会再变的数，发布时选「数据快照」，那一版打开不查库。
- `version=draft` 只用于发布前自查，别出现在给客户的链接里。


---

# HTTP 接口

嵌一个 iframe 用不到这些接口——**它们是给要自己做报表列表、自己做导出按钮、或者要把报表数据拿去别处用的宿主准备的**。

约定：

- 前缀统一 `/api`，请求体与响应体都是 JSON（UTF-8）。
- 出错回 `{ "error": "一句能照着办的话" }`，HTTP 状态码见各接口。
- 多租户部署时租户从请求头 `X-Conch-Tenant` 取，**由反向代理注入**，见[部署与安全](/guide/security#谁能看到报表)。
- 查看类调用一律带 `version`，服务端按那一版取规格；**接口不接受客户端传 SQL**。

## 报表列表

```http
GET /api/reports
```

```json
[
  {
    "id": "r260922123456",
    "title": "门店经营看板",
    "datasource": "retail",
    "updatedAt": "2026-09-22T14:03:11",
    "publishedVersion": "v3",
    "hasDraft": true
  }
]
```

`publishedVersion` 为 `null` 表示这张报表还没发布过，嵌出去打不开。宿主做自己的报表菜单时按这个字段过滤。

## 打开一张报表

```http
GET /api/reports/{id}/view?version=v3
```

`version` 不写取当前发布版；`draft` 取草稿。查看页自己调的就是它。

```json
{
  "id": "r260922123456",
  "title": "门店经营看板",
  "version": "v3",
  "mode": "dynamic",
  "publishedAt": "2026-09-22T14:10:05",
  "note": "加了退款率",
  "spec": { "version": 1, "title": "…", "params": [], "queries": {}, "nodes": [] },
  "params": { "month": "2026-08" },
  "data": null
}
```

| 字段 | 说明 |
|---|---|
| `mode` | `dynamic` 每次打开取最新数；`snapshot` 数据快照，数字已固化 |
| `spec` | 渲染用的报表规格。**SQL 正文已去掉**，查询名保留 |
| `params` | 发布那一刻的筛选条件值，作为初始值 |
| `data` | 仅快照版有值：固化下来的查询结果，形状同下面的 `queries` |

| 状态码 | 含义 |
|---|---|
| `404` | 报表不存在，或指定的版本号不存在 |
| `409` | 这张报表还没有发布 |

## 取数

```http
POST /api/reports/{id}/data
Content-Type: application/json

{ "version": "v3", "params": { "month": "2026-08", "store": ["S001", "S002"] } }
```

```json
{
  "queries": {
    "q_by_store": {
      "columns": ["store_name", "sales_amount"],
      "columnTypes": ["String", "Decimal"],
      "rows": [["上海徐汇店", 281033.5], ["上海浦东店", 236810.0]],
      "truncated": false,
      "elapsedMs": 42
    },
    "q_total": { "error": "字段 pay_amount 不存在" }
  }
}
```

- 每条查询单独成败：一条查不出来，其它照常返回，那一条带 `error`。
- `rows` 是二维数组，列顺序同 `columns`；日期已格式化成 `yyyy-MM-dd` 或 `yyyy-MM-dd HH:mm:ss`。
- `truncated` 为 `true` 表示结果超过上限被截断（页面上限 5000 行）。
- 参数写法同链接参数，只是用真正的 JSON 类型：区间写 `["2026-01-01", "2026-03-31"]`，多选写数组，不限写 `null`。

## 穿透明细

```http
POST /api/reports/{id}/drill

{ "version": "v3", "drill": "d_store_orders",
  "args": { "store_name": "上海徐汇店" },
  "params": { "month": "2026-08" } }
```

```json
{ "title": "上海徐汇店 订单明细", "queries": { "q_orders": { "columns": [], "rows": [] } } }
```

`drill` 是报表规格里声明的穿透目标 key，`args` 的 key 必须是该目标声明过的参数，否则整个请求回 `400`。**穿透 SQL 在服务端按规格取，客户端传不进来。**

## 导出

```http
POST /api/reports/{id}/export/xlsx
POST /api/reports/{id}/export/docx

{ "version": "v3", "params": { "month": "2026-08" } }
```

回的是文件流，文件名在 `Content-Disposition` 里。带上 `"drill": "d_store_orders", "args": {…}` 就是导出那一层穿透明细。

- `xlsx` 全量数据（上限 10 万行，页面上限是 5000 行），`docx` 图文报告。
- PDF 没有接口：走浏览器打印，在报表页头的「导出」里选。
- 报表规格里关掉了某种格式，对应请求回 `400`。

## 版本列表

```http
GET /api/reports/{id}/versions
```

```json
[
  { "no": "v3", "time": "2026-09-22T14:10:05", "who": "本人", "note": "加了退款率",
    "mode": "dynamic", "current": true,
    "audit": { "score": 86, "grade": "excellent", "findings": 2, "highest": "low" } }
]
```

宿主要做「看历史版本」的下拉时用它，`no` 填进链接的 `version`。

## curl 速查

```bash
BASE=https://report.example.com
ID=r260922123456

# 这张报表能不能嵌（回 409 就是还没发布）
curl -s "$BASE/api/reports/$ID/view" | head -c 300

# 按条件取数
curl -s -X POST "$BASE/api/reports/$ID/data" \
  -H 'Content-Type: application/json' \
  -d '{"version":"v3","params":{"month":"2026-08"}}'

# 导出 Excel
curl -s -X POST "$BASE/api/reports/$ID/export/xlsx" \
  -H 'Content-Type: application/json' \
  -d '{"version":"v3","params":{"month":"2026-08"}}' -OJ
```


---

# 常见问题

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

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

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

**处理：** 打开报表，点右上角「发布」，再回来打开这个链接。只是想在发布前自己看一眼，用 `&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。

没有提示但值不对，看[链接参数](/guide/url#筛选条件)里各类型的写法：区间要写 `起,止`，多选用逗号分隔，值要 URL 编码。

## iframe 里出现了第二条滚动条

宿主没有按报表报上来的高度调 iframe。监听 `height` 消息，见[五分钟接入第四步](/guide/quickstart#第四步：让-iframe-高度跟着内容走)。

## 高度消息收不到

- 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`，页头连同导出一起去掉了。宿主自己做按钮，调[导出接口](/reference/api#导出)。
2. 报表规格里关掉了导出格式。
3. 当前在数据快照版且规格关掉了导出。

## 小程序 web-view 里能嵌吗

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

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

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

## 一个页面能嵌几张报表

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

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

## 报表服务挂了页面会怎样

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