9.1. 看板对象

addChart(chart)

功能：将一个图表添加至看板。

参数：

• chart
  图表对象

返回值：无

batchSetDataSetParamValues(sourceData, batchSet, sourceValueContext)

功能：批量设置图表数据集参数值。

参数：

• sourceData
  要设置的源参数值对象，格式为：
  { 源参数名 : 源参数值, …}
  或者
  { getValue: function(name){ return …; } }
• batchSet
  批量设置对象
• sourceValueContext
  可选，传递给图表数据集参数索引对象的value函数sourceValueContext参数的对象， 如果为数组，则传递多个参数，默认为sourceData。

返回值： 批量设置的图表对象数组

批量设置对象格式为：

{
  //必选，要设置的目标图表元素ID、图表实例ID、charts数组索引，或者它们的数组
  target: "..."、["...", ...],
  //可选，要设置的参数值映射表，没有则不设置任何参数值
  data:
  {
    源参数名 : 图表数据集参数索引对象、[ 图表数据集参数索引对象, ... ],
    ...
  }
}

上述源参数名可以是简单参数名，例如：”name”、”value”， 也可以是属性路径，例如：”order.name”、”[0].name”、”[‘order’].product.name”

图表数据集参数索引对象用于确定源参数值要设置到的目标图表数据集参数，格式为：

{
  //可选，目标图表在批量设置对象的target中的索引数值，默认为：0
  chart: ...,
  //可选，目标图表数据集数组的索引数值，默认为：0
  dataSet: ...,
  //可选，目标图表数据集的参数数组索引/参数名，默认为：0
  param: ...,
  //可选，自定义源参数值处理函数，返回要设置的目标参数值
  //sourceValue 源参数值
  //sourceValueContext 源参数值上下文对象
  value: function(sourceValue, sourceValueContext){ return ...; }
}

或者，可简写为上述对象的param属性值

charts

功能：看板包含的所有图表对象数组。

getAllCharts()

功能：获取看板包含的所有图表。

参数：无

返回值：图表对象数组

getChart(chartInfo)

功能：获取指定标识的图表。

参数：

• chartInfo
  图表标识： 图表元素ID、 图表实例ID、 charts数组索引

返回值：图表对象，没找到则是null

getChartIndex(chartInfo)

功能：获取指定标识的图表在charts中的索引。

参数：

• chartInfo
  图表标识： 图表元素ID、 图表实例ID、 charts数组索引

返回值：索引数值，没找到则是-1

init()

功能：初始化看板。

参数：无

返回值：无

看板页面加载时，会自动调用此函数，此后，不允许再次调用。

isHandlingCharts()

功能：判断看板是否正在监视处理它包含的所有图表。

参数：无

返回值：true 是；false 否

关于看板监视处理图表的详细说明，请参考startHandleCharts()说明。

isWaitForRender(chart)

功能：判断指定图表是否在等待渲染。

参数：

• chart
  看板包含的某个图表

返回值：true 是；false 否

如果chart.statusPreRender()为true， 则表明它在等待渲染。

startHandleCharts() 依据此函数返回值决定是否执行chart.render()。

isWaitForUpdate(chart)

功能：判断指定图表是否在等待更新数据。

参数：

• chart
  看板包含的某个图表

返回值：true 是；false 否

如果chart.statusRendered()为true、 或者chart.statusPreUpdate()为true、 或者chart.statusUpdated()为true且 chart.updateInterval大于-1， 则表明它在等待更新数据。

startHandleCharts() 依据此函数返回值决定是否执行chart.update()。

listener(listener)

功能：获取/设置看板监听器。

参数：

• listener
  可选，要设置的监听器对象，格式与dg-dashboard-listener相同

返回值：要获取的看板监听器

loadChart(element, chartWidgetId, ajaxOptions)

功能：异步加载图表。

参数：

• element
  用于渲染图表的HTML元素、Jquery对象
• chartWidgetId
  要加载的图表部件ID，含义同dg-chart-widget
• ajaxOptions
  选填参数，可以是图表加载成功回调函数：
  function(chart){ … }
  也可以是加载图表的Jquery ajax请求配置项：
  { success: function(chart){ … }, error: function(jqXHR, textStatus, errorThrown){ … } }
  注意：如果图表加载成功回调函数、ajax请求配置项的success函数返回false，则加载的图表对象不会被加入看板中。

返回值：无

refreshData(chartInfo)

功能：刷新图表数据。

参数：

• chartInfo
  图表标识： 图表元素ID、 图表实例ID、 charts数组索引

返回值：无

参考chart.refreshData()。

removeChart(chartInfo, doDestory)

功能：删除图表。

参数：

• chartInfo
  图表标识： 图表元素ID、 图表实例ID、 charts数组索引
• doDestory
  可选，是否销毁图表，true 销毁；false 不销毁，默认为true

返回值：删除的图表对象，没找到则是null

render()

功能：渲染看板。

参数：无

返回值：无

看板页面加载时，会自动调用此函数，此后，不允许再次调用。

renderContext

功能：渲染上下文。

格式：

{
  //渲染上下文属性集
  attributes:
  {
    //内置图表主题，格式与dg-chart-theme相同
    chartTheme : { ... },
    //内置看板主题
    dashboardTheme :
    {
      //主题名
      name: "...",
      //前景色
      color: "...",
      //背景色
      backgroundColor: "...",
      //边框颜色
      borderColor: "...",
      ...
    },
    //应用上下文
    webContext:
    {
      //应用根路径
      contextPath: "...",
      //异步加载图表的服务端URL
      loadChartURL: "...",
      //更新看板数据的服务端URL
      updateDashboardURL: "..."
    },
    ...
  }
}

另外，打开看板展示页面时的URL传入的参数也会写入它的attributes内，详细参考 传入看板参数章节。

renderContextAttr(attrName, attrValue)

功能：获取/设置渲染上下文属性值。

参数：

• attrName
  属性名
• attrValue
  可选，要设置的属性值

返回值：要获取的上下文属性值

renderForm(form, config)

功能：将指定表单元素渲染为看板表单。

参数：

• form
  要渲染的<form>表单元素、Jquery对象
• config
  可选，看板表单配置对象，格式与dg-dashboard-form相同， 默认取<form>表单元素的dg-dashboard-form属性值

返回值：无

resizeAllCharts()

功能：重新调整所有图表内容的尺寸，使它们与图表元素的尺寸保持一致。

参数：无

返回值：无

参考chart.resize()。

resizeChart(chartInfo)

功能：重新调整指定图表内容的尺寸，使它与图表元素的尺寸保持一致。

参数：

• chartInfo
  图表标识： 图表元素ID、 图表实例ID、 charts数组索引

返回值：无

参考chart.resize()。

startHandleCharts()

功能：开始监视处理看板的所有图表，循环查看它们的状态，执行相应操作：
如果isWaitForRender(chart)， 则执行chart.render()；
如果isWaitForUpdate(chart)， 则从服务端获取更新的数据，然后执行chart.update()。

参数：无

返回值：无

看板页面加载时，会自动调用此函数。

stopHandleCharts()

功能：停止监视处理看板的所有图表。

参数：无

返回值：无

调用此函数后，可再次调用startHandleCharts()开始监视处理。

看板涉及图表刷新类的功能（比如： 图表联动、 异步加载图表、 刷新图表数据、 图表交互设置 等等）都依赖看板监视处理逻辑，调用此函数后，它们都将不起作用。