9.2. 图表对象

autoResize(auto)

功能：获取/设置图表是否自动调整大小。

参数：

• auto
  可选，设置是否自动调整尺寸，true 自动调整；false 不自动调整，默认值为false。

返回值：获取操作结果，true 自动调整；false 不自动调整

bindLinksEventHanders(links)

功能：为指定图表联动设置绑定事件处理函数，绑定后即可支持图表联动功能。

参数：

• links
  图表联动设置，格式参考dg-chart-link

返回值：绑定的事件处理函数对象数组，格式为：
[ { eventType: “…”, eventHandler: function(chartEvent){ … } }, … ]

此函数应在图表处于活跃状态时调用。

chartDataSetAt(index)

功能：获取指定索引的图表数据集对象。

参数：

• index
  chartDataSets数组中的索引

返回值：图表数据集对象；没找到则是null

chartDataSetFirst()

功能：获取chartDataSets数组的第一个图表数据集对象。

参数：无

返回值：图表数据集对象；没找到则是null

chartDataSetName(chartDataSet)

功能：获取指定图表数据集对象的名称，它首先取chartDataSet.alias，如果为空，则取chartDataSet.dataSet.name。

参数：

• chartDataSet
  图表数据集对象

返回值：名称字符串

chartDataSets

功能：图表数据集对象数组，结构为：[ 图表数据集对象, 图表数据集对象, … ]

图表数据集对象 结构为：

{
  //数据集别名
  alias: "...",
  //数据集
  dataSet: 数据集对象,
  //数据集初始参数值映射表：参数名 -> 参数值
  paramValues:{ ... },
  //数据集属性标记映射表：数据集属性名称 -> 标记名数组
  propertySigns:
  {
    "..." : ["...", ...],
    ...
  }
}

数据集对象 结构为：

{
  //ID
  id: "...",
  //名称
  name: "...",
  //参数数组
  params:
  [
    {
      //参数名
      name: "...",
      //参数类型："STRING" 字符串；"BOOLEAN" 布尔值；"NUMBER" 数值
      type: "...",
      //是否必填，值为：true、false
      required: ...,
      //参数描述
      desc: "..."
    },
    ...
  ],
  //属性数组，即数据集查询结果列信息数组
  properties: [ 数据集属性对象, ... ]
}

数据集属性对象 结构为：

{
  //名称
  name: "...",
  //类型："STRING" 字符串；"BOOLEAN" 布尔值；"INTEGER" 整数；"DECIMAL" 小数；
  //"DATE" 日期；"TIME" 时间；"TIMESTAMP" 时间戳
  type: "...",
  //标签名，可能为null
  label: "..."
}

chartDataSetsNonNull()

功能：获取所有图表数据集对象的数组。

参数：无

返回值：图表数据集对象数组

customChartRenderer()

功能：获取/设置图的自定义图表渲染器， 自定义图表渲染器可以重写图表内置的图表渲染器逻辑。

参数：无

返回值：要获取的自定义图表渲染器，没有则是null

dashboard

功能：图表所在的看板对象

dataSetParamValue(chartDataSet, name, value)

功能：获取/设置指定数据集单个参数值。

参数：

• chartDataSet
  图表数据集对象、 图表数据集对象数组索引
• name
  参数名（图表数据集对象的dataSet.params元素的name属性值）、
  参数索引（图表数据集对象的dataSet.params数组索引）
• value
  可选，要设置的参数值

返回值：要获取的参数值

dataSetParamValues(chartDataSet, paramValues)

功能：获取/设置指定数据集全部参数值。

参数：

• chartDataSet
  图表数据集对象、 图表数据集对象数组索引
• paramValues
  可选，要设置的参数值，格式为：{ 参数名 : 参数值, … }
  其中，参数名为图表数据集对象的dataSet.params元素的name属性值

返回值：要获取的全部参数值，格式为：{ 参数名 : 参数值, … }

dataSetPropertiesOfSign(chartDataSet, signName)

功能：获取指定标记的数据集属性对象数组。

参数：

• chartDataSet
  图表数据集对象
• signName
  标记名，图表数据集对象的propertySigns中的标记名数组元素

返回值：数据集属性对象数组

dataSetPropertyLabel(dataSetProperty)

功能：获取指定数据集属性对象的标签名，此方法先获取它的label值，如果没有，则获取name值。

参数：

• dataSetProperty
  数据集属性对象

返回值：标签名字符串

dataSetPropertyOfSign(chartDataSet, signName)

功能：获取指定标记的数据集属性对象。

参数：

• chartDataSet
  图表数据集对象
• signName
  标记名，图表数据集对象的propertySigns中的标记名数组元素

返回值：数据集属性对象

destroy()

功能：销毁图表，释放图表占用的资源、恢复图表HTML元素初值。

参数：无

返回值：无

销毁后，图表将处于已销毁状态。

disableSetting(disable)

功能：获取/设置图表是否禁用交互设置功能。

参数：

• disable
  可选，设置是否禁用交互设置功能，true 禁用；false 不禁用，默认值为false。

返回值：获取操作结果，true 禁用；false 不禁用

设置操作只在render()被调用之前起作用。

doRender()

功能：调用plugin.chartRenderer.render()函数执行图表渲染。

参数：无

返回值：无

doUpdate(results)

功能：调用plugin.chartRenderer.update()函数执行更新图表数据操作。

参数：

• results
  数据集结果对象数组

返回值：无

echartsInit(options)

功能：Echarts图表支持函数：初始化图表的Echarts实例对象。

参数：

• options
  Echarts图表选项

返回值：Echarts实例对象

echartsInstance(instance)

功能：Echarts图表支持函数：获取/设置图表的Echarts实例对象。

参数：

• instance
  可选，要设置的Echarts实例对象

返回值：要获取的Echarts实例对象

echartsLoadMap(name, callback)

功能：Echarts图表支持函数：加载指定名称的echarts地图JSON，并在完成后执行回调函数。

参数：

• name
  要加载的地图名称
• callback
  可选，加载完成回调函数，格式为：function(name){ … }

返回值：无

echartsMapRegistered(name)

功能：Echarts图表支持函数：判断指定名称的Echarts地图是否已经加载注册过而无需再加载。

参数：

• name
  地图名称

返回值：true 已加载注册过；false 未加载过

echartsOptions(options)

功能：Echarts图表支持函数：设置图表Echarts实例的图表选项。

参数：

• options
  Echarts图表选项

返回值：无

echartsThemeName(themeName)

功能：Echarts图表支持函数：获取/设置图表的Echarts主题名。

参数：

• themeName
  可选，要设置的且已注册的Echarts主题名

返回值：要获取的主题名称，没有则是null

设置操作只在render()被调用之前起作用。

element()

功能：获取图表元素DOM对象。

参数：无

返回值：DOM对象

elementId

功能：图表元素ID，即图表元素的id属性值， 如果图表元素未设置id属性，那么在看板页面加载时，系统会为图表元素随机设置一个id属性值。

elementJquery()

功能：获取图表元素的Jquery对象。

参数：无

返回值：Jquery对象

eventBindHandlerDelegation(eventType, eventHanlder, eventHandlerDelegation, delegationBinder)

功能：图表事件支持函数：绑定图表事件处理函数代理。 图表事件处理通常由内部组件（比如Echarts）的事件处理函数代理，在代理函数中构建图表事件对象，然后调用图表事件处理函数。

参数：

• eventType
  要绑定的事件类型，比如：”click”、”mouseover”
• eventHanlder
  图表事件处理函数，格式为：function(chartEvent){ … }
• eventHandlerDelegation
  图表事件处理函数代理，负责构建图表事件对象（chartEvent）并调用eventHanlder
• delegationBinder
  内部组件的代理事件绑定器，格式为：
  { bind: function(chart, eventType, eventHandlerDelegation){ … } }

返回值：无

此函数应在图表处于活跃状态时调用。

eventData(chartEvent, data)

功能：图表事件支持函数：获取/设置图表事件对象的数据（chartEvent.data）。

参数：

• chartEvent
  图表事件对象
• data
  可选，要设置的数据

返回值：要获取的数据

eventHandlers(eventHandlers)

功能：获取/设置图表事件处理函数数组。

参数：

• eventHandlers
  可选，要设置的图表事件处理函数数组，格式为：
  [ { eventType: “…”, eventHandler: function(chartEvent){ … } }, … ]

返回值：要获取的图表事件处理函数数组，没有则是null

设置操作只在render()被调用之前起作用。

eventNewEcharts(eventType, echartsEventParams)

功能：图表事件支持函数：创建Echarts图表的图表事件对象。

参数：

• eventType
  事件类型，比如：”click”、”mouseover”
• echartsEventParams
  Echarts规范的事件处理函数参数对象（params），具体参考Echarts官方文档

返回值：图表事件对象

之后还应设置其 eventData()、 eventOriginalData()、 eventOriginalChartDataSetIndex()、 eventOriginalResultDataIndex()。

eventNewHtml(eventType, htmlEvent)

功能：图表事件支持函数：创建HTML图表的图表事件对象。

参数：

• eventType
  事件类型，比如：”click”、”mouseover”
• htmlEvent
  HTML事件对象

返回值：图表事件对象

之后还应设置其 eventData()、 eventOriginalData()、 eventOriginalChartDataSetIndex()、 eventOriginalResultDataIndex()。

eventOriginalChartDataSetIndex(chartEvent, originalChartDataSetIndex)

功能：图表事件支持函数：获取/设置图表事件对象的原始图表数据集索引（chartEvent.originalChartDataSetIndex）。

参数：

• chartEvent
  图表事件对象
• originalChartDataSetIndex
  可选，要设置的原始图表数据集索引

返回值：要获取的原始图表数据集索引

eventOriginalData(chartEvent, originalData)

功能：图表事件支持函数：获取/设置图表事件对象的原始数据（chartEvent.originalData）。

参数：

• chartEvent
  图表事件对象
• originalData
  可选，要设置的原始数据

返回值：要获取的原始数据

eventOriginalResultDataIndex(chartEvent, originalResultDataIndex)

功能：图表事件支持函数：获取/设置图表事件对象的原始结果数据索引（chartEvent.originalResultDataIndex）。

参数：

• chartEvent
  图表事件对象
• originalResultDataIndex
  可选，要设置的原始结果数据索引

返回值：要获取的原始结果数据索引

eventUnbindHandlerDelegation(eventType, eventHanlder, delegationUnbinder)

功能：图表事件支持函数：为图表解绑事件处理函数代理。

参数：

• eventType
  要绑定的事件类型，比如：”click”、”mouseover”
• eventHanlder
  图表事件处理函数，格式为：function(chartEvent){ … }
• delegationUnbinder
  内部组件的代理事件解绑器，格式为：
  { unbind: function(chart, eventType, eventHandlerDelegation){ … } }

返回值：无

此函数应在图表处于活跃状态时调用。

extValue(name, value)

功能：获取/设置图表扩展属性值。 在destroy()调用后，图表的所有扩展属性值都将被清除， 之后则允许再次调用render()重新渲染图表， 因此，影响重新渲染图表逻辑的扩展属性值都应该使用此函数设置/获取。

参数：

• name
  扩展属性名
• value
  可选，要设置的扩展属性值

返回值：要获取的扩展属性值

getDataSetParamValues(chartDataSet)

功能：获取指定图表数据集对象的所有参数值。

已弃用，请使用dataSetParamValues()函数。

getUpdateResults()

功能：获取此次更新图表的结果数据。

参数：无

返回值：数据集结果对象数组，没有则是null

handleChartEventLink(chartEvent, links)

功能：处理指定图表事件的图表联动操作。

参数：

• chartEvent
  图表事件对象
• links
  图表联动设置，格式参考dg-chart-link

返回值：无

此函数应在图表处于活跃状态时调用。

hasParamDataSet()

功能：判断图表是否有参数化数据集。

参数：无

返回值：true 有；false 无

id

功能：图表实例ID。看板页面加载后会随机生成一个ID值。

init()

功能：初始化图表。

参数：无

返回值：无

初始化后，图表将处于等待渲染状态。

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

isActive()

功能：判断图表是否是活跃的，即：已完成渲染且未被销毁。

参数：无

返回值：true 是；false 否

isAsyncRender()

功能：判断图表的render()函数是否是异步的。

参数：无

返回值：true 是；false 否

isAsyncUpdate()

功能：判断图表的update()函数是否是异步的。

参数：无

返回值：true 是；false 否

isDataSetParamValueReady()

功能：判断图表的所有数据集参数值是否都已准备齐备，没有缺失的必填参数值。

参数：无

返回值：true 是；false 否

links(links)

功能：获取/设置图表的联动设置对象。

参数：

• links
  可选，要设置的图表联动设置对象，格式参考dg-chart-link

返回值：要获取的图表联动设置对象，没有则是null

设置操作只在render()被调用之前起作用。

listener(listener)

功能：获取/设置图表监听器。

参数：

• listener
  可选，要设置的图表监听器，格式参考dg-chart-listener

返回值：要获取的图表监听器，没有则是null

设置操作只在render()被调用之前起作用。

map(map)

功能：地图类图表支持函数：获取/设置图表地图名、地图资源URL。

参数：

• map
  可选，要设置的图表地图名、地图资源URL，格式参考dg-chart-map

返回值：要获取的图表地图名、地图资源URL，没有则是null

设置操作只在render()被调用之前起作用。

mapURL(map)

功能：地图类图表支持函数：获取指定地图名、地图资源URL对应的服务端URL地址，此地址可直接用于加载地图JSON。

参数：

• map
  图表地图名、地图资源URL，格式参考dg-chart-map

返回值：地图的服务端URL地址

name

功能：图表名称。

nameNonNull()

功能：获取图表名称。

参数：无

返回值：图表名称

off(eventType, handler)

功能：解绑图表事件处理函数。

参数：

• eventType
  要解绑的事件类型，比如：”click”、”mouseover”
• handler
  可选，要解绑的图表事件处理函数引用，不设置则解绑上述事件类型的所有处理函数

返回值：无

此函数应在图表处于活跃状态时调用。

on(eventType, handler)

功能：绑定图表事件处理函数。

参数：

• eventType
  要绑定的事件类型，比如：”click”、”mouseover”
• handler
  图表事件处理函数，格式为：function(chartEvent){ … }

返回值：无

此函数应在图表处于活跃状态时调用。

图表事件对象（chartEvent）结构参考图表事件对象章节。

onClick(handler)

功能：绑定单击（”click”）图表事件处理函数。

参数：

• handler
  图表事件处理函数，格式参考on()的handler参数

返回值：无

此函数应在图表处于活跃状态时调用。

onDblclick()

功能：绑定双击（”dblclick”）图表事件处理函数。

参数：

• handler
  图表事件处理函数，格式参考on()的handler参数

返回值：无

此函数应在图表处于活跃状态时调用。

onMousedown()

功能：绑定鼠标按下（”mousedown”）图表事件处理函数。

参数：

• handler
  图表事件处理函数，格式参考on()的handler参数

返回值：无

此函数应在图表处于活跃状态时调用。

onMouseout()

功能：绑定鼠标滑出（”mouseout”）图表事件处理函数。

参数：

• handler
  图表事件处理函数，格式参考on()的handler参数

返回值：无

此函数应在图表处于活跃状态时调用。

onMouseover()

功能：绑定鼠标滑入（”mouseover”）图表事件处理函数。

参数：

• handler
  图表事件处理函数，格式参考on()的handler参数

返回值：无

此函数应在图表处于活跃状态时调用。

onMouseup()

功能：绑定鼠标松开（”mouseup”）图表事件处理函数。

参数：

• handler
  图表事件处理函数，格式参考on()的handler参数

返回值：无

此函数应在图表处于活跃状态时调用。

options(options)

功能：获取/设置图表选项。

参数：

• options
  可选，要设置的图表选项

返回值：要获取的图表选项，没有则是null

设置操作只在render()被调用之前起作用。

plugin

功能：图表使用的底层图表插件，结构为：

{
  //插件唯一标识
  id: "...",
  //插件展示名称标签
  nameLabel: {value: "..."},
  //插件的数据标记定义
  dataSigns:
  [
    {
      //数据标记名
      name: "...",
      //数据标记展示名称标签
      nameLabel: {value: "..."},
      //是否必须标记，值为：true、false
      required: ...,
      //是否可多次标记，值为：true、false
      multiple: ...
    },
    ...
  ],
  //插件的图表渲染器
  chartRenderer: 图表渲染器
}

refreshData()

功能：从服务端获取图表所有数据集的新结果数据，然后使用它们刷新图表。

参数：无

返回值：无

此函数应在图表处于活跃状态时调用。

render()

功能：渲染图表。

参数：无

返回值：true 已执行渲染；false 未执行渲染

只有图表处于 等待渲染、或者 已销毁 状态时，此函数才会执行渲染。

渲染过程中，图表将处于正在渲染状态； 渲染完成后（可能是异步渲染），图表将处于完成渲染状态；

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

renderContext

功能：图表渲染上下文，同看板渲染上下文。

renderContextAttr(attrName, attrValue)

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

参数：

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

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

resetDataSetParamValues(chartDataSet)

功能：重置指定图表数据集的所有参数值。

参数：

• chartDataSet
  图表数据集对象、 图表数据集对象数组索引

返回值：无

resize()

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

参数：无

返回值：无

此函数应在图表处于活跃状态时调用。

resultAt(results, index)

功能：获取指定索引的数据集结果对象。

参数：

• results
  数据集结果对象数组
• index
  索引数值

返回值：数据集结果对象，没有则是null

resultCell(result, property, row)

功能：获取数据集结果对象指定属性、指定行的单元格属性值。

参数：

• result
  数据集结果对象
• property
  数据集属性对象、属性名
• row
  行索引数值（以0开始）

返回值：单个属性值，没有则是null

resultColumnArrays(result, properties, row, count)

功能：获取数据集结果对象的列值数组集。

参数：

• result
  数据集结果对象
• properties
  数据集属性对象数组、 属性名数组、 数据集属性对象、 属性名
• row
  可选，行索引数值（以0开始），默认为0
• count
  可选，获取的最多行数，默认为全部

返回值：当properties是数组时，返回二维数组：[[…, …], …]， 第一维元素索引与properties元素索引一一对应，第二维元素索引表示行号； 当properties不是数组时，返回一维列值数组：[…, …]。

resultDatas(result)

功能：获取数据集结果对象数据的数组形式（data属性值）， 如果data是数组，直接返回；如果不是数组，则将其添加至新建的数组并返回。

参数：

• result
  数据集结果对象

返回值：非null的数组

resultFirst(results)

功能：获取第一个数据集结果对象。

参数：

• results
  数据集结果对象数组

返回值：数据集结果对象，没有则是null

resultNameValueObjects(result, nameProperty, valueProperty, row, count)

功能：获取数据集结果对象的名/值对象数组。

参数：

• result
  数据集结果对象
• nameProperty
  作为名称的 数据集属性对象、 属性名
• valueProperty
  作为值的 数据集属性对象数组、 属性名数组、 数据集属性对象、 属性名
• row
  可选，行索引数值（以0开始），默认为0
• count
  可选，获取的最多行数，默认为全部

返回值：当valueProperty是数组时，返回格式为： [ { name: “…”, value: [ …, … ] } ]； 当valueProperty不是数组时，返回格式为： [ { name: “…”, value: … } ]。

resultRowArrays(result, properties, row, count)

功能：获取数据集结果对象的行值数组集。

参数：

• result
  数据集结果对象
• properties
  数据集属性对象数组、 属性名数组、 数据集属性对象、 属性名
• row
  可选，行索引数值（以0开始），默认为0
• count
  可选，获取的最多行数，默认为全部

返回值：当properties是数组时，返回二维数组：[[…, …], …]， 第一维元素索引表示行索引，第二维元素索引则与properties元素索引一一对应； 当properties不是数组时，返回一维行值数组：[…, …]。

resultRowCell(rowObj, property)

功能：获取数据集结果对象的某行对象的列值。

参数：

• rowObj
  数据集结果对象的某行对象
• property
  数据集属性对象、 属性名

返回值：列值，没有则是null

setDataSetParamValues(chartDataSet, paramValues)

功能：设置指定图表数据集对象的所有参数值。

已弃用，请使用dataSetParamValues()函数。

status(value)

功能：获取/设置图表状态。

参数：

• value
  可选，要设置的图表状态字符串

返回值：要获取的图表状态字符串

谨慎设置图表状态，因为可能会影响图表内部逻辑。

statusDestroyed(set)

功能：获取/设置图表是否处于已销毁状态。

参数：

• set
  可选，仅为true时执行设置操作

返回值：true 是；false 否

谨慎设置图表状态，因为可能会影响图表内部逻辑。

statusPreRender(set)

功能：获取/设置图表是否处于等待渲染状态。

参数：

• set
  可选，仅为true时执行设置操作

返回值：true 是；false 否

等待渲染 状态的图表随时可能会被自动执行render()函数， 具体参考 dashboard.startHandleCharts()函数说明。

谨慎设置图表状态，因为可能会影响图表内部逻辑。

statusPreUpdate(set)

功能：获取/设置图表是否处于等待更新状态。

参数：

• set
  可选，仅为true时执行设置操作

返回值：true 是；false 否

等待更新 状态的图表随时可能会被自动执行update()函数， 具体参考 dashboard.startHandleCharts()函数说明。

谨慎设置图表状态，因为可能会影响图表内部逻辑。

statusRendered(set, postProcess)

功能：获取/设置图表是否处于完成渲染状态。

参数：

• set
  可选，仅为true时执行设置操作
• postProcess
  可选，当set为true时，是否执行完成渲染后置处理逻辑， true 执行，false 不执行，默认为true。
  后置处理逻辑包括：渲染交互设置表单、绑定事件处理函数、调用图表监听器等。

返回值：true 是；false 否

完成渲染 状态的图表随时可能会被自动执行update()函数， 具体参考 dashboard.startHandleCharts()函数说明。

谨慎设置图表状态，因为可能会影响图表内部逻辑。

statusRendering(set)

功能：获取/设置图表是否处于正在渲染状态。

参数：

• set
  可选，仅为true时执行设置操作

返回值：true 是；false 否

render()函数内部会设置此状态。

谨慎设置图表状态，因为可能会影响图表内部逻辑。

statusUpdated(set, postProcess)

功能：获取/设置图表是否处于完成更新状态。

参数：

• set
  可选，仅为true时执行设置操作
• postProcess
  可选，当set为true时，是否执行完成更新后置处理逻辑， true 执行，false 不执行，默认为true。
  后置处理逻辑包括：调用图表监听器等。

返回值：true 是；false 否

完成更新 状态且设置了更新间隔的图表随时可能会被自动执行update()函数， 具体参考 dashboard.startHandleCharts()函数说明。

谨慎设置图表状态，因为可能会影响图表内部逻辑。

statusUpdating(set)

功能：获取/设置图表是否处于正在更新状态。

参数：

• set
  可选，仅为true时执行设置操作

返回值：true 是；false 否

update()函数内部会设置此状态。

谨慎设置图表状态，因为可能会影响图表内部逻辑。

theme(theme)

功能：获取/设置图表主题。

参数：

• theme
  可选，要设置的图表主题，格式参考dg-chart-theme

返回值：要获取的图表主题

设置操作只在render()被调用之前起作用。

update(results)

功能：更新图表数据。

参数：

• results
  要更新至图表的数据集结果对象数组

返回值：true 已执行更新；false 未执行更新

只有图表处于 完成渲染、或者 等待更新、或者 完成更新 状态时，此函数才会执行更新。

更新过程中，图表将处于正在更新状态； 更新完成后（可能是异步更新），图表将处于完成更新状态；

看板页面加载并完成渲染图表后，会自动调用此函数。

数据集结果对象数组 封装与图表数据集对象数组对应的数据集结果，结构为：

[
  数据集结果对象,
  ...
]

数据集结果对象 封装某个数据集的查询结果，结构为：

{
  data:
  [
    //一行结果数据对象
    //属性名 数据集属性对象的name值
    { 属性名: 属性值, ...},
    ...
  ]
  或者
  { 属性名: 属性值, ...}
}

对于SQL数据集，data始终为数组，对于JSON数据集，data结构则与原始JSON数据一致。

chart.resultDatas()可方便获取data的数组形式。

updateInterval

功能：图表更新间隔毫秒数， -1 不更新；0 实时更新；>0 更新间隔毫秒数

updateIntervalNonNull()

功能：获取图表更新间隔。

参数：无

返回值：更新间隔毫秒数，不会返回null