9.2. 图表对象

autoResize(auto)

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

参数

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

返回值:获取操作结果,true 自动调整;false 不自动调整

bindLinksEventHanders(links)

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

参数

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

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

chartDataSetAt(index)

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

参数

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

chartDataSetFirst()

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

参数:无

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

chartDataSetName(chartDataSet)

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

参数

返回值:名称字符串

chartDataSets

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

图表数据集对象 结构为:

  1. {
  2. //数据集别名
  3. alias: "...",
  4. //数据集
  5. dataSet: 数据集对象,
  6. //数据集初始参数值映射表:参数名 -> 参数值
  7. paramValues:{ ... },
  8. //数据集属性标记映射表:数据集属性名称 -> 标记名数组
  9. propertySigns:
  10. {
  11. "..." : ["...", ...],
  12. ...
  13. }
  14. }

数据集对象 结构为:

  1. {
  2. //ID
  3. id: "...",
  4. //名称
  5. name: "...",
  6. //参数数组
  7. params:
  8. [
  9. {
  10. //参数名
  11. name: "...",
  12. //参数类型:"STRING" 字符串;"BOOLEAN" 布尔值;"NUMBER" 数值
  13. type: "...",
  14. //是否必填,值为:true、false
  15. required: ...,
  16. //参数描述
  17. desc: "..."
  18. },
  19. ...
  20. ],
  21. //属性数组,即数据集查询结果列信息数组
  22. properties: [ 数据集属性对象, ... ]
  23. }

数据集属性对象 结构为:

  1. {
  2. //名称
  3. name: "...",
  4. //类型:"STRING" 字符串;"BOOLEAN" 布尔值;"INTEGER" 整数;"DECIMAL" 小数;
  5. //"DATE" 日期;"TIME" 时间;"TIMESTAMP" 时间戳
  6. type: "...",
  7. //标签名,可能为null
  8. label: "..."
  9. }

chartDataSetsNonNull()

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

参数:无

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

customChartRenderer()

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

参数:无

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

dashboard

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

dataSetParamValue(chartDataSet, name, value)

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

参数

返回值:要获取的参数值

dataSetParamValues(chartDataSet, paramValues)

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

参数

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

dataSetPropertiesOfSign(chartDataSet, signName)

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

参数

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

dataSetPropertyLabel(dataSetProperty)

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

参数

返回值:标签名字符串

dataSetPropertyOfSign(chartDataSet, signName)

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

参数

返回值数据集属性对象

destroy()

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

参数:无

返回值:无

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

disableSetting(disable)

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

参数

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

返回值:获取操作结果,true 禁用;false 不禁用

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

doRender()

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

参数:无

返回值:无

doUpdate(results)

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

参数

返回值:无

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)。

参数

返回值:要获取的数据

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
    可选,要设置的原始数据,可以是单个数据对象、数据对象数组

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

eventOriginalInfo(chartEvent, originalChartDataSetIndex, originalResultDataIndex)

功能:图表事件支持函数:设置图表事件对象的原始图表数据集索引、原始数据索引、原始数据(根据原始数据索引自动设置)。

参数

  • chartEvent
    图表事件对象
  • originalChartDataSetIndex
    原始图表数据集索引
  • originalResultDataIndex
    原始数据索引,格式允许:单个索引数值、索引数值数组

返回值:无

eventOriginalResultDataIndex(chartEvent, originalResultDataIndex)

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

参数

  • chartEvent
    图表事件对象
  • originalResultDataIndex
    可选,要设置的原始结果数据索引,当chartEvent.originalData为单个对象时,应是单个索引值; 当chartEvent.originalData为对象数组时,应是与之对应的索引值数组

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

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)

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

参数

返回值:无

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

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)

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

参数

返回值:要获取的图表监听器,没有则是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

功能:图表使用的底层图表插件,结构为:

  1. {
  2. //插件唯一标识
  3. id: "...",
  4. //插件展示名称标签
  5. nameLabel: {value: "..."},
  6. //插件的数据标记定义
  7. dataSigns:
  8. [
  9. {
  10. //数据标记名
  11. name: "...",
  12. //数据标记展示名称标签
  13. nameLabel: {value: "..."},
  14. //是否必须标记,值为:true、false
  15. required: ...,
  16. //是否可多次标记,值为:true、false
  17. multiple: ...
  18. },
  19. ...
  20. ],
  21. //插件的图表渲染器
  22. chartRenderer: 图表渲染器
  23. }

refreshData()

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

参数:无

返回值:无

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

render()

功能:渲染图表。

参数:无

返回值:true 已执行渲染;false 未执行渲染

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

渲染过程中,图表将处于正在渲染状态; 渲染完成后(可能是异步渲染),图表将处于完成渲染状态;

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

renderContext

功能:图表渲染上下文,同看板渲染上下文

renderContextAttr(attrName, attrValue)

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

参数

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

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

resetDataSetParamValues(chartDataSet)

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

参数

返回值:无

resize()

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

参数:无

返回值:无

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

resultAt(results, index)

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

参数

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

resultCell(result, property, row)

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

参数

返回值:单个属性值,没有则是null

resultColumnArrays(result, properties, row, count)

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

参数

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

resultDatas(result)

功能:获取数据集结果对象数据的数组形式(data属性值), 如果data是数组,直接返回;如果不是数组,则将其添加至新建的数组并返回。

参数

返回值:非null的数组

resultFirst(results)

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

参数

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

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

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

参数

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

resultRowArrays(result, properties, row, count)

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

参数

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

resultRowCell(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)

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

参数

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

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

update(results)

功能:更新图表数据。

参数

返回值:true 已执行更新;false 未执行更新

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

更新过程中,图表将处于正在更新状态; 更新完成后(可能是异步更新),图表将处于完成更新状态;

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

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

  1. [
  2. 数据集结果对象,
  3. ...
  4. ]

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

  1. {
  2. data:
  3. [
  4. //一行结果数据对象
  5. //属性名 数据集属性对象的name值
  6. { 属性名: 属性值, ...},
  7. ...
  8. ]
  9. 或者
  10. { 属性名: 属性值, ...}
  11. }

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

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

updateInterval

功能:图表更新间隔毫秒数, -1 不更新;0 实时更新;>0 更新间隔毫秒数

updateIntervalNonNull()

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

参数:无

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