前言

当基础的 iframe 嵌入无法满足"无缝感"要求时，我们需要从简单的"集成"迈向深度的"融合"。

一、场景升级：消除第三方软件的"违和感"

在企业级产品交付中，客户常提出更高的要求：

• 视觉深度定制： "配色必须跟我们官网完全一致，不能有任何插件感。"

• 账号无缝对接： "用户登录了我们的 SaaS，点击报表绝不能再弹出一个登录框。"

• 品牌完全自有： "我们要把分析能力作为核心卖点，界面上不能出现任何第三方 Logo。"

• 赋能业务 DIY： "能不能让客户自己在我们的系统里拖拽设计图表？"

针对这些苛刻要求，我们需要从简单的"嵌入"迈向深度的"融合"。

二、DIV 集成：消灭 iframe 的"外壳感"

iframe 虽然快，但存在样式隔离和交互受限的天然弊端。Wyn 提供的 DIV 集成方案，将看板直接渲染到父页面的 <div> 容器中，使其成为页面一部分。

实战步骤

1. 引入 SDK

bash

npm install @grapecity-software/wyn-integration

2. 编写渲染代码

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;
    });
}

关键优势：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 省心得多。

四、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()：销毁实例，释放资源（切换文档前务必先调用）。

4. 进阶：让客户自己设计图表（赋能业务 DIY）

如果第一篇提到的"让客户在系统里拖拽设计图表"是刚需，可进一步引入设计器（Designer）：

WynIntegration.createDashboardDesigner({
    backendServer: { url: baseURL, token: token },
    defaults: { datasetId: "数据集ID" }
}, '#wyn-root');

设计器同样基于同一套 SDK，能力更强，适合"自助分析平台"类场景，我们将在后续文章单独展开。

五、结语

DIV 集成是迈向"深度融合"的第一步。它消除了 iframe 的物理边界，让 BI 看板真正成为你系统的一部分；配合 SDK 的样式覆盖与编程式控制，看板还能在视觉与交互上完全"长"在你的产品里。

但这还不够——如果每个用户访问看板时还要输入一次 Wyn 的账号密码，体验直接打回解放前。此外，如果想让客户在自己系统里自助设计图表（赋能业务 DIY），还需要引入设计器（Designer）集成。

下一篇（第三篇），我们将彻底解决账号问题：SSO 单点登录与行级数据权限；再之后（第四篇）会单独讲解设计器集成与自助分析（赋能业务 DIY）。