diff --git a/en/option/partial/encode-dimensions.md b/en/option/partial/encode-dimensions.md index 356b0440..86d02f6f 100644 --- a/en/option/partial/encode-dimensions.md +++ b/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: diff --git a/en/option/partial/group-id.md b/en/option/partial/group-id.md index 850ab7b6..21d6519e 100644 --- a/en/option/partial/group-id.md +++ b/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`, Apache ECharts will try to use `series.dataGroupId` as the group ID for the data item. If `series.dataGroupId` is not specified either, Apache 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 "parent-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 "parent-child-grandChild" is formed in the 3 options. In this way, after `setOption` is called, Apache ECharts will try to find the "parent-child" or "child-parent" 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. diff --git a/en/option/partial/universal-transition.md b/en/option/partial/universal-transition.md index ffece5e8..eea47674 100644 --- a/en/option/partial/universal-transition.md +++ b/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. diff --git a/en/option/series/bar.md b/en/option/series/bar.md index 338eb1bf..6b663dc0 100644 --- a/en/option/series/bar.md +++ b/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, diff --git a/en/option/series/boxplot.md b/en/option/series/boxplot.md index 8de4552a..66442f2b 100644 --- a/en/option/series/boxplot.md +++ b/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. diff --git a/en/option/series/candlestick.md b/en/option/series/candlestick.md index 934882e8..2c7dfe1f 100644 --- a/en/option/series/candlestick.md +++ b/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. diff --git a/en/option/series/custom.md b/en/option/series/custom.md index 3815a6b6..a98d51c2 100644 --- a/en/option/series/custom.md +++ b/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( diff --git a/en/option/series/heatmap.md b/en/option/series/heatmap.md index 010ef1c1..3840b495 100644 --- a/en/option/series/heatmap.md +++ b/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. diff --git a/en/option/series/line.md b/en/option/series/line.md index 527d33c4..70f33f0b 100644 --- a/en/option/series/line.md +++ b/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' ) }} + diff --git a/en/option/series/lines.md b/en/option/series/lines.md index d4bf90ca..99a45ed8 100644 --- a/en/option/series/lines.md +++ b/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). diff --git a/en/option/series/map.md b/en/option/series/map.md index fb3d335f..0f41f84d 100644 --- a/en/option/series/map.md +++ b/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. diff --git a/en/option/series/pictorialBar.md b/en/option/series/pictorialBar.md index 85cbcd5f..6f27928b 100644 --- a/en/option/series/pictorialBar.md +++ b/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 diff --git a/en/option/series/pie.md b/en/option/series/pie.md index d90c10ca..717740e9 100644 --- a/en/option/series/pie.md +++ b/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. diff --git a/en/option/series/radar.md b/en/option/series/radar.md index 5ccc7d45..eb2d3417 100644 --- a/en/option/series/radar.md +++ b/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, diff --git a/en/option/series/scatter.md b/en/option/series/scatter.md index 9061d8eb..70202181 100644 --- a/en/option/series/scatter.md +++ b/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" diff --git a/zh/option/partial/encode-dimensions.md b/zh/option/partial/encode-dimensions.md index 312e87e4..f7cdb0ed 100644 --- a/zh/option/partial/encode-dimensions.md +++ b/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)特有的属性: diff --git a/zh/option/partial/group-id.md b/zh/option/partial/group-id.md index 59393a85..bb10a2b4 100644 --- a/zh/option/partial/group-id.md +++ b/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`时,Apache ECharts 会尝试寻找前后`option`数据项间的父子关系,若存在父子关系,则会对相关数据项进行下钻或聚合动画的过渡。 + +没有对应子数据组的数据项不需要指定`childGroupId`。 +如果你使用了[dataset](~dataset)组件来表达数据,推荐使用`encode.itemChildGroupId`来指定哪个维度被编码为子数据组 ID。 diff --git a/zh/option/partial/universal-transition.md b/zh/option/partial/universal-transition.md index 58699a92..e8db608c 100644 --- a/zh/option/partial/universal-transition.md +++ b/zh/option/partial/universal-transition.md @@ -11,7 +11,7 @@ 全局过渡动画(Universal Transition)提供了任意系列之间进行变形动画的功能。开启该功能后,每次`setOption`,相同`id`的系列之间会自动关联进行动画的过渡,更细粒度的关联配置见`universalTransition.seriesKey`配置。 -通过配置`encode.itemGroupId`或者`dataGroupId`等指定数据的分组,还可以实现诸如下钻,聚合等一对多或者多对一的动画。 +通过配置数据项的`groupId`和`childGroupId`,还可以实现诸如下钻,聚合等一对多或者多对一的动画。 可以直接在系列中配置 `universalTransition: true` 开启该功能。也可以提供一个对象进行更多属性的配置。 diff --git a/zh/option/series/bar.md b/zh/option/series/bar.md index d850e2a9..c4e7b1b9 100644 --- a/zh/option/series/bar.md +++ b/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, diff --git a/zh/option/series/boxplot.md b/zh/option/series/boxplot.md index a79941dc..481cb8bc 100644 --- a/zh/option/series/boxplot.md +++ b/zh/option/series/boxplot.md @@ -227,6 +227,10 @@ ECharts 并不内置对原始数据的处理,输入给 `boxplot` 的数据须 prefix = '##' ) }} +{{ use: partial-data-child-group-id( + prefix = '##' +) }} + ### itemStyle(Object) 盒须图单个数据样式。 diff --git a/zh/option/series/candlestick.md b/zh/option/series/candlestick.md index b08c1e0e..7f2b8b21 100644 --- a/zh/option/series/candlestick.md +++ b/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 线图数据的图形样式。 diff --git a/zh/option/series/custom.md b/zh/option/series/custom.md index d9d48804..e4390f3f 100644 --- a/zh/option/series/custom.md +++ b/zh/option/series/custom.md @@ -431,6 +431,10 @@ renderItem 函数的第二个参数。 prefix = '##' ) }} +{{ use: partial-data-child-group-id( + prefix = '##' +) }} + ### itemStyle(Object) {{ use: partial-item-style( diff --git a/zh/option/series/heatmap.md b/zh/option/series/heatmap.md index ea944602..29fe9443 100644 --- a/zh/option/series/heatmap.md +++ b/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')上有效。 diff --git a/zh/option/series/line.md b/zh/option/series/line.md index c446b08b..8519e05a 100644 --- a/zh/option/series/line.md +++ b/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, diff --git a/zh/option/series/lines.md b/zh/option/series/lines.md index 39f45531..cff7c81b 100644 --- a/zh/option/series/lines.md +++ b/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` 时支持多于两个的坐标。 diff --git a/zh/option/series/map.md b/zh/option/series/map.md index 02ef3ce6..bb9d9ab9 100644 --- a/zh/option/series/map.md +++ b/zh/option/series/map.md @@ -101,6 +101,10 @@ center: [115.97, '30%'] prefix = '##' ) }} +{{ use: partial-data-child-group-id( + prefix = '##' +) }} + ### selected(boolean) = false 该区域是否选中。 diff --git a/zh/option/series/pictorialBar.md b/zh/option/series/pictorialBar.md index bfd1477d..7f8a622f 100644 --- a/zh/option/series/pictorialBar.md +++ b/zh/option/series/pictorialBar.md @@ -244,6 +244,10 @@ option = { prefix = '##' ) }} +{{ use: partial-data-child-group-id( + prefix = '##' +) }} + {{ use: pictorialBar-symbol-attrs( prefix = "##", useZ2 = true diff --git a/zh/option/series/pie.md b/zh/option/series/pie.md index 794f6203..d3c07ad3 100644 --- a/zh/option/series/pie.md +++ b/zh/option/series/pie.md @@ -357,6 +357,10 @@ const option = { prefix = '##' ) }} +{{ use: partial-data-child-group-id( + prefix = '##' +) }} + ### selected(boolean) = false 该数据项是否被选中。 diff --git a/zh/option/series/radar.md b/zh/option/series/radar.md index f2431fd9..79b87f0d 100644 --- a/zh/option/series/radar.md +++ b/zh/option/series/radar.md @@ -199,6 +199,10 @@ data : [ prefix = '##' ) }} +{{ use: partial-data-child-group-id( + prefix = '##' +) }} + {{ use: partial-symbol( defaultSymbol = "'circle'", defaultSymbolSize = 4, diff --git a/zh/option/series/scatter.md b/zh/option/series/scatter.md index 757f6c0b..029a61cb 100644 --- a/zh/option/series/scatter.md +++ b/zh/option/series/scatter.md @@ -244,6 +244,10 @@ const option = { prefix = '##' ) }} +{{ use: partial-data-child-group-id( + prefix = '##' +) }} + {{ use: partial-symbol( prefix = "##", name = "单个数据"