5. 可视化数据分析

5. 可视化数据分析

点击主页左侧的数据分析栏，即可打开数据分析模块。

数据集管理用于定义SQL查询数据集，这些数据将用作图表绘制；
图表管理用于定义图表类型，指定绘制图表所需要的数据集；
看板管理用于定义包含多个图表和其他元素的HTML页面，并最终展示给用户；

5.1. 定义数据集

打开数据集添加界面，填写名称、数据源、查询SQL语句，执行预览，保存后，即完成数据集定义。

其中，SQL语句可以是任意格式的查询语句，例如：

SELECT NAME, MAX(VALUE) AS VALUE FROM T_ANALYSIS GROUP BY NAME

参数化数据集

参数化数据集主要用于支持交互式图表，当关联了参数化数据集的图表展示时，用户可自由定义其参数值，从而展示用户需求数据的图表。定义参数化数据集步骤如下：

首先，编写参数化的SQL语句，例如：

SELECT NAME, VALUE FROM T_ANALYSIS WHERE NAME = '${name}'

然后，点击界面右侧的[参数]选项卡，添加name参数：

名称：name，类型：字符串，必填：是

点击[预览]选项卡的按钮，在弹出的参数值面板中填写一个name参数值（例如：张三），执行预览，可以看到最终执行的SQL语句为：

SELECT NAME, VALUE FROM T_ANALYSIS WHERE NAME = '张三'

预览过后，保存即可。

选中SQL语句编辑区的参数名后执行添加参数操作，可自动设置参数名。

参数化SQL语句语法

插值：
${参数名}

条件判断：
<#if 条件></#if>
<#if 条件>…<#else>…</#if>
<#if 条件>…<#elseif 条件>…<#else>…</#if>

数组、集合遍历：
<#list 参数名 as item>…${item}…</#list>
<#list 参数名 as item>…${item}…<#sep>元素间要插入的分隔内容</#list>

条件：

参数名??
当用户填写参数名对应的值时为true，否则为false，可用于处理非必填参数。
参数名
布尔参数值为true时。
!参数名
布尔参数值为false时。
参数名 == “…”、参数名 != “…”
字符串参数值等于、不等于。
参数名 == …、参数名 != …、参数名 gt …、参数名 gte …、参数名 lt …、参数名 lte …
数值参数值等于、不等于、大于、大于等于、小于、小于等于。
条件1 || 条件2、条件1 && 条件2、 !条件
条件组合：或、与、非。

示例：

SELECT NAME, VALUE FROM T_ANALYSIS
WHERE NAME = '${name}'
<#if 最小值??>
AND VALUE >= ${最小值}
<#else>
AND VALUE IS NOT NULL
</#if>
<#if 名称集合??>
AND NAME IN
(
  <#list 名称集合 as item> '${item}' <#sep>,</#list>
)
</#if>
<#if ascByName>
ORDER BY NAME ASC
</#if>
<#if limitCount??>
limit 0, ${limitCount}
</#if>

对应上述示例的数据集参数为：

名称	类型	必填
name	字符串	是
最小值	数值	否
名称集合	字符串	否
ascByName	布尔值	是
limitCount	数值	否

参数化SQL语句的解析底层采用了Freemarker，详细语法请参考其官方文档。

JSON数据集、JSON文件数据集等同样支持上述参数化语法。

设置参数输入框类型

在定义数据集参数时，可选设置参数输入框类型（默认为文本框），当图表展示时，数据集参数设置面板将被绘制为指定类型的输入框。

系统目前支持的输入框类型为：文本框、下拉框、日期、时间、日期时间、单选框、复选框、文本域，详细设置如下表所示：

输入框类型	输入框配置格式	参数值是否为集合
文本框	无	否
下拉框	单选下拉框选项名/值配置： `[ 待选项名值对象, … ]` 多选下拉框选项名/值配置： `{ multiple: true, items: [ 待选项名值对象, … ] }` 待选项名值对象格式为：{ name: “…”, value: … }，当名、值相同时，则可简写为字符串：”…”	多选时：是；单选时：否
日期	可选，日期格式配置： `{ format: ‘…’ }` 默认为： `{ format: ‘Y-m-d’ }` 日期值将会是如2020-07-26的字符串。	否
时间	可选，时间格式配置： `{ format: ‘…’ }` 默认为： `{ format: ‘H:i:s’ }` 时间值将会是如04:01:00的字符串。	否
日期时间	可选，日期时间格式配置： `{ format: ‘…’ }` 默认为： `{ format: ‘Y-m-d H:i:s’ }` 日期时间值将会是如2020-07-26 04:01:00的字符串。	否
单选框	单选框选项名/值配置： `[ 待选项名值对象, … ]` 待选项名值对象格式为：{ name: “…”, value: … }，当名、值相同时，则可简写为字符串：”…”	否
复选框	复选框选项名/值配置： `[ 待选项名值对象, … ]` 待选项名值对象格式为：{ name: “…”, value: … }，当名、值相同时，则可简写为字符串：”…”	是
文本域	无	否

其中，日期格式各符号说明如下表所示：

符号	描述
Y	年份（4位长度）
m	月份（2位长度，01-12）
d	天（2位长度，01-31）
H	小时（2位长度24时制，00-23）
i	分钟（2位长度，00-59）
s	秒数（2位长度，00-59）

5.2. 定义图表

打开图表添加界面，填写名称、选择图表类型、添加数据集、设置更新间隔，保存后，即完成图表定义。

图表可添加多个数据集，一个数据集通常被绘制为图表中的一个图形条目系列；设置更新间隔，可用于支持页面定时刷新数据。

设置数据标记

在添加了数据集后，需要点击条目右侧的按钮设置数据集各列的数据标记，用于定义各列的图表绘制维度。

每一类图表都定义了各自的数据标记项，在切换图表类型时，可能需要重新设置数据标记。

设置数据集别名

数据集别名可在图表展示时定义数据集对应的图例名、系列名，如果不设置，则取数据集名称。

图表通常根据数据集别名来决定数据集对应的图形条目系列，因此，当一个图表多次添加同一个数据集、添加多个同名数据集时，应该为它们设置不同的别名。

设置数据集参数值

如果添加的数据集是参数化数据集，则可点击相应条目右侧的[参数值]按钮，设置其展示时的初始参数值，也可不在此设置，而在图表展示界面动态设置。

如果在图表展示时有数据集未设置必填的参数值，那么需要用户点击图表右上角的[设置]按钮，填写参数值后，图表才会绘制。

注意：在图表展示界面设置的数据集参数值不会被保存。

5.3. 定义看板

看板

看板使用原生的HTML网页作为看板模板，为看板模板中的任意<div>元素添加一个dg-chart-widget属性，并将属性值设置为一个图表部件ID（图表管理页面内的某行的ID值），即可将此<div>定义为一个图表元素。在展示看板时，所有的图表元素都将被绘制成它所指定的图表。

在看板管理界面点击[添加]按钮，在打开页面中填写名称，然后在HTML模板编辑区内填写如下看板代码：

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
</head>
<body>
<div dg-chart-widget="[a chart widget id]" style="width:300px;height:300px;"></div>
</body>
</html>

保存后，即完成了一个简单看板的定义。

注意：[a chart widget id]应设置为图表管理页面内的某行的ID值。

5.4. 导入看板

在看板管理界面点击[导入]按钮，即可将任意HTML导入为看板模板。导入文件可以是单个HTML文件，也可以是包含HTML文件及其依赖所有资源的ZIP压缩包。例如：

index.html

或者

my-dashboard.zip

  |--index.html
  |--conent.html
  |--style
      |--dashboard.css
  |--images
      |--bg.png
      |--icon.png
  |--script
      |--dashboard.js

注意：导入ZIP压缩包前，确保看板文件、文件夹都直接位于压缩包根目录下，不要再内嵌一级目录。

5.5. 管理看板资源

在看板编辑界面，可以管理看板的HTML模板所使用的资源，比如图片、CSS、JS等。
例如，上传一个名称为bg.png的图片资源后，将它设置为看板的背景：

...
<style type="text/css">
.my-dashboard{
  background: url(bg.png);
}
</style>
...
<body class="my-dashboard">
...
</body>
...

5.6. 内置看板资源

看板内置了一些资源库，这些资源库会在展示看板时自动引入，主要包括：

jquery-1.12.4.js
echarts-4.7.0.js
datagear-chartFactory.js

图表初始化支持库，变量名为：window.chartFactory
datagear-dashboardFactory.js

看板初始化支持库，变量名为：window.dashboardFactory
datagear-chartSupport.js

图表渲染支持库，变量名为：window.chartFactory.chartSupport
旧版的window.chartSupport已弃用，将在未来版本移除。
datagear-chartForm.js

图表交互设置支持库，变量名为：window.chartFactory.chartForm
旧版的window.chartForm已弃用，将在未来版本移除。
chartPluginManager.js

图表插件管理库，变量名为：window.chartFactory.chartPluginManager
旧版的window.chartPluginManager已弃用，将在未来版本移除。
jquery.datetimepicker.full.min.js

日期输入框组件支持库

5.7. 看板主题

看板内置了两个CSS样式类：dg-dashboard、dg-chart，它们与系统肤色匹配，可将它们应用于HTML模板中，以支持看板主题，使用方式如下所示：

...
<body class="dg-dashboard">
...
<div class="dg-chart" dg-chart-widget="..."></div>
...
</body>
...

5.8. 设置地图图表

在看板中添加的地图类图表（基本地图、散点值地图、关系地图等），默认只展示中国地图，如果要使用其他地图，则需要设置图表元素上的dg-chart-map属性。例如，设置为北京地图：

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

详细的地图设置请参考dg-chart-map、 dg-chart-map-urls章节。

系统内置的地图类图表（基本地图、散点值地图、关系地图）都支持将数据集的某一列标记为图表地图，用于支持地图随数据一起刷新的场景，此时则不必设置dg-chart-map属性。

5.9. 设置图表主题

在body元素、div图表元素上定义dg-chart-theme属性，即可设置全局、指定图表主题。

例如，将所有图表的前景色设置为红色、背景色设置为蓝色：

<body dg-chart-theme="{color:'red',backgroundColor:'blue'}">
...
</body>

详细的图表主题设置请参考dg-chart-theme章节。

对于Echarts类的图表，也可以使用dg-echarts-theme属性设置原生的Echarts主题。

5.10. 设置图表选项

在div图表元素上定义dg-chart-options属性，即可设置图表选项。

例如，设置指定echarts图表不显示标题、图例顶部对齐、坐标系间隔顶部40像素：

<div dg-chart-widget="..." dg-chart-options="{title:{show:false},legend:{top:0},grid:{top:40}}"></div>

详细的图表选项设置请参考dg-chart-options章节。

5.11. 图表联动

在div图表元素上定义dg-chart-link属性，即可设置图表联动功能。

下面的示例中，当点击chart0的图表条目时，将条目数据对象的name属性值设置为 chart1图表的第0个数据集的第0个参数值，然后刷新chart1图表：

<div id="chart0" dg-chart-widget="..." dg-chart-link="{target:'chart1',data:{name:0}}"></div>
<div id="chart1" dg-chart-widget="..."></div>

详细的图表联动设置请参考dg-chart-link章节。

5.12. 看板表单

看板表单主要用于定义看板级的交互表单，在表单提交时联动看板内的任意图表。为看板模板内的任意多个form表单元素添加dg-dashboard-form属性，即可将表单定义为看板表单。

下面的示例中，<form>元素将会被绘制为包含一个地区文本框的看板表单，在表单提交时，地区文本框的值将被分别设置为chart0、 chart1的对应数据集参数值，然后刷新这两个图表：

<form dg-dashboard-form="
        items: { name: '地区', link: [ 0, {chart:1} ] },
        link: [ 'chart0', 'chart1' ]
    ">
</form>
<div id="chart0" dg-chart-widget="..."></div>
<div id="chart1" dg-chart-widget="..."></div>

详细的看板表单设置请参考dg-dashboard-form章节。

5.13. 使用看板API

每一个看板在展示时，页面都会自动添加一个看板对象，用于为渲染看板页面提供支持。另外，它也封装了很多可扩展看板功能的API，比如：获取图表、删除图表、异步加载图表等等。

看板对象的默认变量名为：window.dashboard。

下面的示例，在点击button1按钮时，调用看板对象的 getChart()函数，获取图表元素ID为chart1的图表对象，然后调用它的refreshData()函数刷新图表数据：

...
<head>
<script type="text/javascript">
$(document).ready(function()
{
  $("#button1").click(function()
  {
    var chart1 = dashboard.getChart("chart1");
    chart1.refreshData();
  });
});
</script>
</head>
<body>
...
  <button id="button1" type="button">刷新</button>
  <div id="chart1" dg-chart-widget="..."></div>
...
</body>
</html>

刷新图表数据可使用更便捷的dashboard.refreshData()函数。

可通过dg-dashboard-var 自定义看板对象变量名。

5.14. 异步加载图表

在看板模板内，除了通过为静态<div>元素设置dg-chart-widget属性定义图表外，也可以使用看板对象的 loadChart 函数异步加载图表：

示例：

<html>
<head>
<script type="text/javascript">
$(document).ready(function()
{
    $("#loadButton1").click(function()
    {
        dashboard.loadChart($("#chart1"), "[a chart widget id]");
    });
    $("#loadButton2").click(function()
    {
        var $chart2 = $("<div id="chart2"></div>").appendTo(document.body);
        dashboard.loadChart($chart2, "[a chart widget id]",
        function(chart)
        {
            alert("chart ["+chart.id+"] loaded");
        });
    });
    $("#removeButton2").click(function()
    {
        dashboard.removeChart("chart2");
    });
});
</script>
</head>
<body>
    <button id="loadButton1">加载图表1</button>
    <div id="chart1"></div>
    <button id="loadButton2">加载图表2</button>
    <button id="removeButton2">删除图表2</button>
</body>
</html>

5.1### 5. 传入看板参数

在打开看板页面时，为页面URL添加的参数，将会被写入看板对象的渲染上下文内，看板页面可以使用renderContextAttr()获取这些传入参数。

例如，使用如下URL打开看板：

/analysis/dashboard/show/[看板ID]/?param0=aaa&param1=bbb&param1=ccc

以下方式可得到上述参数值：

$(document).ready(function()
{
    var p0 = dashboard.renderContextAttr("param0"); // "aaa"
    var p1 = dashboard.renderContextAttr("param1"); // ["bbb", "ccc"]
});

下面的示例看板接受一个map名称的传入参数，并使用它设置地图图表的地图名称：

<html>
<head>
...
<script type="text/javascript">
var myChartListener =
{
    onRender: function(chart)
    {
        var map = (dashboard.renderContextAttr("map") || "beijing" );
        chart.map(map);
    }
};
</script>
</head>
<body>
<div dg-chart-listener="myChartListener" dg-chart-widget="[地图图表部件ID]"></div>
</body>
</html>

上述看板的打开URL则可传入参数如：

打开上海地图图表：
/analysis/dashboard/show/[看板ID]/?map=shanghai
打开重庆地图图表：
/analysis/dashboard/show/[看板ID]/?map=chongqing

下面的示例看板接受一个name名称的传入参数，并使用它设置图表参数化数据集的参数值：

<html>
<head>
...
<script type="text/javascript">
var myChartListener =
{
    onRender: function(chart)
    {
        var name = (dashboard.renderContextAttr("name") || "beijing" );
        chart.dataSetParamValue(0, "sqlParam", name);
    }
};
</script>
</head>
<body>
<div dg-chart-listener="myChartListener" dg-chart-widget="[图表部件ID]"></div>
</body>
</html>

上述看板的打开URL则可传入参数如：

/analysis/dashboard/show/[看板ID]/?name=shanghai
/analysis/dashboard/show/[看板ID]/?name=chongqing

5.16. 分享

点击图表列表、看板列表右上的【分享】按钮，可以将选定记录分享给指定用户、指定用户组、全部匿名用户、全部用户，分享后，目标用户将可以访问图表、看板的展示链接。

当希望将图表、看板的展示链接嵌入外部应用时（通常以iframe的方式），应当将其分享给全部匿名用户或者全部用户，这样，不需登录即可访问分享的展示链接。