7. 看板元素属性参考

7. 看板元素属性参考

dg-chart-auto-resize

功能：设置当浏览器窗口调整尺寸后，是否自动调整图表尺寸。

必填：否

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

格式：true 启用尺寸自动调整；false 禁用尺寸自动调整。默认值为：false。

示例：

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

dg-chart-disable-setting

功能：设置是否禁用图表交互设置功能，当图表是其他图表的联动目标时，有时希望禁用交互设置。

必填：否

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

格式：true 禁用交互设置；false 启用交互设置。默认值为：false。

示例：

<body dg-chart-disable-setting="true">
  <div dg-chart-widget="..." dg-chart-disable-setting="false"></div>
</body>

dg-chart-link

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

必填：否

元素：<div>图表元素

格式：

{
  //可选，触发联动的图表事件类型、事件类型数组，默认为"click"
  trigger: "..."、["...", ...],
  //必选，联动目标图表元素ID、ID数组
  target: "..."、["...", ...],
  //可选，联动数据参数映射表，没有则不设置任何参数值
  data:
  {
    数据属性名 : 图表数据集参数索引对象、[ 图表数据集参数索引对象, ... ],
    ...
  }
}

或者，也可以是上述格式对象的数组：

[
  { ... },
  { ... }
]

其中

数据属性名可以是图表事件对象包含的图表条目数据对象（chartEvent.data）的属性名，也可以是原始数据对象（chartEvent.originalData）的属性名，它对应的属性值将作为映射源值。

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

图表数据集参数索引对象用于定义数据属性名对应的值要设置到的目标图表数据集参数，格式为：

{
  //可选，目标图表在上述target数组中的索引数值，默认为：0
  chart: ...,
  //可选，目标图表数据集数组的索引数值，默认为：0
  dataSet: ...,
  //可选，目标图表数据集的参数数组索引/参数名，默认为：0
  param: ...,
  //可选，自定义数据属性值至目标参数值处理函数，返回目标参数值
  //sourceValue 数据属性值
  //chartEvent 图表事件对象
  value: function(sourceValue, chartEvent){ return ...; }
}

或者，可简写为图表数据集参数索引对象的”param”属性值。

示例：

<head>
<script type="text/javascript">
var myChartLink={ target: 'chart6', data: { name: 0 } };
</script>
</head>
<body>
//当点击chart0图表条目时，
//将图表事件对象数据的"name"属性值设置为chart1图表的第0个数据集的第0个参数值，
//将图表事件对象数据的"value"属性值设置为chart1图表的第0个数据集的第1个参数值，
//将图表事件对象数据的"value"属性值设置为chart1图表的第1个数据集的第0个参数值，
//然后刷新chart1图表
<div id="chart0" dg-chart-widget="..."
    dg-chart-link="{target:'chart1',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属性值，系统自动生成的值在每次刷新时都可能是随机的。

图表联动功能的实现原理是：为源图表绑定事件处理函数，将图表事件对象的数据值设置为目标图表数据集的对应参数值，然后刷新图表。

图表事件对象（chartEvent）的详细说明文档请参考图表事件对象章节。

dg-chart-listener

功能：设置图表监听器。

必填：否

元素：<body>、<div>图表元素。当在<body>元素设置时，可定义全局监听器；当在<div>图表元素设置时，仅定义单个图表监听器，图表元素级设置将会覆盖全局设置。

格式：

{
  //可选，渲染图表完成回调函数
  //chart 图表对象
  render: function(chart){ ... },
  //可选，更新图表数据完成回调函数
  //chart 图表对象
  //results 更新的数据集结果对象数组
  update: function(chart, results){ ... },
  //可选，渲染图表前置回调函数，返回false将阻止渲染图表
  //chart 图表对象
  onRender: function(chart){ ... },
  //可选，更新图表数据前置回调函数，返回false将阻止更新图表数据
  //chart 图表对象
  //results 要更新的数据集结果对象数组
  onUpdate: function(chart, results){ ... }
}

示例：

<head>
<script type="text/javascript">
var chartListener=
{
  render: function(chart){ alert(chart.id + " rendered"); },
  update: function(chart, results){ alert(chart.id + " updated"); }
};
</script>
</head>
<body dg-chart-listener="chartListener">
  <div dg-chart-widget="..." dg-chart-listener="{render:function(chart){ ... }}"></div>
</body>

dg-chart-map

功能：设置地图类图表所使用的地图名称、地图资源URL，如果不设置，则默认为中国地图。

必填：否

元素：<div>图表元素

格式：字符串

系统内置支持的地图名称如下表所示：

china、中国	china-contour、中国轮廓	china-cities、中国城市	world、世界
anhui、安徽	aomen、澳门	beijing、北京	chongqing、重庆
fujian、福建	gansu、甘肃	guangdong、广东	guangxi、广西
guizhou、贵州	hainan、海南	hebei、河北	heilongjiang、黑龙江
henan、河南	hubei、湖北	hunan、湖南	jiangsu、江苏
jiangxi、江西	jilin、吉林	liaoning、辽宁	neimenggu、内蒙古
ningxia、宁夏	qinghai、青海	shandong、山东	shanghai、上海
shanxi、山西	shanxi1、陕西	sichuan、四川	taiwan、台湾
tianjin、天津	xianggang、香港	xinjiang、新疆	xizang、西藏
yunnan、云南	zhejiang、浙江

如果图表需要使用上表中没有的地图，则可在看板编辑页面上传地图JSON文件资源，然后将此属性的值设置为地图JSON文件资源的相对URL即可。

或者，也可通过dg-chart-map-urls 属性定义看板内上传的所有地图JSON文件资源的名称映射表，将此属性值直接设置为映射名称。

示例：

<div dg-chart-widget="..." dg-chart-map="北京">
<div dg-chart-widget="..." dg-chart-map="map/custom.json">

系统内置的地图类图表都支持将数据集的某一列标记为图表地图，用于支持地图随数据一起刷新的场景，地图标记列的值将优先于dg-chart-map属性。

dg-chart-map-urls

功能：设置全局地图名映射表，并可扩展或替换内置地图。

必填：否

元素：<body>

格式：字符串

示例：

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

在展示看板时，则会自动加载看板资源map/custom.json作为上述图表的地图。

dg-chart-on-*

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

必填：否

元素：<div>图表元素

格式：function(chartEvent){ … }

常用的图表事件处理函数属性有：
单击：dg-chart-on-click
双击：dg-chart-on-dblclick
鼠标按下：dg-chart-on-mousedown
鼠标松开：dg-chart-on-mouseup
鼠标进入：dg-chart-on-mouseover
鼠标离开：dg-chart-on-mouseout

示例：

<head>
<script type="text/javascript">
function clickHandler(chartEvent)
{
  alert("click");
};
var chartEventHandlers=
{
  dblClickHandler: function(chartEvent){ alert("dblclick"); },
  mouseoverHandler: function(chartEvent){ alert("mouseover"); },
};
</script>
</head>
<body>
  <div dg-chart-widget="..." dg-chart-on-click="function(chartEvent){  alert('click'); }"></div>
  <div dg-chart-widget="..." dg-chart-on-click="clickHandler"></div>
  <div dg-chart-widget="..." dg-chart-on-dblclick="chartEventHandlers.dblClickHandler"></div>
  <div dg-chart-widget="..." dg-chart-on-mouseover="chartEventHandlers.mouseoverHandler"></div>
</body>

图表事件对象（chartEvent）的详细说明文档请参考图表事件对象章节。

dg-chart-options

功能：自定义图表选项，比如是否显示标题、是否显示图例、图例位置、坐标轴位置等等。

必填：否

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

格式：{ … }

系统内置的各类图表选项格式说明如下表所示：

图表类型	选项说明
折线图、柱状图、饼图、仪表盘、散点图、雷达图、漏斗图、地图、 K线图、热力图、树图、旭日图、桑基图、关系图	Echarts官方图表，图表选项参考Echarts官方文档配置项手册
词云图	Echarts扩展图表，图表选项参考echarts-wordcloud项目说明文档
表格	HTML图表，图表选项如下所示： `{` `title: //标题` `{` `show: true, //是否显示` `text: “…” //自定义标题文本` `color: ‘…’,` `backgroundColor: ‘…’”,` `… //其他CSS样式` `},` `table:` `{` `header: //表头` `{` `color: ‘…’,` `backgroundColor: ‘…’,` `… //其他CSS样式` `},` `row: //行` `{` `odd: //偶数行` `{` `color: ‘…’,` `backgroundColor: ‘…’,` `… //其他CSS样式` `},` `even: //奇数行` `{` `color: ‘…’,` `backgroundColor: ‘…’,` `… //其他CSS样式` `},` `hover: //鼠标悬浮行样式` `{` `color: ‘…’,` `backgroundColor: ‘…’,` `… //其他CSS样式` `},` `selected: //选中行样式` `{` `color: ‘…’,` `backgroundColor: ‘…’,` `… //其他CSS样式` `}` `},` `//自定义单元格渲染函数` `//value 单元格值` `//name 单元格列名` `//rowIndex 单元格行索引` `//columnIndex 单元格列索引` `//row 单元格所在的行数据对象` `renderValue: function(value, name,` `rowIndex, columnIndex, row)` `{` `return “…”;` `}` `}` `}`
标签卡	HTML图表，图表选项如下所示： `{` `label:` `{` `//标签名样式` `name:` `{` `color: ‘…’,` `backgroundColor: ‘…’,` `… //其他CSS样式` `},` `//标签值样式` `value:` `{` `color: ‘…’,` `backgroundColor: ‘…’,` `… //其他CSS样式` `}` `}` `}`

示例：

<head>
<script type="text/javascript">
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-theme属性。

dg-chart-renderer

功能：自定义图表渲染器，用于自定义图表渲染逻辑。

必填：当图表类型为自定义时必填

元素：<div>图表元素

格式：同图表渲染器

当图表类型为自定义时，自定义图表渲染器需至少定义 render、update函数；而对于非自定义类型的图表，自定义图表渲染器的所有项都不是必须定义的，定义的项（比如update函数）将会覆盖图表内置图表渲染器的对应项。

示例：

<head>
<script type="text/javascript">
var myChartRenderer=
{
  render: function(chart)
  {
    chart.elementJquery().append("<div>render custom chart</div>");
  },
  update: function(chart, results)
  {
    chart.elementJquery().append("<div>update custom chart</div>");
  }
};
</script>
</head>
<body>
<div dg-chart-widget="..." dg-chart-renderer="myChartRenderer"></div>
</body>

dg-chart-theme

功能：自定义图表主题，比如前景色、背景色等。

必填：否

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

格式：

{
  //可选，前景颜色
  color:'..',
  //可选，背景颜色
  backgroundColor:'..',
  //可选，实际背景色，当backgroundColor值为'transparent'时，用于设置实际页面背景色
  actualBackgroundColor:'',
  //可选，图表元素渐变色跨度数值，默认为10
  gradient: ...,
  //可选，边框颜色
  borderColor:'...',
  //可选，边框宽度
  borderWidth:'...',
  //可选，标题颜色
  titleColor:'...',
  //可选，图例颜色
  legendColor:'...',
  //可选，图形条目颜色
  graphColors:['...','...','...'],
  //可选，值域图形条目颜色
  graphRangeColors:['...','...'],
  //可选，提示框主题
  tooltipTheme:{color:'...',backgroundColor:'...',borderColor:'...'},
  //可选，高亮块主题
  highlightTheme:{color:'...',backgroundColor:'...',borderColor:'...'}
}

示例：

<head>
<script type="text/javascript">
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-chart-widget

功能：设置图表元素对应的图表部件ID，即图表管理模块列表内的某行的ID值。

必填：是

元素：<div>

格式：字符串

示例：

<div dg-chart-widget="c8d5b5df0172452c37b7"></div>

dg-dashboard-form

功能：定义看板表单，设置看板级的交互操作表单，联动看板内任意图表。

必填：是

元素：<form>

格式：

{
  //必选，表单输入项对象、数组
  items: 表单输入项对象、 [ 表单输入项对象, ... ],
  //可选，表单提交操作时执行的联动图表设置
  link: 图表联动设置对象,
  //可选，表单提交按钮文本
  submitText: "..."
}

其中

表单输入项对象格式为：

{
  //必选，输入项名称
  name: "...",
  //可选，默认值
  value: ...,
  //可选，输入项标签
  label: "...",
  //可选，输入项类型："STRING" 字符串；"BOOLEAN" 布尔值；"NUMBER" 数值。默认值为："STRING"
  type: "...",
  //可选，是否必填：true 必填；false 选填。默认为false
  required: ...,
  //可选，输入框类型：
  //"text" 文本框；"select" 下拉框；"date" 日期框；"time" 时间框；"datetime" 日期时间框；
  //"radio" 单选框；"checkbox" 复选框；"textarea" 文本域。默认值为："text"
  inputType: "...",
  //可选，输入框配置，与定义数据集-设置参数输入框类型表格中的输入框配置格式相同
  inputPayload: ...,
  //可选，此表单输入项值要联动设置到的目标图表数据集参数
  link: 图表数据集参数索引对象、[ 图表数据集参数索引对象, ... ]
}

图表联动设置对象格式为：

 {
  //必选，联动目标图表元素ID、ID数组
  target: "..."、["...", ...],
  //可选，联动数据设置
  data:
  {
    表单输入项名称 : 图表数据集参数索引对象、[ 图表数据集参数索引对象, ... ],
    ...
  }

或者，可简写为图表联动设置对象的target属性值。

图表数据集参数索引对象用于定义表单输入项值要设置到的目标图表数据集参数，格式为：

{
  //可选，目标图表在上述图表联动设置对象的target数组中的索引数值，默认为：0
  chart: ...,
  //可选，目标图表数据集数组的索引数值，默认为：0
  dataSet: ...,
  //可选，目标图表数据集的参数数组索引/参数名，默认为：0
  param: ...,
  //可选，自定义映射源值至目标参数值处理函数
  //sourceValue 表单输入项值
  //formData 看板表单数据对象：{ 表单输入项名称 : 表单输入项值, ... }
  //form 看板表单DOM对象
  value: function(sourceValue, formData, form){ return ...; }
}

或者，可简写为图表数据集参数索引对象的param属性值。

示例：

<html>
<head>
<script type="text/javascript">
var dashboarForm =
{
  items:
  [
    {
      name: "地区", inputType: "select",
      inputPayload:
      [
        {name: '北京',value: '北京'},
        {name: '上海',value: '上海'},
        {name: '广州',value: '广州'}
      ],
      //将此输入项的值分别设置为chart0、chart1的第0个数据集的第0个参数值
      link: [{chart: 0}, {chart: 1}]
    },
    {
      name:"日期", inputType:"date",
      //将此输入项的值分别设置为chart0、chart1的第0个数据集的第1个参数值
      link: [{chart: 0, 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-listener

功能：设置看板监听器。

必填：否

元素：<body>

格式：

{
  //可选，渲染看板完成回调函数
  //dashboard 看板对象
  render: function(dashboard){ ... },
  //可选，渲染图表完成回调函数
  //dashboard 看板对象
  //chart 图表对象
  renderChart: function(dashboard, chart){ ... },
  //可选，更新图表数据完成回调函数
  //dashboard 看板对象
  //chart 图表对象
  //results 已更新的数据集结果对象数组
  updateChart: function(dashboard, chart, results){ ... },
  //可选，渲染看板前置回调函数，返回false将阻止渲染看板
  //dashboard 看板对象
  onRender: function(dashboard){ ... },
  //可选，渲染图表前置回调函数，返回false将阻止渲染图表
  //dashboard 看板对象
  //chart 图表对象
  onRenderChart: function(dashboard, chart){ ... },
  //可选，更新图表数据前置回调函数，返回false将阻止更新图表数据
  //dashboard 看板对象
  //chart 图表对象
  //results 已更新的数据集结果对象数组
  onUpdateChart: function(dashboard, chart, results){ ... }
}

示例：

<head>
<script type="text/javascript">
var myDashboardListener =
{
    //为所有图表名称添加"图表-"前缀
    onRenderChart: function(dashboard, chart)
    {
        chart.name = "图表-" + chart.name;
    }
};
</script>
</head>
<body dg-dashboard-listener="myDashboardListener">
...
</body>
</html>

dg-chart-listener设置会覆盖看板监听器的 renderChart、 updateChart、 onRenderChart、 onUpdateChart函数。

dg-dashboard-var

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

必填：否

元素：<html>

格式：字符串

示例：

将看板对象变量名自定义为：myDashboard

<html dg-dashboard-var="myDashboard">
<head>
<script type="text/javascript">
$(document).ready(function()
{
    var myChart = myDashboard.getChart(0);
});
</script>
</head>
<body>
...
</body>
</html>

dg-echarts-theme

功能：设置Echarts图表的原生Echarts主题。

必填：否

元素：<body>、<div>图表元素。当在<body>元素设置时，可定义全局主题；当在<div>图表元素设置时，仅定义单个图表主题，图表元素级设置将会覆盖全局设置。

格式：字符串

示例：

<head>
<script type="text/javascript">
echarts.registerTheme("myTheme", {...});
</script>
</head>
<body>
<div dg-chart-widget="..." dg-echarts-theme="myTheme"></div>
</body>

要设置的原生Echarts主题名必须是已在Echarts中注册过的。另外，此设置将会覆盖dg-chart-theme设置。