配置图表 - CUBA 框架. 展示图表和地图

1.2. 配置图表

图表通过 Chart 组件进行展示，该组件可以作为全局的画布（canvas）。图表类型通过子类型接口定义，该接口继承了 Chart 接口。

图表可以通在界面 XML 描述或者界面控制器中创建。此时需要在 XML 描述中加入相应的 chart 命名空间：

<window xmlns="http://schemas.haulmont.com/cuba/window.xsd"
        xmlns:chart="http://schemas.haulmont.com/charts/charts.xsd"
        ...>

不同图表类型对应的 XML 元素：

chart:xyChart – XYChart – 散点图
chart:serialChart – SerialChart – 序列图
chart:pieChart – PieChart – 饼图
chart:funnelChart – FunnelChart – 漏斗图
chart:gaugeChart – AngularGaugeChart – 仪表盘图
chart:radarChart – RadarChart – 雷达图
chart:ganttChart – GanttChart – 甘特图
chart:stockChart – StockChart – 股票图

每种图表类型有其本身的属性和方法，这些属性和方法是从 AmCharts 库的相应图表拷贝过来的。图表的属性和方法的文档可以参阅： http://docs.amcharts.com/3/javascriptcharts 。

下列元素可以用来为所有类型的图表做声明式的配置：

chart:allLabels – 包含 label 元素，带有标签文字和其它属性。标签可以放在图表的特定位置，比如：

Figure 1. chart:allLabels

<chart:allLabels>
    <chart:label x="200"
                 y="700"
                 text="You can place a label at any position on the chart"
                 color="DARKBLUE"
                 align="CENTER"
                 rotation="-30"/>
</chart:allLabels>

chart:balloon – 配置鼠标悬浮在图表上时显示的气球（提示窗）的样式，示例：

Figure 2. chart:balloon

<chart:graphs>
    <chart:graph balloonText="[[category]]: [[value]] m/s"
                 bullet="ROUND"
                 fillAlphas="0.3"
                 valueField="value"/>
</chart:graphs>
<chart:balloon adjustBorderColor="false"
               color="WHITE"
               horizontalPadding="10"
               verticalPadding="8"/>

气球的文字通过每个图表的 balloonText 属性来定义。

additionalFields 属性

可以在图表的所有字段中插入图表的数据值，比如 titleField, valueField, category, value, description, percents, open 等等，另外，HTML 中也能使用。

也可以使用 additionalFields 属性从数据提供方获取更多的实体属性。通过这个属性可以将实体属性传递到图表的查询语句中，之后将数据返回给 UI。因此可以在图表的配置中直接使用实体属性的名称。

在下面的例子中，title 是图表的标题，category 是 category 轴的值，value 是 value 轴的值，optional 是 IncomeExpenses 实体属性，取出来用来插入到 balloonText 中：

<chart:serialChart additionalFields="optional"
                   addClassNames="true"
                   categoryField="year"
                   dataContainer="incomeExpensesDc"
                   startDuration="1">
    <chart:graphs>
        <chart:graph alphaField="alpha"
                     balloonText="&lt;span style='font-size:12px;'&gt;[[title]] in [[category]]:&lt;br&gt; &lt;span style='font-size:20px;'&gt;[[value]]&lt;/span&gt; [[optional]]&lt;/span&gt;"
                     dashLengthField="dashLengthColumn"
                     title="Income"
                     type="COLUMN"
                     valueField="income"/>
        <...>
    </chart:graphs>
</chart:serialChart>

Figure 3. additionalFields

字段列表可以通过英文逗号分隔的字符串声明式添加：

additionalFields="income,expense,vat"

或者通过编程的方式，在界面控制器中添加：

List<String> fields = Arrays.asList("income", "expense", "vat");
ganttChart.setAdditionalFields(fields);

chart:chartScrollbar (对于序列图和散点图有效) – 图表的滚动条。

可以设置具体图表通过滚动条进行缩放，示例：

Figure 4. chart:chartScrollbar

<chart:chartScrollbar graph="g1"
                      autoGridCount="true"
                      scrollbarHeight="30"/>

通过 chart:chartScrollbarSettings 元素可以对滚动条的属性进行定制化设置。

<chart:chartScrollbarSettings graph="stockGraph"
                              usePeriod="10mm"
                              position="TOP"/>

另外，甘特图可以有一个 chart:valueScrollbar 元素用来做 value 轴的滚动，chart:chartScrollbar 用来做 category 轴的缩放。

Figure 5. chart:valueScrollbar

<chart:valueScrollbar autoGridCount="true"
                      color="BLACK"/>
<chart:chartScrollbar autoGridCount="true"
                      color="DARKOLIVEGREEN"/>

chart:cursor – 可选元素，能在图标上添加光标；光标跟着鼠标指针走，展示图表上对应点的数值小弹窗。

Figure 6. chart:cursor

<chart:chartCursor cursorAlpha="1"
                   cursorColor="#258cbb"
                   cursorPosition="MOUSE"
                   limitToGraph="g1"
                   pan="true"
                   valueLineAlpha="0.2"
                   valueLineBalloonEnabled="true"
                   valueLineEnabled="true"
                   valueZoomable="true"/>

chart:data – 可选元素，用来做数据绑定。一般在做原型的时候使用。
chart:export – 可选元素，可以启用图表导出。默认的导出实现会在图表上添加一个浮动的 download 按钮：

Figure 7. chart:export

chart:guides – 水平/垂直参考线。

Figure 8. chart:guides

<chart:guides>
    <chart:guide category="2001"
                 dashLength="2"
                 fillAlpha="0.2"
                 fillColor="#CC0000"
                 inside="true"
                 label="fines for speeding increased"
                 labelRotation="90"
                 toCategory="2003"/>
    <chart:guide category="2007"
                 dashLength="2"
                 inside="true"
                 label="motorcycle fee introduced"
                 labelRotation="90"
                 lineAlpha="1"
                 lineColor="#CC0000"/>
</chart:guides>

chart:legend – 定义图表图例的元素，示例：

Figure 9. chart:legend

<chart:legend autoMargins="false"
              marginRight="20"
              markerType="CIRCLE"
              position="RIGHT"
              valueText="[[category]]: [[value]] %"/>

chart:nativeJson – 图表的 JSON 配置。

chart:titles – 图表标题，示例：

Figure 10. chart:titles

<chart:titles>
    <chart:title alpha="1"
                 bold="true"
                 color="DARKSLATEGREY"
                 size="20"
                 tabIndex="0"
                 text="Main title"/>
    <chart:title alpha="0.5"
                 color="BISQUE"
                 size="12"
                 text="Subtitle"/>
</chart:titles>

chart:responsive – 图表的响应式插件。

此插件可以自动调整图表的大小以适应不同的屏幕分辨率。关于 responsive 插件的更多信息可以参阅 AmCharts website。

responsive 元素需要包含嵌套的 rules 元素，这里可以定义适配的规则。可以设置图表是否显示图例、轴标题、参考线、图表标题、缩放控制器，或者将标签移入图表区域等：

<chart:responsive enabled="true">
    <chart:rules>
        <chart:rule maxWidth="400">
            <![CDATA[
            {
                "precision": 2,
                "legend": {
                  "enabled": false
                },
                "valueAxes": {
                  "inside": true
                }
            }
            ]]>
        </chart:rule>
    </chart:rules>
</chart:responsive>

任何配置属性都可以设置为 null；此时，系统会使用默认值（除了 AmCharts 文档中提到的特殊情况）。

在界面控制器配置图表也是按照相同的逻辑。可以配置单一属性，也可以配置组合对象：

pieChart.setWidth("700px");
pieChart.setTitleField("description")
        .setValueField("value")
        .setStartAngle(312)
        .setLegend(new Legend()
                .setMarkerType(MarkerType.CIRCLE)
                .setPosition(LegendPosition.RIGHT)
                .setMarginRight(80))
        .addLabels(
                new Label()
                    .setText("Sample Chart")
                    .setSize(26)
                    .setBold(true)
                    .setAlign(Align.CENTER),
                new Label()
                    .setText("extra information")
                    .setAlign(Align.RIGHT))
        .setLabelTickColor(Color.GOLDENROD)
        .setColors(Arrays.asList(
                    Color.valueOf("#446493"),
                    Color.valueOf("#5E3D2C"),
                    Color.valueOf("#D0A557")))
        .setDataProvider(dataProvider);

展示图表使用的信息可以使用 web 模块的主语言消息包进行覆盖或者本地化。在 CUBA GitHub 已经有一些本地化语言包。