透视表展示 - CUBA 框架. 展示图表和地图

3. 透视表展示

PivotTable 是带有拖拽功能的表格组件，通过这个组件可以将数据集合转换成汇总表格，并且可以通过 2D 的拖拽 UI 来操作。在 CUBA Studio 组件库就可以使用该组件的全部功能。

PivotTable 基于外部 JavaScript 库 - https://github.com/nicolaskruchten/pivottable 。可以在作者的网站上找到更多关于 PivotTable 的例子： http://nicolas.kruchten.com/pivottable/examples/ 。

该组件的 XML 名称： pivotTable

实现该组件的 block： Web Client

Figure 46. 透视表

在界面 XML 描述中定义组件的示例：

<chart:pivotTable id="tipsPivotTable"
                  dataContainer="tipsDc"
                  renderer="HEATMAP">
    <chart:properties>
        <chart:property name="row"/>
        <chart:property name="totalBill"/>
        <chart:property name="tip"/>
        <chart:property name="sex"/>
        <chart:property name="smoker"/>
        <chart:property name="day"/>
        <chart:property name="time"/>
        <chart:property name="size"/>
    </chart:properties>
    <chart:aggregation mode="SUM_OVER_SUM">
        <chart:property name="tip"/>
        <chart:property name="totalBill"/>
    </chart:aggregation>
    <chart:rows>
        <chart:row value="sex"/>
        <chart:row value="smoker"/>
    </chart:rows>
    <chart:columns>
        <chart:column value="day"/>
        <chart:column value="time"/>
    </chart:columns>
    <chart:sortersFunction>
        function(attr){
            if(attr=="Day"){
                return $.pivotUtilities.sortAs(["Mon","Tue","Wed","Thu","Fri","Sat","Sun"]);
            }
        }
    </chart:sortersFunction>
</chart:pivotTable>

pivotTable 的 XML 元素

properties - 在 pivotTable 内使用的一组属性的键值对映射。键是数据容器中属性的名称，值是本地化语言的名称。

derivedProperties - 可以向原始数据容器添加新属性，这些属性派生自现有属性。此元素是键值映射，其中键是生成的属性的名称，值是生成此属性的 JavaScript 函数。
- 元素内部的 derivedProperty 元素需要定义 caption 属性，此属性的值会被当作键值使用。
- function 元素用作 derivedProperty 的值。

hiddenProperties - 不需要展示在 UI 的一组属性。该属性值可以设置为 properties 的键值或者生成属性的名称（比如 derivedProperties 的键值）。该属性只对可编辑的 pivotTable 有效。

hiddenFromAggregations - 不在聚合参数下拉框显示的一组属性。

hiddenFromDragDrop - 不在 UI 可拖拽部分显示的一组属性。

columns - 作为表格列使用的一组属性。该属性值可以设置为 properties 的键值或者生成属性的名称。

columnOrder - 渲染时列数据的展示顺序。

rows - 作为表格行使用的一组属性。该属性值可以设置为 properties 的键值或者生成属性的名称。

rowOrder - 渲染时行数据的展示顺序。

exclusions - 键值映射，其中键是属性的名称（properties 键值或生成的属性的名称），值是要在渲染时不包括的属性值列表。该属性只对可编辑的 pivotTable 有效。

inclusions - 键值映射，其中键是属性的名称（properties 键值或生成的属性的名称），值是要渲染的属性值列表。该属性只对可编辑的 pivotTable 有效。

filterFunction - JavaScript 函数，用来做过滤。

renderers - 定义渲染函数的集合，这个集合需要在 UI 中的可用渲染器列表中显示。
- default 属性用来设置一个默认的渲染器。当组件加载时，选择的渲染器会当作默认的使用。
- 内部的 renderer 元素可以使用 type 属性来设置一个预制的渲染器：AREA_CHART 、 BAR_CHART 、 COL_HEATMAP 、 HEATMAP 、 HORIZONTAL_BAR_CHART 、 HORIZONTAL_STACKED_BAR_CHART 、 LINE_CHART 、 ROW_HEATMAP 、 SCATTER_CHART 、 STACKED_BAR_CHART 、 TABLE_BAR_CHART 、 TABLE 、 TREEMAP 、 TSV_EXPORT。
  
  只对可编辑的 pivotTable 有效。

rendererOptions - 定义渲染器的参数。事实上只有两种渲染器能做自定义设置：
- 全部的 heatmap 渲染器。可以通过 JavaScript 代码设置热力单元的颜色。
- 全部的 chart 渲染器。参数可以用来设置图表的大小。

sortersFunction - JavaScript 函数，用来做行和列标题的排序。

pivotTable 的聚合（aggregation）属性

aggregation - 设置聚合函数，用来对每个单元格的结果做聚合。

aggregation 属性：
- mode 属性可以用来设置一个预制的聚合函数。
- caption 展示在 UI 的本地化语言的描述。
- custom - 如果是 true，那么会忽略 mode 的值，而使用内部的 function 元素指定的 JavaScript 函数。
  
  aggregation 元素：
- function - 包含聚合函数的 JavaScript 代码。
- property - 用来作为聚合函数输入参数的属性列表。该属性值可以设置为 properties 的键值或者生成属性的名称。只对非可编辑 pivotTable 有效。
  
  示例：
  <chart:aggregation mode="SUM_OVER_SUM" custom="true"> <chart:property name="tip"/> <chart:property name="Total Bill"/> </chart:aggregation>

aggregationProperties - 定义在聚合器的下拉列表中显示的属性列表。该属性值可以设置为 properties 的键值或者生成属性的名称。只对可编辑 pivotTable 有效。
```
<chart:aggregationProperties>
    <chart:property name="tip"/>
    <chart:property name="totalBill"/>
</chart:aggregationProperties>
```

aggregations - 定义需要在 UI 中的可用聚合器下拉列表中显示的聚合器集合。

aggregations 属性：
- default 属性用来设置一个预制的聚合函数。当组件加载时，选择的函数会当作默认的使用。
- 内部的 aggregation 元素跟 aggregation 的使用方法相同，除了内部的 property 元素。只对可编辑 pivotTable 有效。
  
  示例：
  <chart:aggregations default="COUNT"> <chart:aggregation caption="Count"/> <chart:aggregation mode="SUM_OVER_SUM"/> </chart:aggregations>

pivotTable 属性

dataContainer - 设置在界面 XML 描述的 data 部分定义的一个数据容器。必须是 collectionDataContainer 类型。

editable - 如果是 true，UI 会显示用来操作数据的元素，否则只显示数据。

menuLimit - 设置双击显示菜单的最大条目数量。如果记录数大于这个值，则会显示相应的信息。只对可编辑 pivotTable 有效。

renderer - 启用设置一个预制的数据渲染器。只对非可编辑 pivotTable 有效。

showColTotals - 定义是否显示列总数。默认值是 true。只对表格渲染器有效。

showRowTotals - 定义是否显示行总数。默认值是 true。只对表格渲染器有效。

showUI - 控制是否在可编辑的透视表中显示 UI 元素。默认值是 true。

autoSortUnusedProperties - 定义在 UI 是否要对没使用的属性进行排序。只对可编辑 pivotTable 有效。

unusedPropertiesVertical - 定义没使用的属性是要以垂直方式展示（true）还是以水平方式展示（false 或者默认情况）。如果设置为数字，那么当属性名称的字符组合长度超过此数字，则属性将垂直显示。

pivotTable 的监听器

addCellClickListener - 为 PivotTable 添加单元格点击事件监听器。CellClickEvent 事件只在表格渲染器会触发（TABLE, HEATMAP, TABLE_BAR_CHART, COL_HEATMAP, ROW_HEATMAP）。
```
tipsPivotTableUI.addCellClickListener(event -> {
    showNotification("Value: " + event.getValue() + ",\n"
        + "Filters applied: " + event.getFilters());
});
```

addRefreshListener - 为 PivotTable 添加刷新事件监听器。RefreshEvent 事件只在可编辑 PivotTable 会触发。
```
tipsPivotTableUI.addRefreshListener(event -> {
    showNotification("Row order :" + event.getRowOrder() + ",\n"
        + "Inclusions: " + event.getInclusions());
});
```
RefreshEvent 事件中有下列值可用： aggregation, aggregationProperties, columns, columnOrder, exclusions, inclusions, renderer, rowOrder, rows.

pivotTable 的属性: autoSortUnusedProperties - dataContainer - editable - height - menuLimit - renderer - unusedPropertiesVertical - width
pivotTable 的元素: aggregation - aggregationProperties - aggregations - columnOrder - columns - derivedProperties - exclusions - filterFunction - hiddenFromAggregations - hiddenFromDragDrop - hiddenProperties - inclusions - properties - rendererOptions - renderers - rowOrder - rows - sortersFunction
API: addCellClickListener - addRefreshListener