首页 入门 文档 下载 模板 示例 - OSCHINA 示例 - CSDN 留言板 开源协议 企业版

看板对象API

本文档仅提供2.0API版本的相关功能说明，对于1.0API版本的功能，请参考旧版文档。

addChart(chart, syncStatus)

将图表添加至看板。
如果图表已添加至看板，将不会再次添加。
参数：
  • chart
    图表对象。
  • syncStatus
    可选，是否在加入看板后同步图表状态，当图表处于准备初始化状态时， 自动初始化或渲染图表。默认值为：true。
返回值：
true 已添加； false 未添加。

addCharts(charts, syncStatus)

将多个图表添加至看板。
如果某个图表已添加至看板，将不会再次添加。
参数：
  • charts
    图表对象或其数组。
  • syncStatus
    可选，是否在加入看板后同步图表状态，当图表处于准备初始化状态时， 自动初始化或渲染图表。默认值为：true。
返回值：
[ true、false, ... ]，是否已添加的布尔值数组，true 已添加；false 未添加。

apiVersion()

获取看板API版本号。
参数：
无。
返回值：
"..."。

chart(identity)

获取看板中指定标识的图表。
参数：
返回值：
图表对象，未找到则是null。

chartIndex(identity)

获取看板中指定标识的图表在dashboard.charts()数组中的索引数值。
参数：
返回值：
索引数值，未找到则是-1。

charts()

获取看板中的所有图表。
参数：
无。
返回值：
[ 图表对象, ... ]。

chartsIn(element)

获取指定元素内（不包括元素自身）包含的所有已加入看板的图表。
参数：
  • element
    HTML元素、元素选择器字符串。
返回值：
[ 图表对象, ... ]。

contextURL(url)

为以'/'字符开头的URL前置添加系统根路径。
参数：
  • url
    可选，要处理的URL，例如：/static/theme/blue/image/logo.png。
返回值：
"..."
如果url以'/'字符开头，则前置添加系统根路径后返回，否则，直接返回原url； 如果未设置url参数，则返回系统根路径。

createChart(element, chartRoot, add)

在指定<div>元素上创建本地图表。
本地图表不会从服务端加载数据，需要通过设置dg-chart-fetcher元素属性、 或者chart.fetcher()函数自定义取数器， 否则，将会按照"empty"取数器逻辑处理（具体参考chart.fetcher()函数的fetcher参数说明）。
此函数支持如下调用方式： 
dashboard.createChart(element);
dashboard.createChart(element, chartRoot);
dashboard.createChart(element, add);
dashboard.createChart(element, chartRoot, add);
此函数是一个异步函数。
参数：
  • element
    用于渲染图表的<div>元素、元素选择器字符串。
  • chartRoot
    可选，要创建的图表根对象，如果不设置， 将从element元素的dg-chart-local属性读取。
  • add
    可选，是否在创建完成后加入看板，默认值为：true。
返回值：
Promise，兑现时表示已创建完成，兑现值为：图表对象，即创建的图表对象， 当add参数为false时处于准备初始化状态。
图表根对象
{
  //可选，此图表要使用的图表插件ID，如果未设置，
  //则必须通过dg-chart-renderer或chart.renderer()函数设置图表渲染器
  plugin: "...",
  //可选，数据集绑定数组，由plugin的图表插件需要决定
  dataSetBinds: [ 数据集绑定, ... ],
  //可选，图表ID，留空会自动生成
  id: "...",
  //可选，图表名称，留空会自动设置为""
  name: "..."
}

createCharts(elements, chartRoots, add)

在多个<div>元素上创建本地图表。
本地图表不会从服务端加载数据，需要通过设置dg-chart-fetcher元素属性、 或者chart.fetcher()函数自定义取数器， 否则，将会按照"empty"取数器逻辑处理（具体参考chart.fetcher()函数的fetcher参数说明）。
此函数支持如下调用方式： 
dashboard.createCharts(elements);
dashboard.createCharts(elements, chartRoots);
dashboard.createCharts(elements, add);
dashboard.createCharts(elements, chartRoots, add);
此函数是一个异步函数。
参数：
  • elements
    用于渲染图表的<div>元素选择器字符串、<div>元素数组。
  • chartRoots
    可选，要创建的图表根对象数组，如果不设置，或者其中某个为null， 将从元素的dg-chart-local属性读取。
  • add
    可选，是否在创建完成后加入看板，默认值为：true。
返回值：
Promise，兑现时表示已创建完成，兑现值为：[ 图表对象, ... ]，即创建的图表数组， 当add参数为false时都处于准备初始化状态。

createUnsolvedCharts(elements, add)

将元素内（包括自身）所有设置了dg-chart-local属性、 且未初始化为图表的<div>元素创建为本地图表。
本地图表不会从服务端加载数据，需要通过设置dg-chart-fetcher元素属性、 或者chart.fetcher()函数自定义取数器， 否则，将会按照"empty"取数器逻辑处理（具体参考chart.fetcher()函数的fetcher参数说明）。
此函数支持如下调用方式： 
dashboard.createUnsolvedCharts();
dashboard.createUnsolvedCharts(elements);
dashboard.createUnsolvedCharts(add);
dashboard.createUnsolvedCharts(elements, add);
此函数是一个异步函数。
参数：
  • elements
    可选，限定查找的HTML元素选择器字符串、HTML元素数组、HTML元素，默认为：<body>元素。
  • add
    可选，是否在创建完成后加入看板，默认值为：true。
返回值：
Promise，兑现时表示已创建完成，兑现值为：[ 图表对象, ... ]，即创建的图表数组， 当add参数为false时都处于准备初始化状态。

dataSetParamValueBatched(sourceData, batchConfig, sourceContext)

使用源数据批量设置看板内多个图表的数据集参数值。
参数：
  • sourceData
    源数据，格式支持：{ ... }、[ ... ]。
  • batchConfig
    批量配置。
  • sourceContext
    可选，传递给数据映射对象的value()函数sourceContext参数，如果为数组，则传递多个参数，默认为：sourceData。
返回值：
[ 图表对象, ... ]，批量设置的图表对象数组。
批量配置
{
  //可选，目标图表元素ID、图表对象、或者它们的数组，用于在下面data中使用的目标图表数据集参数索引中引用图表
  target: "..."、图表对象、[ ... ],
  //可选，下述data中使用的源数据对象属性名的统一根前缀属性名，末尾不应带'.'字符
  root: "...",
  //可选，映射数据配置，定义源数据至目标图表数据集参数值的映射关系，没有则不设置任何参数值
  data:
  //名值映射表，名为源数据对象属性名（除去root前缀），值为目标图表数据集参数索引或其数组
  {
    "...": ...、[ ... ],
    ...
  }、
  //映射对象数组
  [
    {
      //必填，源数据对象属性名（除去root前缀）
      name: "...",
      //必填，目标图表数据集参数索引或其数组
      index: ...、[ ... ],
      //可选，自定义源数据对象属性值处理函数，返回要设置的目标参数值
      //sourceValue 上述name对应的源数据对象属性值
      //sourceContext 上述dataSetParamValueBatched()函数的sourceContext
      value: function(sourceValue, sourceContext...){ return ...; }
    },
    ...
  ]
}
源数据对象属性名
源数据对象属性名和root统一根前缀属性名可以是源数据对象的简单属性名，例如："name"、"value"， 也可以是属性路径，例如："data.name"、"data.value[0]"。

destroy()

销毁看板，内部调用dashboard.doDestroy()函数，执行看板内图表和表单的销毁操作。
参数：
无。
返回值：
true 已销毁；
false 未执行销毁操作，因为看板还未渲染、正在销毁。
另参考看板生命周期。

destroyForm(form)

销毁看板表单（通过dashboard.renderForm()函数、dg-dashboard-form元素属性创建的）。
参数：
  • form
    表单<form>元素、元素选择器字符串。
返回值：
无。

doDestroy()

执行看板销毁，销毁看板内的所有图表、看板表单。
此函数通常用于看板监听器的onDestroy()函数，在阻止默认销毁逻辑后，再调用此函数执行销毁。
参数：
无。
返回值：
无。

doRender()

执行看板渲染，内部调用dashboard.startHandleCharts()函数，处理图表状态，进行图表渲染或更新。
此函数通常用于看板监听器的onRender()函数，在阻止默认渲染逻辑后，再调用此函数执行渲染。
参数：
无。
返回值：
无。
看板页面加载时，默认会自动调用此函数（在dashboard.render()函数内部调用）。

fetcher(fetcher)

获取/设置看板取数器，用于自定义看板内所有图表取数器为"global"的图表数据提供逻辑。
参数：
返回值：
要获取的看板取数器。
看板初始化时，会使用dg-dashboard-fetcher的值执行设置操作。
设置操作应在dashboard.init()函数执行后且dashboard.render()函数执行前调用。
看板取数器
//context 看板获取上下文
function(context)
{
  ...
  return ...;
}
看板取数器应返回一个看板结果对象、 或者一个兑现值为看板结果的Promise对象（异步获取时）。
另外，如果context.chartQueries中的某个数据集查询的ignoreFetch值为true， 取数器不必实际加载其数据，但是应返回一个占位数据集结果，格式为：{ data: null, ignoreFetch: true }。
看板获取上下文
{
  //当前看板对象
  dashboard: 看板对象,
  //当前取数分组名
  group: "...",
  //分组内要更新的图表及其查询信息
  chartQueries:
  [
    { chart: 图表对象, query: 图表查询 },
    ...
  ]
}
看板结果
{
  //图表结果映射表，名为图表ID，值为图表结果对象
  chartResults:
  {
    "...": 图表结果,
    ...
  },
  //图表错误映射表，名为图表ID，值为错误信息对象，
  //如果某个图表结果提供出错，应在这里设置错误信息
  chartErrors:
  {
    "...": { message: "..." },
    ...
  }
}

id()

获取看板ID，这是一个由系统随机生成的唯一ID。
参数：
无。
返回值：
"..."。

init()

初始化看板， 使用<body>元素上的dg-*属性初始化看板， 调用chart.init()函数初始化看板内的所有图表。
在渲染看板时，通常无需先显式调用此函数，直接调用dashboard.render()函数即可， 它的内部会在必要时自动调用此函数。
注意：初始化图表操作不包括chart.manualRender()函数返回true的、 以及chart.element()函数返回null的图表， 这些图表也不会在调用了dashboard.render()后被渲染， 需要手动调用chart.render()函数执行渲染。
此函数是一个异步函数。
参数：
无。
返回值：
Promise，兑现时表示已初始化完成，无兑现值。
看板页面加载时，会自动调用此函数（也可以通过dg-dashboard-code禁用此逻辑）。
看板生命周期 
dashboard.init() -->-- dashboard.render() -->-- dashboard.destroy() -->--|
      |                       |                                                 |
      |                       |---------------------<---------------------------| 
      |------------------------------<------------------------------------------|
调用dashboard.destroy()函数销毁看板后，可再次调用dashboard.init()函数重新初始化看板、 或者调用dashboard.render()函数重新渲染看板。

isActive()

判断看板是否是活跃的，即：已渲染完成且未执行销毁。
已渲染完成：dashboard.render()已执行完。
未执行销毁：dashboard.destroy()未执行。
参数：
无。
返回值：
true 是； false 否。

isAlive()

判断看板是否是活着的，即：已执行渲染且未完成销毁。
已执行渲染：dashboard.render()正在执行、或者已执行完。
未完成销毁：dashboard.destroy()未执行、或者正在执行。
参数：
无。
返回值：
true 是； false 否。

isHandlingCharts()

判断看板是否正在监视处理它包含的所有图表。
参数：
无。
返回值：
true 是； false 否。
另参考dashboard.startHandleCharts()函数。

listener(listener)

获取/设置看板监听器。
参数：
返回值：
要获取的看板监听器。
看板初始化时，会使用dg-dashboard-listener的值执行设置操作。
设置操作应在dashboard.init()函数执行后且dashboard.render()函数执行前调用。
看板监听器 
{
  //可选，渲染看板完成回调函数
  //dashboard 看板对象
  rendered: function(dashboard){ ... },
  
  //可选，销毁看板完成回调函数
  //dashboard 看板对象
  destroyed: function(dashboard){ ... },
  
  //可选，渲染看板前置回调函数，
  //返回false、或者返回兑现值为false的Promise对象将阻止看板渲染，另参考dashboard.doRender()函数
  //dashboard 看板对象
  onRender: function(dashboard){ ... },
  
  //可选，销毁看板前置回调函数，
  //返回false将阻止看板销毁，另参考dashboard.doDestroy()函数
  //dashboard 看板对象
  onDestroy: function(dashboard){ ... }
}

loadChart(element, chartWidgetId, add)

加载单个图表。
此函数支持如下调用方式： 
dashboard.loadChart(element);
dashboard.loadChart(element, chartWidgetId);
dashboard.loadChart(element, add);
dashboard.loadChart(element, chartWidgetId, add);
此函数是一个异步函数。
加载图表受dg-load-chart-policy策略控制。
参数：
  • element
    用于渲染图表的<div>元素、元素选择器字符串。
  • chartWidgetId
    可选，要加载的图表部件ID，即【图表管理】模块表格中的某个图表的ID值， 如果不设置，将从元素的dg-chart-widget属性读取。
  • add
    可选，是否在加载完成后加入看板，默认值为：true。
返回值：
Promise，兑现时表示已加载完成，兑现值为：图表对象，即加载的图表对象， 当add参数为false时处于准备初始化状态。

loadCharts(elements, chartWidgetIds, add)

加载多个图表。
此函数支持如下调用方式： 
dashboard.loadCharts(elements);
dashboard.loadCharts(elements, chartWidgetIds);
dashboard.loadCharts(elements, add);
dashboard.loadCharts(elements, chartWidgetIds, add);
此函数是一个异步函数。
加载图表受dg-load-chart-policy策略控制。
参数：
  • elements
    用于渲染图表的<div>元素选择器字符串、<div>元素数组。
  • chartWidgetIds
    可选，要加载的图表部件ID数组，即【图表管理】模块表格中的某个图表的ID值， 如果不设置或者其中某个为null，将从元素的dg-chart-widget属性读取。
  • add
    可选，是否在加载完成后加入看板，默认值为：true。
返回值：
Promise，兑现时表示已加载完成，兑现值为：[ 图表对象, ... ]，即加载的图表数组， 当add参数为false时都处于准备初始化状态。

loadUnsolvedCharts(elements, add)

将元素内（包括自身）所有设置了dg-chart-widget属性、 且未初始化为图表的<div>元素加载为图表。
此函数支持如下调用方式： 
dashboard.loadUnsolvedCharts();
dashboard.loadUnsolvedCharts(elements);
dashboard.loadUnsolvedCharts(add);
dashboard.loadUnsolvedCharts(elements, add);
此函数是一个异步函数。
加载图表受dg-load-chart-policy策略控制。
参数：
  • elements
    可选，限定查找的HTML元素选择器字符串、HTML元素数组、HTML元素，默认为：<body>元素。
  • add
    可选，是否在加载完成后加入看板，默认值为：true。
返回值：
Promise，兑现时表示已加载完成，兑现值为：[ 图表对象, ... ]，即加载的图表数组， 当add参数为false时都处于准备初始化状态。

mapHandler(mapHandler)

获取/设置地图处理器。
参数：
返回值：
要获取的地图处理器。
看板初始化时，会使用dg-map-handler的值执行设置操作。
设置操作应在dashboard.init()函数执行后且dashboard.render()函数执行前调用。
地图处理器 
{
  //可选，地图名/URL字符串或URL信息对象映射表，其中url通常是看板某个GeoJSON、SVG格式的资源路径
  values:
  {
    "...": "..."、{ url: "..." },
    ...
  },
  //可选，地图名处理函数，处理后再去values中查找
  //name 原始地图名
  name: function(name)
  {
    return "...";
  },
  //可选，当values中未找到时，返回指定名称的地图URL，返回null表示未找到
  //name 原始地图名
  url: function(name)
  {
    return "..."、null;
  }
}

removeChart(identity, doDestroy)

删除图表。
参数：
  • identity
    图表标识：<div>图表元素、<div>图表元素ID、 图表对象、 图表ID、图表数组索引号。
  • doDestroy
    可选，是否销毁图表，默认值为：true。
返回值：
删除的图表对象，未找到时为null。

render()

渲染看板，调用dashboard.doRender()函数，执行看板内图表的渲染或更新操作。
另外，如果看板还未初始化，此函数内部会先调用dashboard.init()函数初始化看板。
此函数是一个异步函数。
参数：
无。
返回值：
Promise，兑现时表示已渲染完成（开始监视执行看板内图表的渲染或更新操作），无兑现值。
看板页面加载时，会自动调用此函数（也可以通过dg-dashboard-code禁用此逻辑）。
另参考看板生命周期。

renderContext()

获取渲染上下文。
参数：
无。
返回值：
渲染上下文。
渲染上下文 
{
  "...": ...,
  ...
}
其中包含打开看板展示页面时的URL参数名/值信息（具体参考 看板源码设计模式-处理看板参数章节）， 以及看板内部使用的DG_*信息。

renderContextValue(name, value)

获取/设置渲染上下文中指定名称的值。
参数：
  • name
    名称。
  • value
    可选，要设置的值。
返回值：
要获取的值，没有则是null。

renderForm(form, config)

将指定<form>表单元素渲染为看板表单。
参数：
  • form
    要渲染的<form>表单元素、元素选择器字符串。
  • config
    可选，看板表单配置，如果不设置， 将从<form>表单元素的dg-dashboard-form属性读取。
返回值：
无。
看板表单配置
{
  //必填，表单输入项或其数组
  items: { ... }、 [ { ... }, ... ],
  //可选，表单联动图表配置
  link: { ... },
  //可选，表单提交按钮文本
  submitText: "...",
  //可选，表单渲染完成回调函数
  //form 表单DOM对象
  rendered: function(form){ ... }
}
表单输入项
{
  //必填，输入项名称
  name: "...",
  //可选，默认值
  value: ...,
  //可选，输入项标签
  label: "...",
  //可选，输入项类型："string" 字符串；"boolean" 布尔值；"number" 数值；
  //"object" 对象（可填写{ ... }或者[ ... ]格式的内容）。默认值为："string"
  type: "...",
  //可选，是否必填：true 必填；false 选填。默认为：false
  required: false、true,
  //可选，输入框类型：
  //"text" 文本框；"select" 下拉框；"date" 日期框；"time" 时间框；"datetime" 日期时间框；
  //"radio" 单选框；"checkbox" 复选框；"textarea" 文本域。默认值为："text"
  inputType: "...",
  //可选，输入框配置，与定义数据集-参数输入框类型表格中的输入框配置格式相同
  inputPayload: ...,
  //可选，此表单输入项值的联动目标图表数据集参数索引或其数组
  link: ...、[ ... ]
}

{
  //可选，联动目标图表元素ID、ID数组，用于在下面data中使用的目标图表数据集参数索引中引用图表
  target: "..."、["...", ...],
  //可选，联动数据配置，定义表单数据至联动目标图表数据集参数值的映射关系，没有则不设置任何参数值
  data:
  //名值映射表，名为表单输入项名称，值为联动目标图表数据集参数索引或其数组
  {
    "...": ...、[ ... ],
    ...
  }、
  //映射对象数组
  [
    {
      //必填，表单输入项名称
      name: "...",
      //必填，联动目标图表数据集参数索引或其数组
      index: ...、[ ... ],
      //可选，自定义表单输入项值处理函数，返回要设置的目标参数值
      //sourceValue 上述name对应的表单输入项值
      //formData 表单数据对象
      //form 表单DOM对象
      value: function(sourceValue, formData, form){ return ...; }
    },
    ...
  ]
}

renderedChart(element)

获取当前在指定HTML元素上渲染的图表对象。
参数：
  • element
    HTML元素、元素选择器字符串。
返回值：
图表对象，没有则是null。

resizeChart(identity)

如果图表处于活跃状态，则重新调整其尺寸，使它与图表元素的尺寸保持一致。
参数：
返回值：
图表对象。
另参考chart.resize()函数。

resizeCharts(charts)

重新调整数组中处于活跃状态的所有图表尺寸，使它们与图表元素的尺寸保持一致。
参数：
返回值：
[ 图表对象, ... ]，实际调整尺寸的图表数组。
另参考chart.resize()函数。

resizeChartsIn(element)

重新调整指定元素内（不包括元素自身）处于活跃状态的所有图表尺寸，使它们与图表元素的尺寸保持一致。
参数：
  • element
    HTML元素、元素选择器字符串。
返回值：
[ 图表对象, ... ]，实际调整尺寸的图表数组。
另参考chart.resize()函数。

resultDataFormat(format)

获取/设置看板级结果数据格式。
如果某个图表的chart.resultDataFormat()为null， 将会使用这个看板级的结果数据格式。
设置了新的结果数据格式后，后续图表刷新将采用这个新格式。
参数：
返回值：
要获取的结果数据格式，没有则是null。

serverDate(asMillisecond)

获取服务端当前日期。
服务端当前日期 = 网页加载时的服务端日期 + (客户端当前日期 - 网页加载时客户端日期)
因此，返回的并不是精确的服务端当前日期，通常是偏差数十至数百毫秒。
参数：
  • asMillisecond
    可选，是否返回毫秒数值而非Date对象，默认为：false。
返回值：
Date对象，或者毫秒数值。

startHandleCharts()

开始监视处理看板内的所有图表，循环查看它们的状态，执行相应操作：
如果图表处于准备渲染状态， 则执行chart.render()函数；
如果图表处于渲染完成状态、 准备更新状态、 更新完成状态且到达刷新间隔， 则加载其数据，然后执行chart.update()函数。
参数：
无。
返回值：
无。
看板页面加载时，默认会自动调用此函数（在dashboard.doRender()函数内部调用）。

stopHandleCharts()

停止监视处理看板内的所有图表。
看板中涉及图表刷新类的功能（图表联动、异步加载图表、刷新图表数据、图表交互设置等等）都依赖看板监视处理逻辑，调用此函数后，它们都将不起作用。
参数：
无。
返回值：
无。
调用此函数后，可再次调用startHandleCharts()开始监视处理。

user()

获取当前用户信息。
参数：
无。
返回值：
用户信息。
用户信息 
{
  //用户ID
  id: "...",
  //用户登录名
  name: "...",
  //用户姓名
  realName: "...",
  //是否管理员，true 是，false 否
  admin: true、false,
  //是否匿名用户，true 是，false 否
  anonymous: true、false,
  //角色集合
  roles:
  [
    {
      //角色ID
      id: "...",
      //角色名称
      name: "...",
      //是否启用，true 是，false 否
      enabled: true、false
    },
    ...
  ]
}
企业版
企业版自1.2.0版本起，用户信息中新增了组织机构信息，如下所示： 
{
  //其他用户信息
  ...,
  //用户组织机构信息，没有则是null
  org:
  {
    //组织机构ID
    id: "...",
    //组织机构名称
    name: "...",
    //组织机构ID完整路径
    fullPath: "...",
    //上级组织机构ID，没有则是null
    parentId: "...",
    //上级组织机构名称，没有则是null
    parentName: "..."
  }
}
 
京ICP备18055183号-1
© 2018-2024 datagear.tech 北京溪歌科技有限公司
登录