物可视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。