You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by sh...@apache.org on 2021/06/23 06:46:22 UTC
[echarts-doc] branch master updated: optimize doc content
This is an automated email from the ASF dual-hosted git repository.
shenyi pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
The following commit(s) were added to refs/heads/master by this push:
new 5f0fef8 optimize doc content
5f0fef8 is described below
commit 5f0fef878f7d757e417dfb7e038f3785d7680997
Author: pissang <bm...@gmail.com>
AuthorDate: Wed Jun 23 14:46:07 2021 +0800
optimize doc content
---
en/api/echarts-instance.md | 45 ++++++--------------------------------
zh/api/echarts-instance.md | 54 +++++++++++-----------------------------------
2 files changed, 19 insertions(+), 80 deletions(-)
diff --git a/en/api/echarts-instance.md b/en/api/echarts-instance.md
index 93aad60..d0cfdb7 100644
--- a/en/api/echarts-instance.md
+++ b/en/api/echarts-instance.md
@@ -70,56 +70,25 @@ chart.setOption(option, {
Optional; states whether not to prevent triggering events when calling `setOption`; `false` by default, stating trigger events.
- + `transition`: `SetOptionTransitionOptItem | SetOptionTransitionOptItem[]`
-
- Optional; specify how to perform combining/separating transition animation when `setOption` called. Currently only [custom series](option.html#series-custom) supports this feature. The content of the parameter `transition` is as follows.
- ```js
- type SetOptionTransitionOptItem = {
- from?: SetOptionTransitionOptFinder;
- to?: SetOptionTransitionOptFinder;
- dividingMethod?: 'split' | 'duplicate';
- };
- type SetOptionTransitionOptFinder = {
- seriesIndex?: number;
- seriesId?: string | number;
- seriesName?: string | number;
- dimension: string | number; // Dimension name or dimension index.
- };
- ```
- For example:
- ```js
- chart.setOption(option, {
- transition: {
- // It means that dimension 3 of the old series 0 can be mapped to
- // dimension "Population" of the new series 0. The data diff will be
- // made based on the values in the two dimensions.
- from: { seriesIndex: 0, dimension: 3 },
- to: { seriesIndex: 0, dimension: 'Population' },
- dividingMethod: 'split'
- }
- });
- ```
- The property `from` and `to` indicate that which dimension of which old series will be mapped to which dimension of which new series. Having the pair of dimensions provided, the data diff will be performed based on the values in that two dimensions. That is, if some values in `from.dimension` is the same as some values in `to.dimension` (e.g., all of them are `"France"`), their corresponding graphic elements will perform transition animation (morphing) if possible. In this case e [...]
-
**Component Merging Modes**
Within a specific type of components (more accurately, "component main type". e.g., `xAxis`, `series`):
+ If `opts.notMerge` is set as `true`, the old components will be totally removed and the new component will be created by the incoming `option`.
+ If `opts.notMerge` is set as `false` or not specified:
- + If this component main type is included in `opts.replaceMerge`, these components will be merged in mode `REPLACE_MERGE`.
- + Otherwise, these components will be merged in mode `NORMAL_MERGE`.
+ + If this component main type is included in `opts.replaceMerge`, these components will be merged in mode `Replace Merge`.
+ + Otherwise, these components will be merged in mode `Normal Merge`.
-What is `NORMAL_MERGE` and `REPLACE_MERGE`?
+What is `Normal Merge` and `Replace Merge`?
-+ `NORMAL_MERGE`
++ `Normal Merge`
+ Within a specific component main type (e.g., `xAxis`, `series`), each single "component description" (i.e., like `{type: 'xAxis', id: 'xx', name: 'kk', ...}`) in the incoming `option` will be mapped and merged into the existing components one by one if possible. Otherwise create new component on the tail of the list. The detailed rule is as follows:
+ For each single "component description" that has `id` or `name` specified in `option`, firstly find and merge to existing components that has the same `id` or `name` if possible.
+ Then for each remaining single "component description", find and merge to remaining existing components if possible.
+ Create new components for the remaining "component descriptions" at the tail.
+ Features:
+ No existing component will be removed. Only add and update are supported in this mode.
- + The "component index" will never be changed.
+ + The index of component(componentIndex) will never be changed.
+ If no `id` and `name` specified in `option` (this is a common case), components can be simply merged intuitively according to where they appear in `option`.
+ Example:
```js
@@ -154,13 +123,13 @@ What is `NORMAL_MERGE` and `REPLACE_MERGE`?
]
}
```
-+ `REPLACE_MERGE`
++ `Replace Merge`
+ Within a specific component main type (e.g., `xAxis`, `series`), only the existing components that has its `id` declared in the incoming `option` will be kept, other existing components will be removed or replaced with new created component. the detailed rule is as follows:
+ Firstly Find and merge to existing components that has the same `id` in `option` if possible.
+ Remove the remaining unmatched existing components. (In fact, set to `null` in the component list to make sure there is no change of the indices of the components that not be removed).
+ Create new components for the remaining "component descriptions", and put them on the places that have been free or appended to the tail.
+ Features:
- + Enable to remove some of the components, which is not supported in `NORMAL_MERGE`.
+ + Enable to remove some of the components, which is not supported in `Normal Merge`.
+ The indices of the existing components will never be modified. This is to ensure that the existing references by index still works (e.g., `xAxisIndex: 2`).
+ After replace merged, there might be some "hole", that is, there is no component at some index (because the original component is removed). But this is expectable and controllable by users.
+ Example:
diff --git a/zh/api/echarts-instance.md b/zh/api/echarts-instance.md
index 0090519..84cb33b 100644
--- a/zh/api/echarts-instance.md
+++ b/zh/api/echarts-instance.md
@@ -70,55 +70,25 @@ chart.setOption(option, {
可选。阻止调用 `setOption` 时抛出事件，默认为 `false`，即抛出事件。
- + `transition`: `SetOptionTransitionOptItem | SetOptionTransitionOptItem[]`
-
- 可选。指定如何进行“合并”/“分裂”过渡动画。当前只有 [自定义系列（ custom series ）](option.html#series-custom) 支持这种过渡动画。`transition` 参数的内容如下：
- ```js
- type SetOptionTransitionOptItem = {
- from?: SetOptionTransitionOptFinder;
- to?: SetOptionTransitionOptFinder;
- dividingMethod?: 'split' | 'duplicate';
- };
- type SetOptionTransitionOptFinder = {
- seriesIndex?: number;
- seriesId?: string | number;
- seriesName?: string | number;
- dimension: string | number; // Dimension name or dimension index.
- };
- ```
- 例如：
- ```js
- chart.setOption(option, {
- transition: {
- // 这指定了，我们要从旧的系列 0 的维度 3 映射到新的系列 0 的维度 'Population'。
- // 接下来，数据项的映射，会在这两个维度上进行。
- from: { seriesIndex: 0, dimension: 3 },
- to: { seriesIndex: 0, dimension: 'Population' },
- dividingMethod: 'split'
- }
- });
- ```
- `from` 和 `to` 属性指定了：从旧的哪个系列的哪个维度，映射到新的哪个系列的哪个维度。有了这个指定后，新旧数据的数据项，就可以进行匹配。匹配规则是，假如 `from.dimension` 上的某几个数值，和 `to.dimension` 上的某几个数值相同（例如，他们的值都是 `"法国"`），它们对应的图形元素将会进行过渡动画（尤其是形变动画）。在这种场景中，echarts 支持了三种过渡动画：一对一、一对多（one-to-many，即合并 combining）、多对一（many-to-one，即分裂，separating）。`dividingMethod` 属性指定了，“合并”/“分裂”动画的效果是什么样的，是 split （劈开成多份），还是 duplicate （复制成多份）。详情可看这些例子：[custom-combine-separate-morph](${galleryEditorPath}custom-combine-separate-morph&edit=1&reset=1), [custom-story-transition] [...]
-
-
**组件合并模式**
对于一种类型的组件（如：`xAxis`, `series`）：
-+ 如果设置 `opts.notMerge` 为 `true`，那么旧的组件会被完全移除，新的组件会根据 `option` 创建。
-+ 如果设置 `opts.notMerge` 为 `false`，或者没有设置 `opts.notMerge`：
- + 如果在 `opts.replaceMerge` 里指定里本 "component main type" ，这类组件会进行 `REPLACE_MERGE`。
- + 否则，会进行 `NORMAL_MERGE`。
++ 如果设置`opts.notMerge`为`true`，那么旧的组件会被完全移除，新的组件会根据`option`创建。
++ 如果设置`opts.notMerge`为`false`，或者没有设置 `opts.notMerge`：
+ + 如果在`opts.replaceMerge`里指定组件类型，这类组件会进行`替换合并`。
+ + 否则，会进行`普通合并`。
+
+什么是`普通合并`和`替换合并`？
-什么是 `NORMAL_MERGE` 和 `REPLACE_MERGE`？
++ `普通合并`
-+ `NORMAL_MERGE`
+ 对于一种类型的组件（如：`xAxis`, `series`），新来的 `option` 中的每个“组件描述”（如：`{type: 'xAxis', id: 'xx', name: 'kk', ...}`）会被尽量合并到已存在的组件中。剩余的情况，会在组件列表尾部创建新的组件。整体规则细节如下：
+ 先依次对 `option` 中每个有声明 `id` 或者 `name` 的“组件描述”，寻找能匹配其 `id` 或者 `name` 的已有的组件，找到的话则合并。
+ 再依次对 `option` 中剩余的“组件描述”，寻找还未执行过前一条的已有组件，找到的话则合并。
+ 其他 `option` 中剩余的“组件描述”，用于在组件列表尾部创建新组件。
+ 特点：
+ 永远不会删除已存在的组件。也就是说，只支持增加，或者更新组件。
- + "component index" 永远不会改变。
+ + 组件的索引（componentIndex）永远不会改变。
+ 如果 `id` 和 `name` 没有在 `option` 中被指定（这是经常出现的情况），组件会按照它在 `option` 中的顺序一一合并到已有组件中。这种设定比较符合直觉。
+ 例子：
```js
@@ -154,14 +124,14 @@ chart.setOption(option, {
]
}
```
-+ `REPLACE_MERGE`
++ `替换合并`
+ 对于一种类型的组件（如：`xAxis`, `series`），只有 `option` 中指定了 `id` 并且已有组件中有此 `id` 时，已有组件会和 `option` 相应组件描述进行合并。否则，已有组件都会删除，新组件会被根据 `option` 创建。细节规则如下：
+ 先依次对 `option` 中每个有声明 `id` 的“组件描述”，寻找能匹配其 `id` 或者 `name` 的已有的组件，找到的话则合并。
- + 删除其他没匹配到的已有组件。（实际上是，在组件列表中设置为 `null`，以保证没有被删除的组件的 "component index" 不改变）。
+ + 删除其他没匹配到的已有组件。
+ 依次对 `option` 中剩余的“组件描述”，创建新组件，填入刚因删除而空出来的位置上，或者增加到末尾。
+ 特点：
- + 与 `NORMAL_MERGE` 相比，支持了组件删除。
- + 已有组件的 "component index" 永远不会变。这是为了保证，`option` 或者 API 中的 index 引用（例如：`xAxisIndex: 2`）仍能正常一致得使用。
+ + 与 `普通合并` 相比，支持了组件删除。
+ + 已有组件的索引永远不会变。这是为了保证，`option` 或者 API 中的 index 引用（例如：`xAxisIndex: 2`）仍能正常一致得使用。
+ 整个处理过程结束后，可能存在一些“洞”，也就是说，在组件列表中的某些 index 上，并没有组件存在（被删除了）。但是这是可以被开发者预期和控制的。
+ 例子：
```js
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org