宿主事件与方法调用

概述

报表嵌入 iframe 后，可以和宿主页面双向通信：

• 事件（报表到宿主）：报表加载完成、出错、查询、导出，以及设计者在报表里配置的自定义事件（点击单元格、点击图表数据点等）。
• 方法调用（宿主到报表）：宿主向 iframe 发送 invoke 消息，改变查询参数、重新查询、读取状态、导出等。

所有消息都通过 window.postMessage 传递，消息体中带 protocol: 'sight-report'。宿主接收时必须校验 event.origin（报表系统的部署地址）和 data.protocol，避免误收页面上其他组件的消息。

功能入口

• 自定义事件的配置位置（在设计器中）：
  • 网格报表：单元格 > 链接 > 发送事件。
  • 单据：组件 > 定位与操作 > 点击链接。
  • 仪表盘：区块 > 点击数据点 / 点整行 / 按列配置 > 发送事件到宿主页面，见 仪表盘的联动与钻取。
• 「三方集成」页面的「接入说明」弹窗中有「接收报表事件」代码示例。

事件（报表到宿主）

消息格式

{
  "protocol": "sight-report",
  "name": "report:loaded",
  "payload": { "elapsedMs": 812 },
  "source": { "reportId": "rpt_sales" },
  "context": { "parameters": { "year": 2025 } },
  "timestamp": 1790658966000
}

系统事件

「直接发送」的事件（report:loaded、report:error、report:print-done 和自定义事件）宿主监听即可收到；「需订阅」的过程性事件需要先向 iframe 发一条 subscribe 消息。

订阅过程性事件

const iframe = document.getElementById('report');
iframe.contentWindow.postMessage(
  { protocol: 'sight-report', type: 'subscribe', events: ['report:query-done', 'report:resize'] },
  'https://your-domain'
);
// 订阅全部：events: ['*']

订阅同时会锁定宿主 origin，此后报表发送的事件使用精确的 origin，安全性更高。未订阅时，报表用 document.referrer 的 origin 作为目标；referrer 也为空时以 * 发送。

接收事件

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://your-domain') return;      // 报表系统的部署地址
  const data = event.data;
  if (!data || data.protocol !== 'sight-report') return;

  if (data.name === 'report:loaded') {
    console.log('报表已就绪', data.payload);
  } else if (data.name === 'patient-selected') {              // 设计者配置的自定义事件
    console.log('选中患者', data.payload, '当前参数', data.context && data.context.parameters);
  }
});

注意：自定义事件名不能以 report: 开头，该前缀保留给系统事件；使用了该前缀的事件在运行时会被丢弃。

方法调用（宿主到报表）

消息格式

请求：

{ "protocol": "sight-report", "type": "invoke", "id": "req-1", "method": "setParameters", "args": [{ "year": 2025 }] }

响应（回送给发起方窗口）：

{ "protocol": "sight-report", "type": "invoke-result", "id": "req-1", "ok": true, "data": { "queried": true, "success": true } }

失败时为 { ..., "ok": false, "error": "..." }。id 必须是非空字符串，用于匹配请求与响应。invoke 只在报表运行于 iframe 内时响应，直接打开报表页不响应。

方法清单

在报表首次加载完成前，setParameters、query、reset、export、print、setSheet、continuePrint 返回 error: 'not-ready'，宿主应等 report:loaded 后重试；读取类方法始终放行，getState().loading 可作为就绪探测。不存在的方法返回 unknown method: xxx；当前报表类型不支持的方法返回 unsupported: …，不会静默成功。

打印机、份数与打印结果

宿主可以在调用时指定打印机和份数（网格与单据都支持），并通过 report:print-done 拿到这一次打印的结果，用于打印轨迹：

const { jobId } = await invoke('print', { printer: '导引单-1F', copies: 2 });
// 稍后收到：
// { name: 'report:print-done',
//   payload: { jobId, command: 'directPrintAll', mode: 'plugin', printer: '导引单-1F', copies: 2,
//              success: true, spoolJobIds: ['118'] } }

• 经 magic-print 静默打印时使用宿主传入的值，没传的项用报表「打印设置」里的配置。宿主传了 printer 时不看报表的「打印预览」开关，直接静默打印。
• 显式指定 previewPrint* 命令时弹出系统打印对话框，浏览器不接受页面指定打印机和份数，printer、copies 不生效。
• 参数不合法（份数越界、命令名未知等）时调用失败，error 以 invalid-argument: 开头。
• 工具栏触发的打印同样会发 report:print 和 report:print-done，各自带 jobId。

report:print-done 的 payload：

使用宿主 SDK sight-report-embed.js 时，旧版 SDK 也能直接调用 report.print({ printer, copies }) 并监听 report:print-done（该事件直接发送，不需要订阅）。SDK 的类型声明（sight-report-embed.d.ts）对应如下：

export type PrintCommand = 'previewPrintAll' | 'previewPrintCurrent' | 'directPrintAll' | 'directPrintCurrent'

export interface PrintOptions {
  printer?: string
  copies?: number
  command?: PrintCommand
}

export interface PrintDonePayload {
  jobId: string
  command?: PrintCommand
  mode: 'plugin' | 'dialog'
  printer: string | null
  copies: number | null
  success: boolean
  error?: string
  spoolJobIds?: string[]
  fallbackReason?: string
}

// SightReportInstance
print(commandOrOptions?: PrintCommand | PrintOptions): Promise<{ accepted: boolean; jobId: string }>

示例

页面加载后按用户所在科室过滤报表，并在查询完成后自适应 iframe 高度：

const iframe = document.getElementById('report');
const ORIGIN = 'https://your-domain';
let seq = 0;

function invoke(method, ...args) {
  return new Promise((resolve, reject) => {
    const id = 'req-' + (++seq);
    const onMsg = (e) => {
      const d = e.data;
      if (e.origin !== ORIGIN || !d || d.protocol !== 'sight-report'
          || d.type !== 'invoke-result' || d.id !== id) return;
      window.removeEventListener('message', onMsg);
      d.ok ? resolve(d.data) : reject(new Error(d.error));
    };
    window.addEventListener('message', onMsg);
    iframe.contentWindow.postMessage({ protocol: 'sight-report', type: 'invoke', id, method, args }, ORIGIN);
  });
}

window.addEventListener('message', async (e) => {
  if (e.origin !== ORIGIN || !e.data || e.data.protocol !== 'sight-report') return;
  if (e.data.name === 'report:loaded') {
    iframe.contentWindow.postMessage(
      { protocol: 'sight-report', type: 'subscribe', events: ['report:resize'] }, ORIGIN);
    await invoke('setParameters', { dept: '内科' });
  } else if (e.data.name === 'report:resize') {
    iframe.style.height = e.data.payload.height + 'px';
  }
});

注意事项

注意：一个 iframe 对应一张报表。报表内部钻取出来的子报表实例不参与宿主通道，宿主只会收到主报表的事件，也只有主报表响应 invoke。

提示：export 与 print 只表示「已受理」。导出失败只在报表页面上提示，不会发 report:error；打印的结果看 report:print-done。

提示：宿主页面使用 Vue 组件（而非 iframe）直接嵌入报表视图时，事件通过组件的 report-event 事件全量触发，不需要订阅。

相关文档

• 报表集成
• 嵌入签名与令牌
• 仪表盘的联动与钻取
• 嵌入接口清单