物可视IOTVIZ

    物可视PlayerAPI

    物可视Embedded Player允许用户将制作好的仪表盘嵌入到自己的Web应用中,并使用Player的运行时API完成仪表盘与应用的交互集成。例如,用户应用可通过Player运行时API控制数据源(tsdb)的查询时间段,或替换设计时保存在仪表盘中的JSON或CSV格式的静态数据,亦或响应仪表盘内可视化组件(Widget)的交互事件。

    嵌入示例代码

    仪表盘的示例代码可通过在仪表盘管理页中点击『生成代码』按钮获得。

    const bdIotVizPlayer = window.BDIotVizPlayer;
    const myDashboard = bdIotVizPlayer({
        containerElement,
        dashboardId: '************************',
        fillMode: 'none', // <-- Optional, Possible value: 'none', 'contain', 'cover', 'responsive'
        token: {
            type: 'embedded', // <-- Must be 'embedded'
            value: '********************************' // <-- Access Token for current dashboard
        }
    });
    myDashboard.getDashboardConfig().then(function(config){
        console.log(config); // <--- Current Dashboard Config
    });

    BDIotVizPlayer是加载 bdiotvizplayer.min.js 后,注册在BDIoTVizPlayer的全局对象,用于嵌入用户在设计期内制作的仪表盘。BDIoTVizPlayer同时也支持ES6/CommonJS/AMD式的模块化引入。

    Player的初始化参数对象

    BDIotVizPlayer在初始化时接收Javascript对象,字段描述如下表:

    字段 值类型 描述
    containerElement DOM Element 必填,用于渲染仪表盘的DOM容器节点
    dashboardId string 必填,仪表盘Id
    fillMode string 选填,可选值none, cover, fill, 默认值为none。当容器尺寸或比例与仪表盘画布设定不一致时采取的渲染方式。none:仪表盘按原比例和尺寸显示;cover:仪表盘比例不变尺寸缩放到可以填充满容器的宽或高;fill:仪表盘调整比例及缩放到填满整个容器
    token object 必填,type必须为'embedded',value为该仪表盘专用的access token,点击物可视仪表盘列表卡片的代码按钮可获取,如需要更新或回收,用户应用的服务器端可访问物可视Token API完成仪表盘专用访问Token的管理工作
    onload function 选填,仪表盘加载完毕后的回掉函数,签名为async function(api){...},传入参数对象(api)为该仪表盘的运行时API

    仪表盘运行时API

    写在前面:理论上说,所有的运行时 API 都需要在仪表盘渲染加载完成后才能够被调用。但是考虑到把这种判断推给使用者而导致用户代码复杂度的提升,我们允许 API 在仪表盘加载前调用,当然操作效果还是必须要在仪表盘加载后才能显现(例如获取属性或者更新配置等)。

    基于这样的考虑,我们把所有的 API 都设置为异步操作,即返回一个 Promise 对象,使用 then 接续后续操作。在仪表盘加载完成后调用方法,会直接返回一个满足状态(fulfilled)的 Promise,而如果在之前,则会返回一个等待状态(pending)的 Promise。总之通过对 Promise 的操作,使用者可以无需关心调用顺序。

    获取仪表盘配置 - getDashboardConfig

    用于获取当前加载仪表盘的配置信息,该方法为异步方法,默认的示例代码中即调用了该方法:

    myDashboard.getDashboardConfig().then(function (config) {
        console.log(config); // <--- Current Dashboard Config
    });

    config对象描述了当前仪表盘内所有可通过运行时API控制的对象。config对象结构如下所示:

    {
        width: number, // the width of the dashboard
        height: number, // the height of the dashboard
        dataTables: [DATATABLE], // each array item refers to a data table used in the dashboard
        widgets: [WIDGET] // each array item refers to a widget used in the dashboard
    }

    其中width和height字段代表了仪表盘画布的宽和高。 dataTables字段(array类型)包含了当前仪表盘中所使用的所有数据源(DataTable)的运行时可配置信息。widgets字段(array类型)包含了当前仪表盘中所使用的所有可视化元件(Widget)的运行时可配置信息。 DataTable对象根据所对接数据源类型的不同而不同,但基本结构如下所示:

    {
        id: '********************************', // the id of the data table
        type: 'tsdblivequery', // the type of the data table
        name: 'test', // name of the data table set in designer
        config: {...} // current configuration of the data table
    }

    其中id是该data table在仪表盘内的唯一标识,会在之后的updateDataTableConfig API中用到; type表明该data table的数据源类型,目前支持如下四种类型的数据源:

    • tsdblivequery: 数据来源于时序数据库(tsdb)的查询
    • dmsub: 数据来源于对物管理设备影子的订阅
    • staticcsv: 数据来源于用户在设计器内上传的静态csv文件
    • staticjson: 数据来源于用户在设计器内上传的静态json文件
    • simulation: 数据源来自于用户配置的仿真数据

    注:在开发仪表盘过程中绑定的数据源只定义了数据的格式。在生产环境中数据可变,不仅限于以上四种类型。

    name为用户对该数据表的命名;config为data table的当前配置,根据type的不同会有差别,请参考DataTable Config说明文档

    Widget对象描述了可视化元件的运行时可设置属性(prop)和事件(event),基本结构如下:

    {
        id:"3554e71f-6171-48df-9406-a6c6331663b2",
        name:"车联网轨迹地图",
        typeId: "46172819-9cff-4dce-ba04-5df91900a6a6",
        ver: "1.0",
        bindings: [{ // 描述组件和数据源的绑定关系
            code: 'xxx', // 绑定关系中的转换函数,定义输入和输出
            refTable: 'some-id', // 关联数据表的 id,可以用来寻找绑定的数据表的详细信息
            toProp: '/seriesMap', // 绑定的字段,如 /seriesMap 表示图表类的数据序列。其他可选值包括 /x, /y, /width, /height 等
        }],
        propsDef: [{
                name: 'center', // name of the runtime property
                validate: function () {...} // validator function
            },
            ...
        ],
        eventsDef: [{
                name: 'loadstart', // event name
                schema: JSONSchema, // json schema to describe the event payload
            },
            ...
        ]
    }

    id是该Widget在仪表盘内的唯一标识;会在与Widget相关的运行时API调用中用到; name是用户在设计仪表盘时给该Widget的命名;typeId和ver字段唯一标识了Widget的类型; propsDef与eventsDef分别包含该Widget运行时可设置的属性(prop)定义和可监听的事件(event)定义。具体的Widget的prop和event的定义请参考『组件操作指南』中的各可视化元件文档。

    更新仪表盘配置 - updateDataTableConfig

    用于运行时更新DataTable的配置。该方法为异步方法,签名为

    updateDataTableConfig(id, config).then(() => {
        // TODO HERE
    })

    id为上面提到的data table唯一标识, config为对应的数据表配置,具体信息请参考DataTable Config文档。

    例如您可以这样来更新一个静态数据源的数据(注意不要遗漏 config 内部的 source 这一层):

    myDashboard.updateDataTableConfig('4040ddbf-f977-4a4b-9428-9a6884e3622d', {
        source: [{dataObj1, dataObj2}]
    }).then(() => {
        // 如果不需要完成更新后的操作,可以不跟 then,下同
        console.log('update complete');
    });

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    await myDashboard.updateDataTableConfig('4040ddbf-f977-4a4b-9428-9a6884e3622d',{...});

    注意:DataTable配置更新后的仪表盘会即刻生效,但不会保存到物可视项目中。

    获取组件属性 - getWidgetProp

    用于获取Widget属性的当前值。该方法为异步方法,签名为

    getWidgetProp(id, prop).then(() => {
        // TODO HERE
    })

    id为上面提到的Widget的唯一标识,prop为 propsDef中对应的属性

    例如您可以这样来获取一个标签(Label)组件的颜色和文字:

    myDashboard.getWidgetProp('4040ddbf-f977-4a4b-9428-9a6884e3622d', 'color').then(color => {
        console.log(color); // <- '#333'
    });
    
    myDashboard.getWidgetProp('4040ddbf-f977-4a4b-9428-9a6884e3622d', 'text').then(text => {
        console.log(text); // <- '我是一个标签'
    });

    每个组件拥有的属性都是不同的。您可以到每个组件的文档中,“动态属性描述”这一章节来寻找它们。例如上面例子中的 color, text 就可以在 标题文本可视元件文档 中找到。

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    const text = await myDashboard.getWidgetProp('4040ddbf-f977-4a4b-9428-9a6884e3622d', 'text')

    设置组件属性 - setWidgetProp

    用于设置Widget属性的当前值。该方法为异步方法,签名为

    myDashboard.setWidgetProp(id, prop, value).then(() => {
        // TODO HERE
    })

    id为上面提到的Widget的唯一标识,prop为 propsDef中对应的属性, value为通过propsDef中给出的validate方法验证的合法值,非法的value会被忽略。

    例如您可以这样来更新一个标签(Label)组件的颜色:

    myDashboard.setWidgetProp('4040ddbf-f977-4a4b-9428-9a6884e3622d', 'color', 'white').then(() => {
        console.log('更新完成');
    });

    和获取组件属性一样,属性的列表根据组件的不同而不同。它们都可以在每个组件的文档中找到。

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    await myDashboard.setWidgetProp('4040ddbf-f977-4a4b-9428-9a6884e3622d', 'color', 'white')

    注意:Widget Prop更新后的仪表盘会即刻生效,但不会保存到物可视项目中。

    绑定组件事件 - onWidgetEvent

    用于设置对Widget属性事件的监听器(listener)。该方法为异步方法,签名为

    myDashboard.onWidgetEvent(id, prop, listener).then(() => {
        // TODO HERE
    })

    注册成功后当该事件发生时,listener会被回调,listener的签名为

    listener(event)

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    await myDashboard.onWidgetEvent('3554e71f-6171-48df-9406-a6c6331663b2', 'loadstart', console.log)

    解绑组件事件 - unWidgetEvent

    用于取消对Widget属性事件的监听。该方法为异步方法,签名为

    myDashboard.unWidgetEvent(id, prop, listener?).then(() => {
        // TODO HERE
    })

    如果传入了 listener 参数,则指定取消这一个监听;如果没有传入,则去掉所有对该事件的监听。

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    await myDashboard.unWidgetEvent('3554e71f-6171-48df-9406-a6c6331663b2', 'loadstart')

    绑定组件DOM事件 - onWidgetDOMEvent

    onWidgetEvent 只能对物可视组件预设的事件进行监听,依赖于组件内部在特定的阶段抛出对应的事件。但如果想从 DOM 层面更直接的监听事件,或者想处理组件内部并没有抛出的事件,可以使用更底层的 onWidgetDOMEvent 方法。

    myDashboard.onWidgetDOMEvent(id, eventName, listener).then(() => {
        // TODO HERE
    })

    第二个参数 eventName 可以是常规的 DOM 事件名称,例如 click, mouseover 等等。

    注册成功后当该事件发生时,listener会被回调,listener的签名为

    listener(event)

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    await myDashboard.onWidgetDOMEvent('3554e71f-6171-48df-9406-a6c6331663b2', 'click', () => {
        window.location.href = 'http://www.baidu.com'; // 按钮的简单实现
    })

    暂停数据源 - pauseDataTableSourcer

    用于暂停某些数据源的自动更新。通常的动态数据源(包括时序数据库,物影子,仿真)都带有自动更新的功能。如果想要使用 updateDataTableConfig 接口手动更新数据的话,需要先暂停自动更新的数据源。否则两方都在持续更新,会导致数据紊乱。

    静态的数据源(静态JSON,静态CSV)可以被认为永远处于暂停状态。不过仍然可以对它们调用这个方法,只是没有作用而已。

    这个方法是一个异步方法,签名为:

    myDashboard.pauseDataTableSourcer('dataTableId').then(() => {
        // TODO HERE
    });

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    await myDashboard.pauseDataTableSourcer('4040ddbf-f977-4a4b-9428-9a6884e3622d')

    您可以使用 getDashboardConfig() 接口获取仪表盘配置,从而获取您想要操作的数据源的 id。

    恢复数据源 - resumeDataTableSourcer

    用户恢复已被暂停的数据源的自动更新功能。对尚未处于暂停状态的数据源或者静态数据源调用该方法没有作用,但也不会报错。

    这个方法是一个异步方法,签名为:

    myDashboard.resumeDataTableSourcer('dataTableId').then(() => {
        // TODO HERE
    });

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    await myDashboard.resumeDataTableSourcer('4040ddbf-f977-4a4b-9428-9a6884e3622d')

    您可以使用 getDashboardConfig() 接口获取仪表盘配置,从而获取您想要操作的数据源的 id。

    获取数据源的暂停状态 - isDataTableSourcerPaused

    获取某个数据源当前是否处于暂停状态。静态数据源将一律返回 true。

    这个方法是一个异步方法,签名为:

    myDashboard.isDataTableSourcerPaused('dataTableId').then(isPaused => {
        console.log(isPaused);
        // TODO HERE
    });

    如果您的浏览器支持ES6 async/await 或者使用了 babel 的相关功能,则也可以写作:

    let isPaused = await myDashboard.isDataTableSourcerPaused('4040ddbf-f977-4a4b-9428-9a6884e3622d');

    您可以使用 getDashboardConfig() 接口获取仪表盘配置,从而获取您想要操作的数据源的 id。

    上一篇
    物可视DataTableAPI
    下一篇
    常见问题