嵌入式 BI 实战（二）：DIV 集成与 SDK 深度定制

前言当基础的 iframe 嵌入无法满足无缝感要求时我们需要从简单的集成迈向深度的融合。本文聚焦两类问题视觉深度定制与品牌完全自有通过 DIV 集成 样式/SDK 定制解决账号无缝对接留到第三篇用 SSO 解决赋能业务 DIY客户自助设计图表属于设计器集成文末给出入口、后续单独展开。一、场景升级消除第三方软件的违和感在企业级产品交付中客户常提出更高的要求视觉深度定制 “配色必须跟我们官网完全一致不能有任何插件感。”账号无缝对接 “用户登录了我们的 SaaS点击报表绝不能再弹出一个登录框。”品牌完全自有 “我们要把分析能力作为核心卖点界面上不能出现任何第三方 Logo。”赋能业务 DIY “能不能让客户自己在我们的系统里拖拽设计图表”针对这些苛刻要求我们需要从简单的嵌入迈向深度的融合。二、DIV 集成消灭 iframe 的外壳感iframe 虽然快但存在样式隔离和交互受限的天然弊端。Wyn 提供的 DIV 集成方案将看板直接渲染到父页面的div容器中使其成为页面一部分。实战步骤引入 SDKbashnpm install grapecity-software/wyn-integration编写渲染代码import { WynIntegration } from grapecity-software/wyn-integration; let viewer:any null; const createViewer (baseURL, token, dashboardId) { if (viewer){ viewer.destroy(); } WynIntegration.createDashboardViewer({ baseUrl: baseURL, //http://example.com:51980, token: token, defaults: { dashboardId: dashboardId, //仪表板文档ID //dp: {仪表板参数名称: [仪表板参数值]}, //例如只展示华东数据dp:{ Region:[华东] } , }, features: { actionbarItems: [focus], } }, #wyn-root).then(instance { viewer instance; }); }与第一篇衔接这里的dp和第一篇 URL 里的dp参数完全等价只是写法从拼在 URL 后面变成了放进defaults.dp。同样的{Region:[华东]}就能让不同用户看到不同数据。关键优势DIV 集成 vs iframe 集成三、样式深度定制让你的 BI 看板长在系统里DIV 集成让看板成为父页面 DOM 的一部分但默认的 Wyn 主题配色、字体、圆角等往往和你的产品风格不一致。最干净、最可维护的做法不是去逐个覆盖 CSS 类名而是直接换主题——在 Wyn 中按企业 VI 定制一套主题集成时指定使用它看板就能和宿主系统视觉统一。通过 SDK 指定主题在createViewerLite的defaults中通过theme传入主题名称即可WynIntegration.createViewerLite({ baseUrl: baseURL, token: token, defaults: { dashboardId: dashboardId, theme: your-theme-id // 在 Wyn 后台「主题管理」中创建的自定义主题 ID } }, #wyn-root);这样无需写一行 CSS看板的配色、字体、图表风格就会跟随你定义的企业主题与官网 / 业务系统保持一致。主题从哪来主题在 Wyn的「系统管理系统设置系统外观」的自定义主题进行创建和维护支持基于默认主题微调主色、辅助色、背景、字体等保存后得到一个主题 ID。后续品牌升级只要改主题所有嵌入看板自动生效比逐个改 CSS 省心得多。补充如果主题仍满足不了个别细节例如要彻底隐藏工具栏、定制某个组件再配合features开关或宿主 CSS 做精细微调即可二者叠加使用。四、SDK 深度定制从嵌入到可控拿到 viewer 实例后我们不再只是被动展示而是可以用代码主动控制看板实现与业务系统的双向联动。这正是标题中SDK 深度定制的核心含义。1. 参数联动让业务系统驱动看板第一篇讲过的千人千面在 DIV 模式下同样适用。除了初始化时通过defaults.dp传入运行时还可以用setParameterValue动态改变参数WynIntegration.createViewerLite({ baseUrl: baseURL, token: token, dashboardId: dashboardId, theme: your-theme-id // 在 Wyn 后台「主题管理」中创建的自定义主题 ID dp:{ 参数名称: [参数值]} //需要查看对应的文档的参数名称 }, #wyn-root);这样点击业务系统的区域下拉框看板就会跟着过滤无需重新创建 viewer 实例。2. 生命周期与事件回调SDK 通过回调选项暴露关键事件方便与业务系统衔接WynIntegration.createViewerLite({ baseUrl: baseURL, token: token, defaults: { dashboardId: dashboardId }, onLoaded: (docName) { console.log(看板加载完成, docName); // 可在此隐藏业务系统的 loading 状态 }, onError: (errorInfo) { console.error(看板渲染出错, errorInfo); } }, #wyn-root);3. 编程式指令viewer 实例还提供一系列方法用于更深度的交互executeCommand(option)执行下钻、切换页面、显示 / 隐藏场景等操作requestFullScreen()请求全屏getDatasets()获取当前看板使用的数据集列表destroy()销毁实例释放资源切换文档前务必先调用。注意以上为 Wyn 集成 SDK 的常用能力具体方法名与参数以你所用版本的官方文档为准。4. 进阶让客户自己设计图表赋能业务 DIY如果第一篇提到的让客户在系统里拖拽设计图表是刚需可进一步引入设计器DesignerWynIntegration.createDashboardDesigner({ backendServer: { url: baseURL, token: token }, defaults: { datasetId: 数据集ID } }, #wyn-root);设计器同样基于同一套 SDK能力更强适合自助分析平台类场景我们将在后续文章单独展开。五、结语DIV 集成是迈向深度融合的第一步。它消除了 iframe 的物理边界让 BI 看板真正成为你系统的一部分配合 SDK 的样式覆盖与编程式控制看板还能在视觉与交互上完全长在你的产品里。但这还不够——如果每个用户访问看板时还要输入一次 Wyn 的账号密码体验直接打回解放前。此外如果想让客户在自己系统里自助设计图表赋能业务 DIY还需要引入设计器Designer集成。下一篇第三篇我们将彻底解决账号问题SSO 单点登录与行级数据权限再之后第四篇会单独讲解设计器集成与自助分析赋能业务 DIY。