看板源码设计模式
在看板管理页面，选中一条记录后，点击【设计】按钮，将打开看板设计页面。
对于
*.html看板模板文件，默认将处于【源码模式】，可以自由编辑HTML/JavaScript/CSS文本，也可以引入任意JavaScript/CSS库，
为看板模板中的元素添加dg-*属性，即可添加看板功能。
看板源码设计模式可以使用全部看板功能， 适用于熟悉前端开发的技术人员。
插入图表
在
<div>元素上添加dg-chart-widget或dg-chart-local属性，
即可将元素定义为图表元素，在看板展示时，图表元素将被绘制为对应的图表。
其中，dg-chart-widget属性的值应是图表部件ID值（图表管理页面内的某行ID值），
dg-chart-local属性的值应是{ ... }格式的图表定义对象。
点击【插入】菜单，可以在看板模板源码区的当前光标位置插入已有/新建/本地图表。
插入【选择/新建】图表
当光标位于
<div>元素标签内时，将为元素插入dg-chart-widget="..."属性代码；
当位于<div>元素的dg-chart-widget=""属性的""中时，将仅插入图表部件ID值；
否则，它将插入完整的<div dg-chart-widget="..."></div>元素代码。
关于
dg-chart-widget的详细用法，请参考dg-chart-widget章节。
插入【本地】图表
与上述插入规则类似，不同的是，插入的元素属性是
dg-chart-local而非dg-chart-widget，
其属性值也不是图表部件ID，而直接是通过{ ... }格式定义的本地图表对象。
比如，对于系统内置的
日期时间插件，插入的本地图表元素代码是：
<div dg-chart-local="{'plugin':'org.datagear.v2.datetime'}"></div>
关于
dg-chart-local的详细用法，请参考dg-chart-local章节。
设置图表配置
在
<div>图表元素上添加dg-chart-config-values属性，即可设置图表配置。
...
<div dg-chart-widget="..."
dg-chart-config-values="{titleText:'自定义标题'}">
</div>
...
关于
dg-chart-config-values的详细用法，请参考dg-chart-config-values章节。
在看板可视设计模式下，可以通过【编辑 - 图表配置】功能打开图表配置表单界面直观地配置图表。
设置图表选项
在
<body>元素上添加dg-chart-options属性，即可设置全局图表选项；
在<div>图表元素上添加dg-chart-options属性，即可设置指定图表选项。
图表选项的格式由选定图表类型对应的图表插件定义，
系统内置图表类型的图表选项格式参考内置图表类型-图表选项章节。
比如，设置内置
折线图第一个线条颜色为红色、类型为断线式、宽度为6像素：
...
<body dg-chart-options="{title:{show:false}}">
<div dg-chart-widget="..."
dg-chart-options="{
series:[{
lineStyle:{
color: 'red',
type: 'dashed',
width: 6
}
}]
}">
</div>
</body>
...
关于
dg-chart-options的详细用法，请参考dg-chart-options章节。
图表选项可以在设计看板时设置，也可以在定义图表时设置，看板中的设置会覆盖定义图表时的同名项，
详细参考定义图表-设置图表选项章节。
设置图表主题
在
<body>元素上添加dg-chart-theme属性，即可设置全局图表主题；
在<div>图表元素上添加dg-chart-theme属性，即可设置指定图表主题。
比如，将所有图表的文本颜色设置为红色、背景色设置为蓝色，指定图表文本颜色设为黄色：
...
<body dg-chart-theme="{color:'red',backgroundColor:'blue'}">
<div dg-chart-widget="..." dg-chart-theme="{color:'yellow'}">
</div>
</body>
...
关于
dg-chart-theme的详细用法，请参考dg-chart-theme章节。
图表联动
在
<div>图表元素上添加dg-chart-link属性，即可设置图表联动功能。
下面的示例中，当点击
chart0的图表条目时，将条目数据对象的name属性值设置为
chart1图表的第0个数据集的第0个参数值，然后刷新chart1图表。
<div id="chart0" dg-chart-widget="..." dg-chart-link="{target:'chart1',data:{'data.name':0}}"></div>
<div id="chart1" dg-chart-widget="..."></div>
关于
dg-chart-link的详细用法，请参考dg-chart-link章节。
处理图表事件
在
<div>图表元素上添加dg-chart-on-*属性，即可监听和处理图表事件。
下面的示例，为图表绑定了一个
dg-chart-on-click事件处理函数，在点击图表条目时，打开一个新窗口并传递其name参数。
...
<script>
function handleClick(event)
{
window.open("detail.html?name=" + event.data.name);
};
</script>
...
<div dg-chart-widget="..." dg-chart-on-click="handleClick"></div>
...
关于
dg-chart-on-*的详细用法，请参考dg-chart-on-*章节。
扩展图表地图
下面的示例，新添加了一个
customMap名称地图，并替换了内置的china地图。
<body dg-map-handler="{values:{customMap:'map/custom.json',china:'map/myChina.json'}}">
<div dg-chart-widget="..." dg-chart-options="{mapName:'customMap'}">
</body>
对于内置图表类型，
也可以直接在其图表选项中指定地图路径，而无需预先定义
dg-map-handler属性。
示例：
<div dg-chart-widget="..." dg-chart-options="{mapName:'map/custom.json'}">
关于
dg-map-handler的详细用法，请参考dg-map-handler章节。
看板表单
在
<form>元素上添加dg-dashboard-form属性，即可定义看板表单。
看板表单主要用于定义看板级的交互表单，在表单提交时联动看板内的任意图表。
下面的示例，
<form>元素将会被绘制为包含一个地区文本框的看板表单，
在表单提交时，地区文本框的值将被分别设置为chart0、
chart1的对应数据集参数值，然后刷新这两个图表。
...
<form dg-dashboard-form="{
items: { name: '地区', link: [ 0, { chart: 1 } ] },
link: { target: [ 'chart0', 'chart1' ] }
}">
</form>
<div id="chart0" dg-chart-widget="..."></div>
<div id="chart1" dg-chart-widget="..."></div>
...
关于
dg-dashboard-form的详细用法，请参考dg-dashboard-form章节。
禁用内置图表工具
在
<body>元素上添加dg-chart-disable-tool属性，即可全局禁用内置图表工具（参数/数据）；
在<div>图表元素上添加dg-chart-disable-tool属性，即可禁用指定内置图表工具（参数/数据）。
示例：
...
<body dg-chart-disable-tool="true">
<div dg-chart-widget="..." dg-chart-disable-tool="{param:false}">
</div>
</body>
...
关于
dg-chart-disable-tool的详细用法，请参考dg-chart-disable-tool章节。
监听看板状态
在
<body>元素上添加dg-dashboard-listener属性（看板监听器），即可监听看板渲染/销毁状态。
下面的示例，在看板指定元素内显示当前用户信息。
...
<script>
var dashboardListener =
{
onRender: function(dashboard)
{
var user = dashboard.user();
var ele = document.getElementById("userInfo");
ele.innerHTML = "<b>"+user.realName+"</b>";
}
};
</script>
...
<body dg-dashboard-listener="dashboardListener">
<div id="userInfo"></div>
</body>
...
关于
dg-dashboard-listener的详细用法，请参考dg-dashboard-listener章节。
监听图表状态
在
<div>图表元素上添加dg-chart-listener属性（图表监听器），即可监听图表渲染/更新/销毁状态。
下面的示例，在图表更新前对数据进行处理：
...
<script>
var listener=
{
onUpdate: function(chart, chartResult)
{
var dataSetBind = chart.dataSetBindMain();
var data = chart.resultDataOf(chartResult, dataSetBind);
//处理data
...
chart.resultDataOf(chartResult, dataSetBind, data);
}
};
</script>
...
<div dg-chart-listener="listener" dg-chart-widget="..."></div>
...
关于
dg-chart-listener的详细用法，请参考dg-chart-listener章节。
自定义图表
对于在定义图表时的自定义图表类型，可以在此通过
dg-chart-renderer完全实现图表渲染/更新/销毁等功能；
对于其他类型的图表，也可以在此通过定义dg-chart-renderer的部分函数，从而重写部分功能。
由于在定义图表时的自定义图表操作未绑定任何数据标记，
因而这里定义的图表渲染器只能采用硬编码的方式访问图表绑定数据集的详细数据结构，
使其只能在局部范围内使用，如果希望在系统内全局复用，应自定义图表插件，详细参考自定义图表插件章节。
示例：
...
<script>
var myChartRenderer=
{
render: function(chart)
{
var ele = chart.element();
ele.innerText = "render";
},
update: function(chart, chartResult)
{
var ele = chart.element();
ele.innerText = JSON.stringify(chartResult);
},
destroy: function(chart)
{
var ele = chart.element();
ele.innerText = "";
}
};
</script>
...
<div dg-chart-widget="..." dg-chart-renderer="myChartRenderer"></div>
...
关于
dg-chart-renderer的详细用法，请参考dg-chart-renderer章节。
处理看板参数
在打开看板展示页面时，为页面URL添加的参数，
可以使用dashboard.renderContextValue()
或者chart.renderContextValue()函数获取。
下面的示例中，看板接受一个
map名称的传入参数，并使用它设置地图图表的地图名。
...
<script>
var dashboardListener =
{
onRender: function(dashboard)
{
var map = (dashboard.renderContextValue("map") || "china" );
var chart = dashboard.chart("chart1");
var options = chart.options();
options["mapName"] = map;
}
};
</script>
...
<body dg-dashboard-listener="dashboardListener">
<div id="chart1" dg-chart-widget="【地图图表部件ID】"></div>
</body>
...
上述看板的打开URL则可传入如下示例参数：
//打开上海地图图表 /dv/【看板ID】/?map=shanghai //打开重庆地图图表 /dv/【看板ID】/?map=chongqing
下面的示例中，看板接受一个
name名称的传入参数，并使用它设置图表参数化数据集的参数值：
...
<script>
var chartListener =
{
onRender: function(chart)
{
var name = chart.renderContextValue("name");
chart.dataSetParamValueFirst("name", name);
}
};
</script>
...
<div dg-chart-listener="chartListener" style="width:300px;height:300px;"
dg-chart-widget="..."></div>
...
上述看板的打开URL则可传入如下示例参数：
/dv/【看板ID】/?name=shanghai /dv/【看板ID】/?name=chongqing
获取看板对象
每一个看板在展示时，页面都会自动添加一个看板对象，为渲染看板页面提供支持。
另外，它也封装了很多可扩展看板功能的API，比如：获取图表、异步加载图表、获取当前用户信息等等。
看板对象的默认变量名为：
window.dashboard。
示例：
...
<head>
<script>
document.addEventListener("DOMContentLoaded", (event) =>
{
//此时可以获取和使用dashboard变量
var user = dashboard.user();
});
</script>
</head>
<body>
...
</body>
...
自定义看板交互
对于包含参数化数据集的图表，
除了通过简单的看板表单实现交互，
也可以自定义表单，结合
chart.dataSetParamValue*()、
chart.refresh()等函数，实现自定义看板交互。
下面的示例，使用图表监听器设置图表数据的初始日期范围，
并提供了一个交互表单，用户可自主筛选指定日期范围的图表数据。
...
<script src="lib/jquery-4.0.0.min.js"></script>
<script>
var listener =
{
rendered: function(chart)
{
var dsb = chart.dataSetBindMain();
chart.dataSetParamValues(dsb, {fromDate: "2026-05-01", toDate: "2026-05-31"});
}
};
$(function()
{
$("#form").submit(function()
{
var fromDate = $("[name='fromDate']", this).val();
var toDate = $("[name='toDate']", this).val();
var chart = dashboard.chart("chart");
var dsb = chart.dataSetBindMain();
chart.dataSetParamValues(dsb, {fromDate: fromDate, toDate: toDate});
chart.refresh();
return false;
});
});
</script>
...
<form id="form">
<label>起始日期：</label> <input name="fromDate">
<label>结束日期：</label> <input name="toDate">
<button type="submit">查询</button>
</form>
<div id="chart" dg-chart-widget="..." dg-chart-listener="listener" dg-chart-disable-tool="true"></div>
...
异步加载图表
在看板中，除了通过为静态
<div>元素添加dg-chart-widget属性的方式定义图表，
也可以使用
dashboard.loadChart()、
dashboard.loadCharts()、
dashboard.loadUnsolvedCharts()
函数异步加载图表。
其中，dashboard.loadUnsolvedCharts()函数可以加载看板页面内所有动态添加的图表元素，
当看板网页完全由客户端JS脚本渲染时（比如前端框架Vue、React等），可以使用此函数异步加载所有客户端JS创建的图表元素。
异步加载图表权限受
<html>元素上的dg-load-chart-policy控制。
示例：
<!DOCTYPE html>
<html>
<head>
<script src="lib/jquery-4.0.0.min.js"></script>
<script>
$(function()
{
$("#loadButton1").click(function()
{
dashboard.loadChart($("#chart1"), "【图表部件ID】");
});
$("#loadButton2").click(function()
{
var chart2Ele = $("<div id='chart2'></div>").appendTo(document.body);
dashboard.loadChart(chart2Ele, "【图表部件ID】",
function(chart)
{
alert("chart ["+chart.id+"] loaded");
});
});
$("#removeButton2").click(function()
{
dashboard.removeChart("chart2");
});
var chartWidgetIds = ["【图表部件ID-0】", "【图表部件ID-1】", "【图表部件ID-2】"];
for(var i=0; i<chartWidgetIds.length; i++)
$(document.body).append("<div dg-chart-widget='"+chartWidgetIds[i]+"'></div>");
//异步加载上述动态添加的三个图表
dashboard.loadUnsolvedCharts();
});
</script>
</head>
<body>
<button id="loadButton1">加载图表1</button>
<div id="chart1" style="width:300px;height:300px;"></div>
<button id="loadButton2">加载图表2</button>
<button id="removeButton2">删除图表2</button>
</body>
</html>
手动渲染图表
在看板页面加载时，默认会自动将看板内的所有
<div>图表元素（设置了dg-chart-widget属性）渲染为图表，
如果希望阻止某个图表的自动渲染，则应为<div>图表元素添加dg-chart-manual-render属性，
并在需要时调用chart.render()函数渲染图表。
下面的示例中，点击【显示】按钮后，将显示并渲染图表，点击【隐藏】按钮后，将隐藏并销毁图表。
...
<script src="lib/jquery-4.0.0.min.js"></script>
<script>
$(function()
{
$("#showBtn").click(function()
{
var panel = $("#chartPanel");
var chart = dashboard.chart("chart");
panel.show();
chart.render();
});
$("#hideBtn").click(function()
{
var panel = $("#chartPanel");
var chart = dashboard.chart("chart");
panel.hide();
chart.destroy();
});
});
</script>
...
<button id="showBtn">显示</button>
<button id="hideBtn">隐藏</button>
<div id="chartPanel" style="display:none;width:50vw;height:50vh;">
<div id="chart" dg-chart-widget="..." dg-chart-manual-render="true" style="width:100%;height:100%;"></div>
</div>
...
如果
<div>图表元素处于<template></template>或者其他虚拟元素中，
也应设置其dg-chart-manual-render属性，
在元素真正挂载后再调用chart.render()函数渲染图表。
关于
dg-chart-manual-render的详细用法，请参考dg-chart-manual-render章节。
手动渲染看板
在
<html>元素上添加dg-dashboard-code="instance"属性，即可控制手动渲染看板；
在<body>元素内添加<script dg-dashboard-code="instance"></script>，
即可控制看板对象代码插入位置以及手动渲染看板。
下面的示例中，打开看板页面时不会自动渲染看板，在点击【渲染看板】按钮后，才执行渲染看板。
<!DOCTYPE html>
<html dg-dashboard-code="instance">
<head>
<script src="lib/jquery-4.0.0.min.js"></script>
<script>
$(function()
{
$("#btn").click(function()
{
dashboard.render();
});
});
</script>
</head>
<body>
<button id="btn">渲染看板</button>
...
</body>
</html>
下面的示例中，在执行了一些操作后，再执行渲染看板。
<!DOCTYPE html> <html> ... <body> ... ... //在此处插入看板对象代码 <script dg-dashboard-code="instance"></script> <script> //执行其他代码 ... dashboard.render(); </script> </body> </html>
关于
dg-dashboard-code的详细用法，请参考dg-dashboard-code章节。