深色模式
自定义元素(不用 iframe)
第二种嵌入形态:引一个脚本,写一个标签。报表直接画在你们页面里,没有 iframe。
html
<script type="module" src="https://report.example.com/embed.js"></script>
<conch-report report-id="r260922123456" params='{"month":"2026-08"}'></conch-report>就这两行。高度自己跟着内容走,不用监听消息去调;条件用属性传,或者拿到元素调方法。
跟 iframe 那种比,什么时候用哪个
两种形态的能力完全一样——同一张报表、同一套筛选条件、同样能穿透和导出。差别只在「画在哪」:
| iframe | 自定义元素 | |
|---|---|---|
| 宿主要做的事 | 写一个 <iframe> | 引一个脚本 + 写一个标签 |
| 高度 | 自己监听 height 消息去调 | 不用管,元素跟着内容长 |
| 改条件 | postMessage | 改属性,或调 setParams() |
| 打印 / 导出 PDF | 只打印报表 | 打印的是整个宿主页面(报表在其中) |
| 浏览器要求 | 都支持 | 需要支持 Shadow DOM 与 ES 模块(Chrome / Edge / Safari / Firefox 现行版本都支持,IE 不行) |
| 页面上放几张 | 几个 iframe 就几份运行时 | 共用一份运行时,页面更轻 |
选择建议:宿主是老系统、或者只想少写代码,用 iframe;宿主是现代前端项目、一页要摆好几张报表、或者希望报表跟页面一起滚动,用自定义元素。
属性
属性名和 链接参数 一一对应,语义完全一样。
| 属性 | 说明 |
|---|---|
report-id | 报表 id,必填 |
version | 看哪一版,默认当前发布版 |
lock | 只读的筛选条件,逗号分隔;all 表示全部锁住 |
chrome | 写 0 去掉报表自带的页头(标题、版本、刷新、导出) |
params | 筛选条件,JSON 对象 |
theme | 设计令牌覆盖,JSON 对象或 名:值,名:值 |
html
<conch-report
report-id="r260922123456"
params='{"month":"2026-08","store":["S001","S002"]}'
lock="month"
chrome="0"
></conch-report>params 写的是真正的 JSON
链接参数只能拼字符串,属性里可以直接写数组、数字、null。日期区间写 ["2026-01-01","2026-03-31"],数字区间写 [100,500],null 表示不限。
改 report-id、version、lock、chrome 等于换了另一张报表,元素会重新打开;改 params、theme 是热更新,不重新加载。
登录凭证
报表服务开了鉴权时,给元素设 tokenProvider(返回凭证的异步函数),报表按需调用:
js
document.querySelector('conch-report').tokenProvider = async () =>
(await fetch('/my-api/report-token').then((r) => r.json())).token凭证从宿主后端换来,详见登录身份与数据范围。同一页上的几个元素共用一个凭证来源。
方法
js
const el = document.querySelector('conch-report')
el.setParams({ month: '2026-07' }) // 改筛选条件,自动重新取数
el.refresh() // 按当前条件重新取一次数
el.setTheme({ primary: '#2c6ecb' }) // 换设计令牌
el.params // 读当前条件setParams 只写要改的那几个条件,没写的保持原样。
事件
事件从元素上冒泡出来,event.detail 里是内容。
| 事件 | 什么时候发 | detail |
|---|---|---|
conch-ready | 报表打开并渲染完 | id、title、version |
conch-params | 筛选条件变了(人改的或代码改的) | params 当前全部条件的值 |
conch-error | 报表打不开(没发布、没权限、服务不通) | message |
js
el.addEventListener('conch-ready', (e) => {
console.log('打开了', e.detail.title, e.detail.version)
})
el.addEventListener('conch-params', (e) => {
// 把条件写回地址栏,用户刷新页面还能回到同一个筛选状态
history.replaceState(null, '', '?month=' + e.detail.params.month)
})样式不会互相干扰
报表画在 Shadow DOM 里,这意味着:
- 你们系统的全局 CSS(reset、UI 框架样式、
* { box-sizing }之类)不会渗进报表把版式弄坏; - 报表自己的样式也不会漏出去影响你们的页面。
要让报表跟你们系统一个配色,走设计令牌——写在标签上,或者用 setTheme():
html
<conch-report report-id="r2609..." theme='{"primary":"#b8453c","bg":"#ffffff"}'></conch-report>令牌清单见外观与主题。元素本身是个块级元素,宽高、外边距按你们页面的常规写法控制即可:
css
conch-report { display: block; max-width: 1200px; margin: 0 auto; }一页放几张
每个元素自己一份状态,互不干扰——条件各改各的,数据各取各的:
html
<conch-report report-id="r2609...01" params='{"month":"2026-08"}'></conch-report>
<conch-report report-id="r2609...02" params='{"month":"2026-08"}'></conch-report>运行时只加载一份,第二张开始几乎没有额外开销。
在框架里用
原生自定义元素,各框架都直接支持。
Vue 3——告诉编译器 conch-report 不是 Vue 组件,别去解析它:
js
// vite.config.js
export default {
plugins: [vue({
template: { compilerOptions: { isCustomElement: (tag) => tag === 'conch-report' } },
})],
}vue
<template>
<conch-report ref="report" report-id="r260922123456" @conch-params="onParams" />
</template>
<script setup>
import { ref, watch } from 'vue'
const report = ref()
const month = ref('2026-08')
watch(month, (m) => report.value?.setParams({ month: m }), { immediate: true })
function onParams(e) { console.log(e.detail.params) }
</script>React(19 起原生支持自定义元素的属性与事件):
jsx
import { useEffect, useRef } from 'react'
export function Report({ month }) {
const ref = useRef(null)
useEffect(() => { ref.current?.setParams({ month }) }, [month])
useEffect(() => {
const el = ref.current
const onReady = (e) => console.log('打开了', e.detail.title)
el.addEventListener('conch-ready', onReady)
return () => el.removeEventListener('conch-ready', onReady)
}, [])
return <conch-report ref={ref} report-id="r260922123456" />
}React 18 及更早版本不会把对象属性传给自定义元素,条件一律用 setParams() 传,别写在 JSX 属性上。
一份能直接打开的最小例子
存成 .html 双击就能看:
html
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8" />
<title>经营看板</title>
<script type="module" src="https://report.example.com/embed.js"></script>
<style>
body { margin: 0; font-family: system-ui; }
conch-report { display: block; max-width: 1200px; margin: 0 auto; }
</style>
</head>
<body>
<h2 style="padding:16px 20px;margin:0">经营看板</h2>
<label>月份:<input type="month" value="2026-08" oninput="setMonth(this.value)" /></label>
<conch-report id="report" report-id="r260922123456" params='{"month":"2026-08"}' chrome="0"></conch-report>
<script>
const el = document.getElementById('report')
function setMonth(month) { el.setParams({ month }) }
el.addEventListener('conch-ready', (e) => console.log('报表已打开', e.detail.title, e.detail.version))
el.addEventListener('conch-error', (e) => console.warn('报表打不开', e.detail.message))
</script>
</body>
</html>排查
标签在那儿但什么都没有 —— 脚本没加载成功。embed.js 必须用 <script type="module"> 引,且报表服务的地址要能从用户浏览器访问到(服务地址是脚本自己的来源推出来的,不用另外配)。打开浏览器控制台看网络请求。
报表里说「还没有指定报表」 —— report-id 没写或写空了。
条件没生效 —— params 属性必须是合法的 JSON 对象;写坏了控制台会有一句提示,报表按没传条件打开。另外条件 id 要和报表筛选栏里的对得上,对不上报表顶部会列出来。
Vue 项目里报 "Failed to resolve component: conch-report" —— 按上面配 isCustomElement。
