所有文档

          物可视 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
          下一篇
          常见问题