看板元素属性

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

将<div>元素定义为图表元素，在看板展示时，图表元素将被绘制为具体的图表。

元素： <div>图表元素

必填： 与dg-chart-local属性二者必选其一（当希望将<div>绘制为图表时）

格式：

"..."

值应为是某个图表部件ID，即【图表管理】模块表格中的某个图表的ID值。

示例：

...
<div dg-chart-widget="c8d5b5df0172452c37b7" style="width:30vw;height:30vh;"></div>
...

dg-chart-local

将<div>元素定义为本地图表元素，在看板展示时，图表元素将被绘制为具体的图表。
与dg-chart-widget不同，本地图表不会从服务端加载数据，需要通过设置dg-chart-fetcher元素属性、或者chart.fetcher()函数自定义取数器，否则，将会按照"empty"取数器逻辑处理（具体参考chart.fetcher()函数的fetcher参数说明）。

元素： <div>图表元素

必填： 与dg-chart-widget属性二者必选其一（当希望将<div>绘制为图表时）

格式：

{
  ...
}

格式与图表根对象相同，另参考dashboard.createChart()函数。

示例：

...
<div dg-chart-local="{plugin:'org.datagear.v2.datetime'}" style="width:30vw;height:30vh;"></div>
...

...
<script>
var chartRoot = {plugin:'org.datagear.v2.datetime'};
</script>
...
<div dg-chart-local="chartRoot" style="width:30vw;height:30vh;"></div>
...

dg-api-version

声明看板采用的API版本，在看板展示时加载对应API版本的看板、图表支持库。

元素： <html>

必填： 否

格式：

"2.0"
声明看板采用最新的2.0版本的API，新建看板应使用此值
"1.0"
声明看板采用已废弃、仅用于兼容旧版功能的API，新建看板不应再使用
空
API版本由定义看板-API版本决定

2.0版本API的看板中只能使用apiVersion声明为2.0的图表插件及图表部件， 1.0版本API的看板中只能使用apiVersion未定义或者声明为1.0的图表插件及图表部件。

示例：

<!DOCTYPE html>
<html dg-api-version="2.0">
...
</html>

<!DOCTYPE html>
<html dg-api-version="1.0">
...
</html>

dg-chart-auto-resize

当浏览器窗口调整尺寸后，是否自动调整图表尺寸。

元素： <body>、<div>图表元素。在<body>元素时，设置全局功能；在<div>图表元素时，仅设置单个图表功能。

必填： 否

格式：

true、空
启用尺寸自动调整
false
禁用尺寸自动调整

示例：

<body dg-chart-auto-resize="false">
  <div dg-chart-widget="..." dg-chart-auto-resize="true"></div>
</body>

dg-chart-config-values

设置图表配置值，即图表插件配置表单对应的值。
此处的设置项会覆盖在定义图表-设置图表配置时设置的同名项。

元素：<div>图表元素

必填：否

格式：

{
  ...
}

应符合图表插件配置表单中的表单属性规定的格式。

示例：

<div dg-chart-widget="..."
  dg-chart-config-values="{showTitle: true, titleColor: 'red'}">
</div>

dg-chart-disable-tool

是否禁用图表内置工具功能，包括参数、数据功能，优先级低于通用图表选项中的disableTool选项。

元素：<body>、<div>图表元素。在<body>元素时，设置全局功能；在<div>图表元素时，仅设置单个图表功能，图表元素级设置将会继承全局设置。

必填：否

格式：

true、false、{ ... }

格式与chart.disableTool()函数的disable参数格式相同。

示例：

<body dg-chart-disable-tool="true">
  <div dg-chart-widget="..." dg-chart-disable-tool="{data:false}"></div>
</body>

dg-chart-fetch-group

设置图表取数分组。
当一个看板有很多图表，希望它们分组加载数据以提高整体加载效率，或者有图表数据加载较耗时，希望它不影响其他图表而单独加载数据时，可以设置此属性。

必填： 否

元素： <body>、<div>图表元素。在<body>元素时，设置全局取数分组；在<div>图表元素时，仅设置单个图表取数分组。

格式：

"..."

示例：

<div dg-chart-widget="..."></div>
<div dg-chart-widget="..."></div>
<div dg-chart-widget="..."></div>
<div dg-chart-fetch-group="slow-0" dg-chart-widget="..."></div>
<div dg-chart-fetch-group="slow-0" dg-chart-widget="..."></div>
<div dg-chart-fetch-group="slow-1" dg-chart-widget="..."></div>

上述未设置dg-chart-fetch-group的三个图表、分组为"slow-0"的两个图表、分组为"slow-1"的一个图表，将分别使用三个独立的ajax请求加载数据，互不影响。

dg-chart-fetcher

设置图表取数器，自定义图表数据提供逻辑。

必填： 否

元素： <div>图表元素

格式：

...

格式与chart.fetcher()函数的fetcher参数格式相同。

示例：

<!DOCTYPE html>
<html>
<head>
<script>
function chartFetcher(context)
{
  var chartResult = {
    dataSetResults: [{ data: [ {name: "aaa", value: 10}, {name: "bbb", value: 60} ] }]
  };
  return chartResult;
};
</script>
</head>
<body>
  <div dg-chart-widget="..." dg-chart-fetcher="chartFetcher"></div>
</body>
...

上述示例中的图表不会请求服务端加载数据，而是使用chartFetcher函数中的chartResult数据更新图表。

dg-chart-link

设置图表联动功能，比如：在鼠标点击图表条目后，更新联动目标图表数据并刷新图表。

元素：<div>图表元素

必填：否

格式：

{
 ...
}

格式与chart.links()函数的links参数相同，另参考chart.bindLinkEventHanders()函数。

示例：

<!DOCTYPE html>
<html>
<head>
<script>
var myChartLink={ target: "chart6", data: { name: 0 } };
</script>
</head>
<body>
//当点击chart0图表条目时，
//将图表事件对象的data.name属性值设置为chart1图表的第0个数据集的第0个参数值，
//将图表事件对象的data.value属性值设置为chart1图表的第0个数据集的第1个参数值，
//将图表事件对象的data.value属性值设置为chart1图表的第1个数据集的第0个参数值，
//然后刷新chart1图表
<div id="chart0" dg-chart-widget="..."
    dg-chart-link="{target:'chart1',root:'data',data:{name:0,value:[1,{dataSet: 1}]}}">
</div>
<div id="chart1" dg-chart-widget="..."></div>

//当点击chart2图表条目时，
//将图表事件对象的name属性值设置为chart3图表的第0个数据集的第0个参数值，
//将图表事件对象的name属性值设置为chart4图表的第0个数据集的第0个参数值，
//然后刷新chart3、chart4图表；
//当双击chart2图表条目时，
//将图表事件对象的name属性值设置为chart1图表的第0个数据集的第0个参数值，
//然后刷新chart1图表
<div id="chart2" dg-chart-widget="..."
    dg-chart-link="[
        {target:['chart3','chart4'],data:{name:[0,{chart:1}]}},
        {trigger:'dblclick',target:'chart1',data:{name:0}}
      ]">
</div>
<div id="chart3" dg-chart-widget="..."></div>
<div id="chart4" dg-chart-widget="..."></div>

//当点击chart5图表条目时，
//将图表事件对象的name属性值设置为chart6图表的第0个数据集的第0个参数值，
//然后刷新chart6图表
<div id="chart5" dg-chart-widget="..." dg-chart-link="myChartLink"></div>
<div id="chart6" dg-chart-widget="..."></div>

//当点击chart7图表条目时，不传递任何参数，直接刷新chart8图表
<div id="chart7" dg-chart-widget="..." dg-chart-link="{target:'chart8'}"></div>
<div id="chart8" dg-chart-widget="..."></div>
</body>
...

用户应设置联动目标图表元素的id属性值，系统自动生成的值在每次刷新时都可能是随机的。
图表事件结构的详细说明文档请参考对应图表插件的相关文档，内置图表类型的图表事件结构参考内置图表类型-图表事件结构章节。

dg-chart-listener

设置图表监听器，用于在图表渲染前/后（无数据）、更新前/后（有数据）、销毁前/后执行回调函数。

元素：<body>、<div>图表元素。在<body>元素时，设置全局监听器；在<div>图表元素时，仅设置单个图表监听器，图表元素级设置将会继承全局设置。

必填：否

格式：

{
  ...
}

格式与图表监听器相同，另参考chart.listener()函数。

示例：

<!DOCTYPE html>
<html>
<head>
<script>
var chartListener=
{
  rendered: function(chart){ alert(chart.id + " rendered"); },
  updated: function(chart, chartResult){ alert(chart.id + " updated"); }
};
</script>
</head>
<body dg-chart-listener="chartListener">
  <div dg-chart-widget="..." dg-chart-listener="{rendered: function(chart){ ... }}"></div>
</body>
...

dg-chart-manual-render

是否手动渲染图表，而非在看板页面加载后自动渲染。
手动渲染的图表只有在手动调用chart.render()函数后才会渲染，通常用于制作具有页内弹窗效果的看板，在触发弹窗后才渲染图表。

元素：<div>图表元素

必填：否

格式：

true
手动渲染
false、空
自动渲染

示例：

...
<div dg-chart-widget="..." dg-chart-manual-render="true"></div>
...

dg-chart-on-*

绑定图表事件处理函数，*应替换为实际事件类型，比如：dg-chart-on-click。
具体的事件类型由底层图表渲染器定义，内置图表类型支持的事件类型参考内置图表类型-图表事件类型章节。

元素： <div>图表元素

必填： 否

格式：

//参数个数和格式由底层图表渲染器定义
function(...)
{
  ...
}

示例：

<!DOCTYPE html>
<html>
<head>
<script>
function clickHandler(event)
{
  alert("click");
};
</script>
</head>
<body>
  <div dg-chart-widget="..." dg-chart-on-click="function(event){  alert('click'); }"></div>
  <div dg-chart-widget="..." dg-chart-on-click="clickHandler"></div>
</body>
...

dg-chart-options

设置图表选项，比如：是否显示标题、是否显示图例、图例位置、坐标轴位置、图表样式等等。
具体的图表选项由底层图表渲染器定义，内置图表类型支持的图表选项参考内置图表类型-图表选项章节。另外，所有图表都支持一些通用图表选项，详细参考通用图表选项章节。
设置图表选项时，通常无需设置数据部分，图表在绘制时会自动从其绑定的数据集中读取数据，填充图表选项的数据部分。
此处的设置项会覆盖在定义图表-设置图表选项时设置的同名项。

必填： 否

元素： <body>、<div>图表元素。在<body>元素时，设置全局图表选项；在<div>图表元素时，仅设置单个图表选项，图表元素级设置将会继承全局设置。

格式：

{
  ...
}

示例：

<!DOCTYPE html>
<html>
<head>
<script>
var myChartOptions={ title: {show: false } };
</script>
</head>
<body dg-chart-options="{legend:{left:0}}">
  <div dg-chart-widget="..." dg-chart-options="{title:{show:false},legend:{top:0},grid:{top:40}}"></div>
  <div dg-chart-widget="..." dg-chart-options="myChartOptions"></div>
</body>
...

dg-chart-renderer

自定义图表渲染器，重写图表渲染、更新、销毁等逻辑。

元素： <div>图表元素

必填： 否

格式：

{
  ...
}

格式与图表渲染器相同，另参考chart.renderer()函数。

对于在定义图表时的自定义图表类型，这里的自定义图表渲染器应至少实现 render()、update()、destroy()函数；对于其他类型的图表，自定义图表渲染器的所有项都不是必须定义的，定义的项（比如update()函数）将会覆盖图表底层图表渲染器的对应项。

示例：

<!DOCTYPE html>
<html>
<head>
<script src="lib/jquery-4.0.0.min.js"></script>
<script>
var myChartRenderer =
{
  render: function(chart)
  {
    var ele = $(chart.element());
    $("<h1 />").text("图表渲染器示例").appendTo(ele);
    $("<div class='content' />").appendTo(ele);
  },
  update: function(chart, chartResult)
  {
    var ele = $(chart.element());
    var content = $("> .content", ele);
    content.empty();
    var dataSetBinds = chart.dataSetBindsMain();
    dataSetBinds = chart.dataSetBindsFetched(dataSetBinds, chartResult);
    for(let i=0; i<dataSetBinds.length; i++)
    {
      let datas = chart.resultDatasOf(chartResult, dataSetBinds[i]);
      $("<div />").text(JSON.stringify(datas)).appendTo(content);
    }
  },
  destroy: function(chart)
  {
    var ele = $(chart.element());
    ele.empty();
  }
};
</script>
</head>
<body>
<div dg-chart-widget="..." dg-chart-renderer="myChartRenderer"></div>
</body>
...

dg-chart-theme

自定义图表主题，包括文本色、背景色、字体尺寸等。

元素： <body>、<div>图表元素。在<body>元素时，设置全局图表主题；在<div>图表元素时，仅设置单个图表主题，图表元素级设置将会继承全局设置。

必填： 否

格式：

{
  ...
}

格式与图表主题相同，另参考chart.theme()函数。

示例：

<!DOCTYPE html>
<html>
<head>
<script>
var myChartTheme = { color: "#00FF00" };
</script>
</head>
<body dg-chart-theme="{color:'#FFF',backgroundColor:'#000'}">
  <div dg-chart-widget="..." dg-chart-theme="{color:'#FF0000',backgroundColor:'#0000FF'}"></div>
  <div dg-chart-widget="..." dg-chart-theme="myChartTheme"></div>
</body>
...

dg-dashboard-code

自定义看板脚本代码逻辑和插入位置。
看板脚本是一段JavaScript脚本，其中包含创建看板对象实例、初始化看板（调用dashboard.init()函数）、渲染看板（调用dashboard.render()函数）的代码，会自动插入看板展示页面。
看板脚本默认会插入在</body>前，如果在<body></body>元素内定义了 <script dg-dashboard-code></script> 元素，则会插入其中，在之后的代码中则可以直接使用看板对象。
在<script dg-dashboard-code></script>之后的<div>图表元素将不会被识别，需要通过异步加载图表的方式才能加载它们。

元素： <html>、<body></body>内的<script>

必填： 否

格式：

"instance"
仅创建看板对象实例
"init"
创建看板对象实例、初始化看板（调用dashboard.init()函数）
"render"、空
创建看板对象实例、初始化看板（调用dashboard.init()函数）、渲染看板（调用dashboard.render()函数）

示例：

在</body>前的JavaScript脚本里直接使用看板对象：

<!DOCTYPE html>
<html>
...
<body>
...
<script dg-dashboard-code></script>
<script>
//这里可以直接使用看板对象
var serverDate = dashboard.serverDate();
...
</script>
</body>
</html>

不自动渲染看板，在执行一些自定义代码后，手动渲染看板：

<!DOCTYPE html>
<html>
...
<body>
...
<script dg-dashboard-code="init"></script>
<script>
//执行其他代码
...
dashboard.render();
</script>
</body>
</html>

不自动初始化和渲染看板，在执行一些自定义代码后，手动初始化和渲染看板：

<!DOCTYPE html>
<html>
...
<body>
...
<script dg-dashboard-code="instance"></script>
<script>
//执行其他代码
...
//此处无需显式调用dashboard.init()函数初始化看板，
//dashboard.render()函数内部自动调用它
dashboard.render();
</script>
</body>
</html>

不自动初始化和渲染看板，在点击按钮后，初始化和渲染看板：

<!DOCTYPE html>
<html dg-dashboard-code="instance">
<head>
<script src="lib/jquery-4.0.0.min.js"></script>
<script>
$(function()
{
  $("#btn").click(function()
  {
    //此处无需显式调用dashboard.init()函数初始化看板，
    //dashboard.render()函数内部自动调用它
    dashboard.render();
  });
});
</script>
</head>
<body>
  <button id="btn">渲染看板</button>
</body>
</html>

dg-dashboard-form

定义看板表单，联动看板内任意图表。

元素： <form>

必填： 是（当希望将<form>绘制为看板表单时）

格式：

{
  ...
}

格式与看板表单配置相同，另参考dashboard.renderForm()函数。

示例：

<!DOCTYPE html>
<html>
<head>
<script>
var dashboarForm = {
  items: [
    {
      name: "地区", inputType: "select",
      inputPayload: [ "北京", "上海", "广州"],
      //将此输入项的值分别设置为chart0、chart1的第0个数据集的第0个参数值
      link: [ 0, {chart: 1} ]
    },
    {
      name:"日期", inputType:"date",
      //将此输入项的值分别设置为chart0、chart1的第0个数据集的第1个参数值
      link: [{param: 1}, {chart: 1, param: 1}]
    }
  ],
  //当表单提交时，联动图表chart0、chart1
  link: ["chart0", "chart1"]
};
</script>
</head>
<body>
  <form dg-dashboard-form="dashboarForm" class="dg-inline"></form>
  <div id="chart0" dg-chart-widget="..."></div>
  <div id="chart1" dg-chart-widget="..."></div>
</body>
</html>

系统内置了一些常用的看板表单布局样式类，可添加至<form>看板表单元素的class属性，具体包括：

样式类名	样式说明
`dg-inline`	表单内所有输入项、标签、输入框、提交按钮显示在单行内
`dg-col-2`	表单输入项条目分两列显示，提交按钮在新行中显示
`dg-col-3`	表单输入项条目分三列显示，提交按钮在新行中显示
`dg-col-4`	表单输入项条目分四列显示，提交按钮在新行中显示
`dg-col-5`	表单输入项条目分五列显示，提交按钮在新行中显示
`dg-item-inline`	表单输入项条目的标签、输入框在单行中显示，可与`dg-col-*`组合使用

dg-dashboard-fetcher

设置看板取数器，自定义看板内所有图表取数器（dg-chart-fetcher、 chart.fetcher()值）设置为"global"的数据提供逻辑。

元素： <body>

必填： 否

格式：

function(context){ ... }

格式与看板取数器相同，另参考dashboard.fetcher()函数。

示例：

<!DOCTYPE html>
<html>
<head>
<script>
function dashboardFetcher(context)
{
  var dashboardResult = { chartResults: {} };
  var chartResults = dashboardResult.chartResults;
  for(let i=0; i<context.chartQueries.length; i++){
    let chart = context.chartQueries[i].chart;
    let chartId = chart.id();
    chartResults[chartId] = { dataSetResults: [{ data: [ {name: "aaa", value: 10}, {name: "bbb", value: 60} ] }] };
  }
  return dashboardResult;
};
</script>
</head>
<body dg-dashboard-fetcher="dashboardFetcher">
  <div id="chart1" dg-chart-widget="..." dg-chart-fetcher="global"></div>
  <div id="chart2" dg-chart-widget="..." dg-chart-fetcher="global"></div>
  <div id="chart3" dg-chart-widget="..."></div>
</body>
...

上述示例中的chart1和chart2图表不会请求服务端加载数据，而是使用dashboardFetcher函数中的提供的数据更新图表， chart3图表则会照常请求服务端加载数据后更新图表。

dg-dashboard-listener

设置看板监听器，用于在看板渲染前/后、销毁前/后执行回调函数。

元素： <body>

必填： 否

格式：

{
  ...
}

格式与看板监听器相同，另参考dashboard.listener()函数。

示例：

<!DOCTYPE html>
<html>
<head>
<script>
var myDashboardListener =
{
  //在看板渲染前打印日志
  onRender: function(dashboard)
  {
    console.log("看板渲染前");
  }
};
</script>
</head>
<body dg-dashboard-listener="myDashboardListener">
...
</body>
</html>

dg-dashboard-var

自定义看板页面的看板对象变量名。
默认看板对象变量名为：window.dashboard。

元素： <html>

必填： 否

格式：

"..."

示例：

<!DOCTYPE html>
<html dg-dashboard-var="myDashboard">
<head>
<script src="lib/jquery-4.0.0.min.js"></script>
<script>
$(function()
{
  var user = myDashboard.user();
});
</script>
</head>
<body>
...
</body>
</html>

上述示例将看板对象变量名自定义为：myDashboard。

dg-load-chart-policy

设置看板异步加载图表策略，控制看板页面调用dashboard.loadChart()、 dashboard.loadCharts()、 dashboard.loadUnsolvedCharts()函数可异步加载的图表。

元素： <html>

必填： 否

格式：

"all"
可异步加载看板创建人有访问权限的所有图表
"none"
不可异步加载任何图表
"图表部件ID,图表部件ID,..."
仅可异步加载列表中指定图表部件ID（图表管理页面内的某行ID值）的图表
"permitted"、无
可异步加载当前打开看板的用户有访问权限的所有图表

示例：

<!DOCTYPE html>
<html dg-load-chart-policy="none">
<head>
...
</head>
<body>
...
</body>
</html>

<!DOCTYPE html>
<html dg-load-chart-policy="105b3bfae180057e89ae,27012828d1803f4893d5">
<head>
...
</head>
<body>
...
</body>
</html>

dg-map-handler

设置地图处理器，用于添加新地图、替换内置图表地图、处理地图名映射。

元素： <body>

必填： 否

格式：

{
  ...
}

格式与地图处理器相同，另参考dashboard.mapHandler()函数。

示例：

<body dg-map-handler="{values:{customMap:'map/custom.json', china: 'map/myChina.json'}}">
  <div dg-chart-widget="..." dg-chart-options="{mapName:'customMap'}">
</body>

上述示例中，会加载看板资源map/custom.json作为图表地图。

<!DOCTYPE html>
<html>
<head>
<script>
var parentMap = "江苏省";
var mapHandler =
{
  values:{ "江苏省南京市": "map/nanjing.json" },
  name: function(name)
  {
    return parentMap + name;
  }
};
</script>
</head>
<body dg-map-handler="mapHandler">
  <div dg-chart-widget="..." dg-chart-options="{mapName:'南京市'}">
</body>
</html>

上述示例中，在图表中指定了南京市地图，会加载江苏省南京市对应的map/nanjing.json看板资源作为图表地图。

看板元素属性

dg-chart-widget

dg-chart-local

dg-api-version

dg-chart-auto-resize

dg-chart-config-values

dg-chart-disable-tool

dg-chart-fetch-group

dg-chart-fetcher

dg-chart-link

dg-chart-listener

dg-chart-manual-render

dg-chart-on-*

dg-chart-options

dg-chart-renderer

dg-chart-theme

dg-dashboard-code

dg-dashboard-form

dg-dashboard-fetcher

dg-dashboard-listener

dg-dashboard-var

dg-load-chart-policy

dg-map-handler

上一章

下一章