docs: add tutorial for calculatedField

docs/assets/guide/en/data_analysis/pivot_table_dataAnalysis.md

@@ -68,7 +68,10 @@ dataConfig application example:
 
 ### 1. Totals
 
+#### VTable to calculate subtotals configuration:
+
 [option description](../../option/PivotTable#dataConfig.totals)
+
 Configuration example:
 
 ```
@@ -95,6 +98,17 @@ dataConfig: {
 
 Online demo：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-total
 
+#### Custom summary data
+
+If you need to customize summary data, you do not want VTable to calculate the subtotals. In addition to the above configuration, you also need to include the corresponding summary data in the data passed to VTable. In this way, VTable will analyze it internally and display it as summary data instead of using VTable's summary value.
+
+<div style="width: 50%; text-align: center;">
+<img src="https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/guide/custom-total-demo.png" />
+<p>Custom subtotal total sample code</p>
+</div>
+
+Specific example: https://visactor.io/vtable/demo/data-analysis/pivot-analysis-custom-total
+
 ### 2. Sorting rules
 
 VTable's pivot table supports four sorting methods: natural sorting of dimension values, specified dimension value order, indicator value sorting, and custom sorting.
@@ -124,6 +138,7 @@ Online demo：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-sort-
 ### 3. Filter rules
 
 [option description](../../option/PivotTable#dataConfig.filterRules)
+
 Configuration example:
 
 ```
@@ -141,6 +156,7 @@ Online demo：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-filte
 ### 4. Aggregation method
 
 [option description](../../option/PivotTable#dataConfig.aggregationRules)
+
 Configuration example:
 
 ```
@@ -206,6 +222,7 @@ The sales indicator in this record is a non-numeric value, and it is required to
 ### 5. Derive Field
 
 [option description](../../option/PivotTable#dataConfig.derivedFieldRules)
+
 Configuration example:
 
 ```
@@ -223,6 +240,34 @@ Configuration example:
 
 Online demo：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-derivedField
 
+### 6. Pivot table calculated fields
+
+[option description](../../option/PivotTable#dataConfig.calculatedFieldRules)
+
+Configuration example:
+
+```
+dataConfig: {
+  calculatedFieldRules:[
+    {
+      key: 'AvgPrice',
+      dependIndicatorKeys: ['Quantity', 'Sales'],
+      calculateFun: dependValue => {
+        return dependValue.Sales / dependValue.Quantity;
+      }
+    }
+  ],
+}
+```
+
+Configuration explanation:
+
+- key: The key unique identifier of the calculated field, which can be used as a new indicator and configured in indicators for display in the pivot table.
+- dependIndicatorKeys: The indicators that the calculated field depends on, which can be the corresponding indicator fields in records. If the dependent indicator is not in records, it needs to be configured in aggregationRules, specifying the aggregation rules and indicatorKey to be used in dependIndicatorKeys.
+- calculateFun: the calculation function of the calculated field, the function parameter is the value of the dependent indicator.
+
+Specific example: https://visactor.io/vtable/demo/data-analysis/pivot-analysis-calculatedField
+
 ## Data analysis process
 
 Dependent configuration: dimensions, indicators and dataConfig.

docs/assets/guide/zh/data_analysis/pivot_table_dataAnalysis.md

@@ -68,7 +68,10 @@ dataConfig 应用举例：
 
 ### 1. 数据汇总规则
 
+#### VTable 来计算小计总计配置：
+
 [option 说明](../../option/PivotTable#dataConfig.totals)
+
 配置示例：
 
 ```
@@ -95,6 +98,17 @@ dataConfig: {
 
 具体示例：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-total
 
+#### 自定义汇总数据
+
+如果需要自定义汇总数据，不期望 VTable 来计算小计总计值。除了需要配置上述配置外，还需要传入 VTable 的数据中需要包含对应的汇总数据。这样 VTable 内部会分析将其作为汇总数据而不使用 VTable 的汇总值来展示
+
+ <div style="width: 50%; text-align: center;">
+     <img src="https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/guide/custom-total-demo.png" />
+    <p>自定义小计总计示例代码</p>
+  </div>
+
+具体示例：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-custom-total
+
 ### 2. 排序规则
 
 VTable 的透视表支持四种排序方式：维度值自然排序、指定维度值顺序，指标值排序、自定义排序。
@@ -124,6 +138,7 @@ VTable 的透视表支持四种排序方式：维度值自然排序、指定维
 ### 3. 过滤规则
 
 [option 说明](../../option/PivotTable#dataConfig.filterRules)
+
 配置示例：
 
 ```
@@ -141,6 +156,7 @@ filterRules: [
 ### 4. 聚合方式
 
 [option 说明](../../option/PivotTable#dataConfig.aggregationRules)
+
 配置示例：
 
 ```
@@ -207,6 +223,7 @@ dataConfig:{
 ### 5. 派生字段
 
 [option 说明](../../option/PivotTable#dataConfig.derivedFieldRules)
+
 配置示例：
 
 ```
@@ -224,6 +241,34 @@ dataConfig:{
 
 具体示例：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-derivedField
 
+### 6. 透视表计算字段
+
+[option 说明](../../option/PivotTable#dataConfig.calculatedFieldRules)
+
+配置示例：
+
+```
+     dataConfig: {
+        calculatedFieldRules: [
+          {
+            key: 'AvgPrice',
+            dependIndicatorKeys: ['Quantity', 'Sales'],
+            calculateFun: dependValue => {
+              return dependValue.Sales / dependValue.Quantity;
+            }
+          }
+        ],
+     }
+```
+
+配置解释说明：
+
+- key: 计算字段的 key 唯一标识，可以当做新指标，用于配置在 indicators 中在透视表中展示。
+- dependIndicatorKeys：计算字段依赖的指标，可以是在 records 中具体对应的指标字段。如果依赖的指标不在 records 中，则需要在 aggregationRules 中配置，具体指明聚合规则和 indicatorKey 以在 dependIndicatorKeys 所使用。
+- calculateFun：计算字段的计算函数，依赖的指标值作为参数传入，返回值作为计算字段的值。
+
+具体示例：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-calculatedField
+
 ## 数据分析过程
 
 依赖配置：维度，指标及 dataConfig。

docs/assets/option/en/table/pivotTable.md

@@ -220,7 +220,7 @@ export interface Total {
 
 ### derivedFieldRules(DerivedFieldRules)
 
-Add derived fields
+Add a derived field. The vtable will generate a new field based on the rules defined by the derived field and add the new field to the data. The new field can be used as a dimension item or an indicator item.
 
 ```
 export type DerivedFieldRules = DerivedFieldRule[];
@@ -235,6 +235,26 @@ export interface DerivedFieldRule {
 }
 ```
 
+### calculatedFieldRules (CalculatedFieldRules)
+
+Calculated fields are similar to the calculated fields in Excel pivot tables. New indicator values can be calculated through calculated fields, and they are all recalculated based on the summary results. Note: Different from derived fields.
+
+```
+export type CalculateddFieldRules = CalculateddFieldRule[];
+```
+
+```
+export interface CalculatedFieldRule {
+  /** Unique identifier, which can be used as the key of a new indicator and used to configure indicators to be displayed in a pivot table. */
+  key: string;
+  /** The indicator that the calculated field depends on, which can be the corresponding indicator field in records or not the field in data records
+  * If the dependent indicator is not in records, it needs to be explicitly configured in aggregationRules, specifying the aggregation rule and indicatorKey to be used in dependIndicatorKeys. */
+  dependIndicatorKeys: string[];
+  /** The calculation function of the calculated field. The dependent indicator value is passed in as a parameter, and the return value is used as the value of the calculated field. */
+  calculateFun?: (dependFieldsValue: any) => any;
+}
+```
+
 ## columnTree(Array)
 
 Column header tree, type: `(IDimensionHeaderNode|IIndicatorHeaderNode)[]`. Among them, IDimensionHeaderNode refers to the dimension value node of non-indicator dimensions, and IIndicatorHeaderNode refers to the indicator name node.

docs/assets/option/zh/table/pivotTable.md

@@ -224,7 +224,7 @@ export interface Total {
 
 ### derivedFieldRules(DerivedFieldRules)
 
-增加派生字段
+增加派生字段，vtable 会基于派生字段定义的规则来生成新的字段，并将新字段加入到数据中。该新的字段可以作为维度项或者指标项。
 
 ```
 export type DerivedFieldRules = DerivedFieldRule[];
@@ -239,6 +239,26 @@ export interface DerivedFieldRule {
 }
 ```
 
+### calculatedFieldRules (CalculateddFieldRules)
+
+计算字段，类 Excel 透视表中的计算字段，可以通过计算字段来计算新的指标值，且都是在汇总结果基础上进行的再计算。注意：不同于派生字段。
+
+```
+export type CalculateddFieldRules = CalculateddFieldRule[];
+```
+
+```
+export interface CalculateddFieldRule {
+  /** 唯一标识，可以当做新指标的key，用于配置在 indicators 中在透视表中展示。 */
+  key: string;
+  /** 计算字段依赖的指标，可以是在 records 中具体对应的指标字段 or 不是数据records 中的字段
+   * 如果依赖的指标不在 records 中，则需要在 aggregationRules 中明确配置，具体指明聚合规则和 indicatorKey 以在 dependIndicatorKeys 所使用。 */
+  dependIndicatorKeys: string[];
+  /** 计算字段的计算函数，依赖的指标值作为参数传入，返回值作为计算字段的值。   */
+  calculateFun?: (dependFieldsValue: any) => any;
+}
+```
+
 ## columnTree(Array)
 
 列表头树，类型为:`(IDimensionHeaderNode|IIndicatorHeaderNode)[]`。其中 IDimensionHeaderNode 指的是维度非指标的维度值节点，IIndicatorHeaderNode 指的是指标名称节点。

packages/vtable/src/ts-types/new-data-set.ts

@@ -180,8 +180,12 @@ export type DerivedFieldRules = DerivedFieldRule[];
 
 //#region 计算字段规则
 export interface CalculateddFieldRule {
+  /** 唯一标识，可以当做新指标的key，用于配置在 indicators 中在透视表中展示。 */
   key: string;
+  /** 计算字段依赖的指标，可以是在 records 中具体对应的指标字段 or 不是数据records 中的字段
+   * 如果依赖的指标不在 records 中，则需要在 aggregationRules 中明确配置，具体指明聚合规则和 indicatorKey 以在 dependIndicatorKeys 所使用。 */
   dependIndicatorKeys: string[];
+  /** 计算字段的计算函数，依赖的指标值作为参数传入，返回值作为计算字段的值。   */
   calculateFun?: (dependFieldsValue: any) => any;
 }