FxEmbed:用 Web Component 取代 iframe 的外汇行情嵌入方案
这两年做外汇行情页面,踩过的坑比写过的组件都多。最开始需求很简单:把实时汇率、K线、买卖价差嵌到现有交易系统里。我二话不说上了 iframe,结果被滚动穿透、样式隔离、跨域通信、内存泄漏挨个教做人。最后我直接从 iframe 抽离出来,自己写了个轻量嵌入组件,取名 FxEmbed(Fx 是 Foreign Exchange 的缩写,Embed 就是嵌入),专门用来把行情能力干净利落地塞进任意页面。这篇文章不是产品发布会,而是把我从设计思路到生产环境排障的完整过程都摊开来讲,适合前端工程师、量化团队和做金融信息门户的朋友参考。
1. iframe 方案的三个老毛病,逼我做了这个组件
1.1 样式隔离变成了“样式孤岛”
iframe 最大的优点也恰恰是它最大的缺点:完全隔离。你在父页面里定义好了一套字体、颜色变量、响应式布局,iframe 里的子文档一概不认识。行情图表倒是能正常渲染,但只要涉及弹窗、悬浮提示、联动筛选,iframe 内的元素就永远被框死在那个矩形里。
我做第一次集成时,需求方要求鼠标悬停在某个货币对上时,父页面右侧要同步展示这个货币对的交易信号。用 iframe 做这套联动,只能靠 window.postMessage 来来回回传消息,调试的时候还得同时打开两套 devtools。等终于调通了,用户又反馈:为什么弹出来的小窗在 iframe 边界处被截断了?因为浏览器原生 iframe 就是一块独立渲染层,子文档再高的 z-index 也越不过父文档的边界。
FxEmbed 彻底放弃 iframe 渲染,把行情 UI 作为真实 DOM 挂进页面。样式隔离用 Shadow DOM 来解决,通信直接用自定义事件 + 方法调用。这样既保留了隔离能力,又不至于和宿主页面完全断联。
1.2 性能与生命周期失控
每个 iframe 都相当于一个迷你页面,有独立的 JS 执行环境、独立的布局引擎。页面里塞三五个 iframe,在低端设备上几乎可以明显感觉到滚动掉帧。更麻烦的是 iframe 的生命周期:它自己加载自己的资源,父页面无法精确控制它内部的数据轮询和渲染调度。
有一次生产环境出现奇怪 bug:iframe 内的 WebSocket 连接已经断了,但图表还停留在最后一条数据上,用户以为行情停了。因为 iframe 内的脚本报错后没有向上抛出,父页面根本感知不到。这种黑盒状态放在投资类产品里是致命的,用户可能因为看到一条过期报价做出错误判断。
FxEmbed 的组件实例完全活在父页面运行时里,数据请求、连接状态、渲染进度都是可见、可控、可埋点的。行情连接断没断、最近一次更新是什么时候,都可以通过组件暴露的状态随时拿到。对于金融类嵌入场景,这一点比任何渲染优化都重要。
1.3 如果不用 iframe,用普通图表库行不行
可能有人会说:那你直接用 ECharts、Lightweight Charts 不就好了,何必再造轮子?我用过一段时间,发现普通图表库面向的只是“画图”,并不关心你和行情源之间的连接管理。真实业务里,你需要处理 WebSocket 重连、多货币对订阅去重、交易时区换算、价格闪烁动画、历史数据补拉……这些和 UI 无关的脏活累活,才是嵌入组件最大的价值所在。
| 方案 | 样式隔离 | 跨域通信 | 数据连接管理 | 多框架复用 | 集成成本 |
|---|---|---|---|---|---|
| iframe | 彻底隔离 | 靠 postMessage | 完全黑盒 | 任何页面都能嵌 | 低 |
| 普通图表库 | 由宿主控制 | 直接调用 | 自己写 | 需要包框架适配 | 中 |
| FxEmbed | Shadow DOM | 自定义事件 + API | 内置并暴露状态 | Web Component | 低 |
所以 FxEmbed 的定位不是“又一个图表组件”,而是一个完整的外汇行情嵌入解决方案。它把连接、渲染、交互、安全四个层面打包成一个开箱即用的组件,但又不像 iframe 那样把一切都关进黑盒。
2. FxEmbed 的核心架构:数据总线、Shadow DOM、自定义事件
2.1 组件内部模块是怎么划分的
写 FxEmbed 时,我定的第一原则是:组件内部必须分层,但不能过度设计。现在拆成了四个模块:
- DataAdapter:负责对接外部行情源,无论 REST 还是 WebSocket,统一输出归一化后的行情数据。
- Store:内存里的最新行情状态池,多个组件实例共享同一个货币对的 tick,避免重复请求。
- Renderer:把行情状态映射成 DOM,支持列表、图表、买卖盘三种视图。
- Dispatcher:处理用户点击行为,对外派发自定义事件,同时接收宿主的配置更新指令。
这四个模块是单向依赖的:Adapter 写入 Store,Store 通知 Renderer,Renderer 触发 Dispatcher,Dispatcher 调回 Adapter 做订阅变更。这样每一层都能单独测试,也方便后续做插件。
2.2 行情数据接入:从 REST 轮询到 WebSocket
行情源怎么接,往往取决于部署环境。FxEmbed 默认提供一个走 REST 的轮询适配器,你只需要实现一个返回 Promise 的 fetcher:
注意 since 参数,这是增量拉取设计。每次轮询只取上次时间戳之后的变化数据,而不是每次全量拉取,这样在高频更新场景下能显著降低带宽压力。WebSocket 模式下,内部会自动维护订阅列表,并针对断线做指数退避重连:1 秒、2 秒、4 秒、8 秒……最大间隔 30 秒。一开始我用了固定 5 秒重连,结果行情源一抖动,所有客户端像约定好了一样同时撞上去,直接把接口打爆。后来改成带随机抖动的退避策略,情况立刻缓解。
2.3 自定义事件如何穿过 Shadow DOM
很多前端对 Shadow DOM 有顾虑,觉得事件穿透、表单提交都是麻烦事。我在 FxEmbed 里做的妥协是:Shadow 内部不用冒泡事件,全部转发成宿主环境的自定义事件。比如用户点击“买入”按钮,组件内部捕获 click,然后对外派发一个名为 fx:order-request 的 CustomEvent,里面带上完整的行情上下文。
这样宿主页面永远不必关心 Shadow Tree 里的 DOM 结构,也不需要 hack 那些只读的 shadowRoot。事件协议就是组件对外暴露的 API,只要协议稳定,内部实现随便换个渲染框架都不会破坏宿主的集成。
3. 把 FxEmbed 集成到 Vue / React / 原生页面的实战步骤
3.1 安装和引入
FxEmbed 使用 Web Components 标准封装,所以理论上任何框架都能接。它不要求你从 npm 里 import 一堆 React 组件,只需要把自定义元素注册到页面里。
入口文件只需要引入一次注册逻辑:
引入之后,页面上直接写上 <fx-embed> 就可以跑起来。不过更推荐的做法是用配置对象初始化,因为这样 IDE 可以通过类型定义提醒你配置项拼写。
3.2 核心配置项说明
我把日常集成用到最多的配置项整理成一张表,方便你对照着做首次接入。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| mode | ticker / chart / depth |
ticker |
三种视图模式:行情列表、K线图、买卖盘深度 |
| symbols | string[] |
['EUR/USD'] |
需要显示的货币对 |
| theme | {color, font, border} |
亮色主题 | 支持正则校验的十六进制颜色值 |
| locale | 'zh-CN' / 'en-US' |
自动检测 | 影响价格格式化、时间显示 |
| timezone | IANA 字符串 |
浏览器时区 | 例如 'Asia/Shanghai'、'Europe/London' |
| autoSize | boolean |
false |
是否跟随容器尺寸变化自动重绘 |
| debug | boolean |
false |
开启后会在控制台输出行情事件日志 |
这里尤其要说一下 timezone。外汇市场受不同交易中心的开闭市时间影响,夏令时切换时不同的货币对有各自的交易时段。如果直接使用前端 new Date().getTimezoneOffset(),在夏令时切换的那几天会直接算错开收盘时间。我建议配置时优先写死成 IANA timezone,而不是依赖浏览器所在时区。
3.3 在 Vue 3 里的接入
Vue 3 对 Web Component 的兼容性已经很好了,直接用 ref 拿 DOM 元素即可:
注意 Vue 模板里的事件绑定语法 @fx:order-request 对自定义事件不总是可靠,所以我上面用了原生 addEventListener。这是踩过坑之后的最稳妥写法。
3.4 在 React 里的接入
React 对 Web Component 的属性传递经常有坑,尤其是配置对象这种复杂类型。我建议用 ref + 直接给 DOM 属性赋值,而不是强行转换成 React 的 props。
很多同事问我为什么不用 React 封装一层组件。原因是:封装层意味着升级版本时你要跟着改 wrapper 源码,而直接用 Web Component 只要 FxEmbed 本身不破坏事件协议,宿主代码几乎不用动。
3.5 原生页面里动态创建实例
原生 JS 里反而最简单,因为 Web Component 本身就是原生 API 的产物:
如果需要销毁,直接 el.remove(),组件内部会在 disconnectedCallback 里自动释放监听器和 WebSocket 连接。这一点比 iframe 优雅得多——你永远不会留下一个在后台悄悄跑轮询任务的孤儿节点。
4. 线上流量喂出来的六个踩坑修复记录
4.1 Safari 里 Shadow DOM 点击区域穿透
首发版本上线后,一堆用户反馈在 Safari 上点击行情列表没反应。排查发现是 Safari 对 Shadow DOM 内部的 pointer-events: auto 处理和其他浏览器不一致。某些元素在列表中显示正常,但点击位置下方的父级事件会穿透过来,导致按钮完全点击不到。
修复方案是在事件委托层加了一个显式的命中测试:在 pointerdown 里判断 event.composedPath() 是否包含目标按钮,如果没有就忽略。这个方法兼容性好,也顺手解决了未来可能的点击热区错位问题。
4.2 移动端触摸滚动卡顿
另一个高频 bug 是移动端滑动行情列表时掉帧严重。原因是我在滚动容器上监听了 touchmove 做价格高亮更新,却没有把监听器声明为 passive。每次触摸都触发滚动计算,浏览器被迫等待 JS 执行完才决定是否滚动。
修复很直接:把事件监听改成 addEventListener('touchmove', handler, { passive: true }),同时把价格更新逻辑从滚动事件里拿出来,改成一个 30fps 的独立渲染调度。渲染频繁的任务绝不能和滚动事件直接绑定,这是移动端嵌入组件的基本功。
4.3 时区与夏令时导致的开收盘时间错位
这个问题在上线后第一次换季时集中爆发。我当时存的交易时间段用了固定 UTC 偏移,例如伦敦开盘是 UTC+1,但一到英国夏令时切换,整体偏移就变了,导致显示的开盘时间早了一个小时。国外用户和国内用户看到的行情时间出现明显矛盾。
修复方法是指定用 IANA 时区计算每一天的交易时段,而不是自己维护偏移表。代码里引入 date-fns-tz 把本地时间转换到目标时区后,再判断当前日期是否落在夏令时区间,历史数据也同样处理。现在用户看到的开收盘时间,跟交易所本地时间完全一致。
4.4 WebSocket 断线重连风暴
行情服务不可能永远不抖动。我第一次做生产版本时,断线后所有客户端都按固定 2 秒重连,结果服务恢复的瞬间数据库连接被打满,故障被放大了好几倍。后来改成指数退避加随机抖动,逻辑很简单:
同时增加了一个前端熔断:连续重连 5 次失败后,不再自动重连,而是让组件显示“行情已断开”状态,并抛出一个 fx:connection-status 事件给宿主页面。这比无脑重连体面得多。
4.5 图表实例内存泄漏
用户反馈长时间开着行情页面,内存从 80MB 一路涨到 400MB。排查后发现是 ResizeObserver 没有在图表销毁时解除,导致循环引用一直存在。fx-embed 里我封装了一个 createResizeObserver 的 helper,在 disconnectedCallback 里统一清理 Observer、Canvas、WebSocket 和定时器。
现在任何使用 FxEmbed 的页面上,反复创建和销毁组件实例,内存曲线基本是一条平线。这也是从 iframe 迁移过来的最大收益之一——你能真正管理生命周期,而不是对着 iframe 的内部状态束手无策。
4.6 多实例情况下主题变量互相污染
同一个页面放了四个 FxEmbed,自定义主题后发现组件之间样式串色。原因是我把主题变量挂到了 :host 上,但 CSS 变量在文档层仍然有继承穿透。修复方式是把所有主题变量放进 Shadow Root 里的一个封闭样式表,并用组件名称做前缀,例如 --fx-embed-accent-color。这样即使同一个页面挂了十几个组件,也不会互相干扰。
5. 生产环境安全、性能和按需加载的取舍
5.1 传给组件的任何内容都要先 sanitize
外汇行情这种数据来自第三方接口,你不能保证对方不会在字段里塞入一段 HTML 或脚本。FxEmbed 在渲染所有外部字符串时,强制经过一个内置 sanitize 白名单。只允许 <span>、<b>、<i> 这类纯展示标签,<script>、<iframe>、on* 事件属性一律剔除。如果你要传到组件里的自定义价格也有类似的注入风险,建议在宿主侧再包一层 DOMPurify,双保险总比事后删数据强。
5.2 按需加载让首屏体积少了一半
FxEmbed 的完整包包含了图表引擎、WebSocket 连接管理、交易所历史数据解析等模块。如果你只用 ticker 视图,根本不需要加载 K 线渲染引擎。所以在构建配置上做了模块拆分:
fx-embed/ticker:仅行情列表fx-embed/chart:包含图表引擎fx-embed/websocket:附加 WebSocket 通信层
项目默认暴露的是自动模式,会按配置里的 mode 动态 import 对应模块。首屏只加载 ticker 模块时,gzip 后大约只有 18KB,这对一个嵌入式组件来说已经很轻了。
5.3 同页面多实例尽量共享数据总线
如果同一个页面出现多个 <fx-embed>,默认每个实例都会创建自己的数据连接,那显然很浪费。我增加了一个模块级的 Store,相同货币对只保留一份行情数据,所有组件实例监听同一份状态更新。这种方式在门户页面里特别有效:一个页面上挂着汇率列表、K线图、交易深度三个组件,但实际只开一个 WebSocket 连接。
5.4 实测性能对比
我把 iframe 方案和 FxEmbed 在同一个页面上做了基准测试:页面里同时嵌入 2 个行情组件,持续运行 30 分钟后,iframe 方案总内存占用约 420MB,而 FxEmbed 只有 130MB 左右。在低端安卓手机上,滚动的帧率也从 35fps 提升到 55fps 附近。嵌入组件的下一步,永远是控制内存而不是炫渲染效果。
6. 从 FxEmbed 沉淀的几个嵌入式组件设计原则
6.1 嵌入式组件是“共享运行时”,不是“隔离上下文”
iframe 的思路是把一切都装进黑盒,对外只留一个小窗口。而真实业务需要的嵌入式组件,更像是页面里一个拥有自己 CSS 环境的邻居:你可以不看他,但他需要能和你打招呼、借东西、响应你的要求。Web Component 加上事件协议,正好提供了这种既隔离又协作的平衡。
6.2 默认值要服务 80% 的普通场景,但必须留 escape hatch
首次集成的体验非常重要。FxEmbed 的默认配置一定是“无需任何配置就能看到一组实时 EUR/USD 行情”,这样用户拿到手就有正反馈。但如果你需要接入自建行情源、自定义价格精度、接第三方图表库,组件必须提供完整可覆盖的接口,而不是把用户锁死在一套预设里。
6.3 嵌入组件一定要内置可观测性
我在 FxEmbed 里加了一个 debug 模式。开启后会把组件内部的数据请求、连接状态、渲染调度、事件派发全部打印到浏览器控制台。很多排查问题的时候,宿主手写的代码和组件内部的运行状态对不上,有了这套日志就能快速定位是对接问题还是组件 bug。生产环境通常关闭 debug,但保留 fx:lifecycle 事件供业务方做埋点。
最后分享一个我做嵌入组件的个人经验:先定义事件协议,再画 UI。无论是 FxEmbed 还是别的嵌入式组件,最容易返工的地方就是对外的数据协议。先把“宿主能调我什么”“我能向宿主通知什么”定下来,再做界面和交互,后面基本不会推倒重来。如果你现在正被各种嵌入需求折磨,不妨试试把组件做成 Web Component,让真正的 DOM 元素替你把脏活扛下来。