Skip to content

自定义元素(不用 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。

接下来 ​

给 AI 用的纯文本索引在 /llms.txt,每篇原文在 /md/ 下。