docs: update documents for multiple level drilldown - childGroupId

en/option/partial/encode-dimensions.md

@@ -60,9 +60,13 @@ encode: {
     // Using dimensions[3] as the name of each data item. This is useful in charts like
     // 'pie', 'funnel', where data item name can be displayed in legend.
     itemName: 3,
-    // Using dimensions[4] as the groupId of each data item. groupId will be used to categorize the data. And to determine
-    // How the merge and split animation are performed in the universal transition. See universalTransition option for detail.
-    itemGroupId: 4
+    // Using dimensions[4] as the group ID for each data item. With universalTransition enabled,
+    // the data items from the old option and those from the new one, if sharing a same group ID,
+    // will then be matched and applied to a proper animation after `setOption` is called.
+    itemGroupId: 4,
+    // Using dimension[5] as the child group ID for each data item. This option is introduced to
+    // make multiple levels drilldown and aggregation animation come true. See childGroupId for more.
+    itemChildGroupId: 5
 }
 
 // These properties only work in cartesian(grid) coordinate system:

en/option/partial/group-id.md

@@ -3,15 +3,59 @@
 
 ## dataGroupId(string)
 
-A groupID common to all data in the series. the groupID will be used to classify the data and determine how merge and split animations are performed in the universal transition animation.
-
-If you are using the [dataset](~dataset) component to represent the data, it is recommended to use `encode.itemGroupID` to specify which dimension is encoded as the groupID.
+A group ID assigned to all data items in the series.
 
+This option has a lower priority than `groupId`, which means when `groupId` is specified for a certain data item the `dataGroupId` will be simply ignored for that data item. For more information, please see `series.data.groupId`.
 
 
 {{ target: partial-data-group-id }}
 
 #${prefix} groupId(string)
 
-The groupID of this data item. groupID will be used to classify the data.
+The group ID of a data item. When `universalTransition` is enabled, the data items from the old option and those from the new one, if sharing a same group ID, will then be matched and applied to a proper animation after `setOption` is called.
+
+If a data item is not specified with a `groupId`, Echarts will try to use `series.dataGroupId` as the group ID for the data item. If `series.dataGroupId` is not specified either, Echarts will fall back to using the data item's ID as its group ID.
+
+If you are using the [dataset](~dataset) component to represent data, you are recommended to use `encode.itemGroupId` to specify the dimension that is to be encoded as the group ID.
+
+
+{{ target: partial-data-child-group-id }}
+
+#${prefix} childGroupId(string)
+
+The group ID of the child data of a data item. This option is introduced to make multiple levels drilldown and aggregation animation possilbe.
+
+~[700x300](${galleryViewPath}doc-example/bar-drilldown&edit=1&reset=1)
+
+Before `childGroupId` is introduced, developers actually can use `groupId` to make drilldown and aggregation animation already, but with the limit on the times that a continious drilldown or aggregation can happen, which is only one time.
+
+`childGroupId`, together with `groupId`, help to form "father-child" relationships between data items of different options, such as:
+
+```text
+data: [                        data: [                        data: [
+  {                              {                              {
+    name: 'Animals',               name: 'Dogs',                  name: 'Corgi',
+    value: 3,                      value: 3,                      value: 5,
+    groupId: 'things',             groupId: 'animals',            groupId: 'dogs'
+    childGroupId: 'animals'        childGroupId: 'dogs'         },
+  },                             },                             {
+  {                              {                                name: 'Bulldog',
+    name: 'Fruits',                name: 'Cats',                  value: 6,
+    value: 3,                      value: 4,                      groupId: 'dogs'
+    groupId: 'things',             groupId: 'animals',          },
+    childGroupId: 'fruits'         childGroupId: 'cats',        {
+  },                             },                               name: 'Shiba Inu',
+  {                              {                                value: 7,
+    name: 'Cars',                  name: 'Birds',                 groupId: 'dogs'
+    value: 2,                      value: 3,                    }
+    groupId: 'things',             groupId: 'animals',        ]
+    childGroupId: 'cars'           childGroupId: 'birds'
+  }                              }
+]                              ]
+```
+
+The 3 groups of data above come from 3 options, and by specifying `groupId` and `childGroupId` for the data items a relationship of "father-child-grandChild" is formed in the 3 options. In this way,  after `setOption` is called, Echarts will try to find the "father-child" or "child-father" relationship of the old option and the new one. If the relationship exists, the matching data items will be applied to a drilldown animation or an aggregation one.
+
+If a data item has no child data then there is no need to specify a `childGroupId` at all.
 
+If you are using the [dataset](~dataset) component to represent data, you are recommended to use `encode.itemChildGroupId` to specify the dimension that is to be encoded as the child group ID.

en/option/partial/universal-transition.md

@@ -11,7 +11,7 @@ Configuration related to universal transition animation.
 
 Universal Transition provides the ability to morph between any series. With this feature enabled, each time `setOption`, transitions between series with the same `id` will be automatically associated with each other.
 
-One-to-many or many-to-one animations such as drill-down, aggregation, etc. can also be achieved by specifying groups of data such as `encode.itemGroupId` or `dataGroupId`.
+One-to-many or many-to-one animations such as drill-down, aggregation, etc. can also be achieved by specifying data items' `groupId` and `childGroupId`.
 
 This can be enabled directly by configuring `universalTransition: true` in the series. It is also possible to provide an object for more detailed configuration.
 

en/option/series/bar.md

@@ -216,6 +216,10 @@ The value of a single data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: partial-bar-state(
     prefix = "##",
     topLevel = false,

en/option/series/boxplot.md

@@ -191,6 +191,10 @@ Value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 Style of a single data.

en/option/series/candlestick.md

@@ -209,6 +209,10 @@ Value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 Style of a candle box.

en/option/series/custom.md

@@ -444,6 +444,10 @@ Value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 {{ use: partial-item-style(

en/option/series/heatmap.md

@@ -154,6 +154,10 @@ Value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### label(Object)
 
 It is valid with [coordinateSystem](~series-heatmap.coordinateSystem) of 'cartesian2d' value.

en/option/series/line.md

@@ -338,6 +338,10 @@ The value of a single data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: partial-symbol(
     defaultSymbol = "'circle'",
     defaultSymbolSize = 4,
@@ -491,3 +495,4 @@ Select state of specified single data.
     prefix = "####",
     hasInherit = ${state} === 'emphasis'
 ) }}
+

en/option/series/lines.md

@@ -200,6 +200,10 @@ the name of data.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### coords(Array)
 
 An array includes two ore more than two coordinates. Each coordinate could be `[x, y]` in [rectangular coordinate](~grid) and `[lng, lat]` in [geographic coordinate](~geo).

en/option/series/map.md

@@ -104,6 +104,10 @@ The numerical value of this area.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### selected(boolean) = false
 
 Whether the are selected.

en/option/series/pictorialBar.md

@@ -195,6 +195,10 @@ The value of a single data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: pictorialBar-symbol-attrs(
     prefix = "##",
     useZ2 = true

en/option/series/pie.md

@@ -334,6 +334,10 @@ Data value.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### selected(boolean) = false
 
 Whether the data item is selected.

en/option/series/radar.md

@@ -163,6 +163,10 @@ Numerical value of a single data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: partial-symbol(
     defaultSymbol = "'circle'",
     defaultSymbolSize = 4,

en/option/series/scatter.md

@@ -175,6 +175,10 @@ the value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: partial-symbol(
     prefix = "##",
     name = "single data"

zh/option/partial/encode-dimensions.md

@@ -55,8 +55,10 @@ encode: {
     itemId: 2,
     // 指定数据项的名称使用第三个维度在饼图等图表中有用，可以使这个名字显示在图例（legend）中。
     itemName: 3,
-    // 指定数据项的组 ID (groupID)，组 ID 会被用于分类数据，并在全局过渡动画中决定如何进行合并和分裂动画，具体见 universalTransition
-    itemGroupId: 4
+    // 指定数据项的组 ID (groupId)。当全局过渡动画功能开启时，setOption 前后拥有相同 groupId 的数据项会进行动画过渡。
+    itemGroupId: 4,
+    // 指定数据项对应的子数据组 ID (childGroupId)，用于实现多层下钻和聚合。详见 childGroupId。
+    itemChildGroupId: 5
 }
 
 // 直角坐标系（grid/cartesian）特有的属性：

zh/option/partial/group-id.md

@@ -3,15 +3,57 @@
 
 ## dataGroupId(string)
 
-该系列所有数据共有的组 ID。组 ID 会被用于分类数据，并在全局过渡动画中决定如何进行合并和分裂动画。
-
-如果你使用了[dataset](~dataset)组件来表达数据，推荐使用`encode.itemGroupID`来指定哪个维度被编码为组 ID。
-
+该系列所有数据项的组 ID，优先级低于`groupId`。详见`series.data.groupId`。
 
 
 {{ target: partial-data-group-id }}
 
 #${prefix} groupId(string)
 
-该数据项的组 ID。组 ID 会被用于分类数据，并在全局过渡动画中决定如何进行合并和分裂动画。
+该数据项的组 ID。当全局过渡动画功能开启时，`setOption` 前后拥有相同组 ID 的数据项会进行动画过渡。
+
+若没有指定`groupId` ，会尝试用`series.dataGroupId`作为该数据项的组 ID；若`series.dataGroupId`也没有指定，则会使用数据项的 ID 作为组 ID。
+
+如果你使用了[dataset](~dataset)组件来表达数据，推荐使用`encode.itemGroupId`来指定哪个维度被编码为组 ID。
+
+
+{{ target: partial-data-child-group-id }}
+
+#${prefix} childGroupId(string)
+
+该数据项对应的子数据组 ID，用于实现多层下钻和聚合。
+
+~[700x300](${galleryViewPath}doc-example/bar-drilldown&edit=1&reset=1)
+
+通过`groupId`已经可以达到数据下钻和聚合的效果，但只支持一层的下钻和聚合。为了实现多层下钻和聚合，我们又引入了`childGroupId`。
+
+引入`childGroupId`后，不同`option`的数据项之间就能形成逻辑上的父子关系，例如：
+
+```text
+data: [                        data: [                        data: [
+  {                              {                              {
+    name: 'Animals',               name: 'Dogs',                  name: 'Corgi',
+    value: 3,                      value: 3,                      value: 5,
+    groupId: 'things',             groupId: 'animals',            groupId: 'dogs'
+    childGroupId: 'animals'        childGroupId: 'dogs'         },
+  },                             },                             {
+  {                              {                                name: 'Bulldog',
+    name: 'Fruits',                name: 'Cats',                  value: 6,
+    value: 3,                      value: 4,                      groupId: 'dogs'
+    groupId: 'things',             groupId: 'animals',          },
+    childGroupId: 'fruits'         childGroupId: 'cats',        {
+  },                             },                               name: 'Shiba Inu',
+  {                              {                                value: 7,
+    name: 'Cars',                  name: 'Birds',                 groupId: 'dogs'
+    value: 2,                      value: 3,                    }
+    groupId: 'things',             groupId: 'animals',        ]
+    childGroupId: 'cars'           childGroupId: 'birds'
+  }                              }
+]                              ]
+```
+
+上面 3 组 data 分别来自 3 个 option ，通过`groupId`和`childGroupId`，它们之间存在了“父-子-孙”的关系。在`setOption`时，Echarts 会尝试寻找前后`option`数据项间的父子关系，若存在父子关系，则会对相关数据项进行下钻或聚合动画的过渡。
+
+没有对应子数据组的数据项不需要指定`childGroupId`。
 
+如果你使用了[dataset](~dataset)组件来表达数据，推荐使用`encode.itemChildGroupId`来指定哪个维度被编码为子数据组 ID。

zh/option/partial/universal-transition.md

@@ -11,7 +11,7 @@
 
 全局过渡动画（Universal Transition）提供了任意系列之间进行变形动画的功能。开启该功能后，每次`setOption`，相同`id`的系列之间会自动关联进行动画的过渡，更细粒度的关联配置见`universalTransition.seriesKey`配置。
 
-通过配置`encode.itemGroupId`或者`dataGroupId`等指定数据的分组，还可以实现诸如下钻，聚合等一对多或者多对一的动画。
+通过配置数据项的`groupId`和`childGroupId`，还可以实现诸如下钻，聚合等一对多或者多对一的动画。
 
 可以直接在系列中配置 `universalTransition: true` 开启该功能。也可以提供一个对象进行更多属性的配置。
 

zh/option/series/bar.md

@@ -292,6 +292,10 @@ option = {
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: partial-bar-state(
     prefix = "##",
     topLevel = false,

zh/option/series/boxplot.md

@@ -227,6 +227,10 @@ ECharts 并不内置对原始数据的处理，输入给 `boxplot` 的数据须
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 盒须图单个数据样式。

zh/option/series/candlestick.md

@@ -396,6 +396,10 @@ K 线图的选中状态。开启 [selectedMode](~series-candlestick.selectedMode
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 单个 K 线图数据的图形样式。

zh/option/series/custom.md

@@ -431,6 +431,10 @@ renderItem 函数的第二个参数。
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 {{ use: partial-item-style(

zh/option/series/heatmap.md

@@ -205,6 +205,10 @@ option = {
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### label(Object)
 
 在直角坐标系([coordinateSystem](~series-heatmap.coordinateSystem): 'cartesian2d')上有效。

zh/option/series/line.md

@@ -367,6 +367,10 @@ const option = {
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: partial-symbol(
     defaultSymbol = "'circle'",
     defaultSymbolSize = 4,

zh/option/series/lines.md

@@ -224,6 +224,10 @@ ECharts 2.x 里会用地图上的 `markLine` 去绘制迁徙效果，在 ECharts
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### coords(Array)
 
 一个包含两个到多个二维坐标的数组。在 [polyline](~series-lines.polyline) 设置为 `true` 时支持多于两个的坐标。

zh/option/series/map.md

@@ -101,6 +101,10 @@ center: [115.97, '30%']
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### selected(boolean) = false
 
 该区域是否选中。