文档中心

物可视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对象，字段描述如下表:

仪表盘运行时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。