You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by su...@apache.org on 2020/12/22 09:43:21 UTC
[incubator-echarts-doc] 01/02: doc: fix the doc for timeline.
This is an automated email from the ASF dual-hosted git repository.
sushuang pushed a commit to branch next
in repository https://gitbox.apache.org/repos/asf/incubator-echarts-doc.git
commit e0960acc80d054ca8d8dfebcfbaba951af0643df
Author: 100pah <su...@gmail.com>
AuthorDate: Tue Dec 22 16:29:12 2020 +0800
doc: fix the doc for timeline.
---
en/option/component/timeline.md | 182 +++++++++++++++++++++++-----------------
en/option/option.md | 5 ++
zh/option/component/timeline.md | 177 ++++++++++++++++++++++----------------
zh/option/option.md | 6 ++
4 files changed, 219 insertions(+), 151 deletions(-)
diff --git a/en/option/component/timeline.md b/en/option/component/timeline.md
index 6608542..7914a1b 100644
--- a/en/option/component/timeline.md
+++ b/en/option/component/timeline.md
@@ -9,95 +9,99 @@ Here is an example:
~[600x400](${galleryViewPath}doc-example/mix-timeline-all&edit=1&reset=1)
-Different from other components, `timeline` component requires multiple options. If the traditional way of ECharts option is called *atomic option*, then, the option used along with timeline should be call a *compound option* composed with multiple atomic options. For example:
+Different from other cases, `timeline` component requires multiple options. We call first the parameter of `setOption` as `ECOption`, and call the traditional single ECharts option as `ECUnitOption`.
+
++ In the case that `timeline` and `media query` are not set, an `ECUnitOption` is an `ECOption`.
++ In the case that `timeline` or `media query` are set, an `ECOption` is made up with several `ECUnitOption`s.
+ + The properties at the root of `ECOption` form an `ECUnitOption`, which is also called `baseOption`, representing the default settings.
+ + Each item of the array `options` form an `ECUnitOption`, which can be also called `switchableOption`, representing options for each time tick.
++ `baseOption` and one `switchableOption` are used to calculate the `finalOption`, based on which the chart will be final rendered.
+
+For example:
```javascript
-// In the following example, baseOption is an *atomic option*, so as each item in options array.
-// Each of the atomic option follows configuration introduced in this document.
-myChart.setOption(
- {
- baseOption: {
- timeline: {
- ...,
- data: ['2002-01-01', '2003-01-01', '2004-01-01']
- },
- title: {
- subtext: ' Data is from National Bureau of Statistics '
- },
- grid: {...},
- xAxis: [...],
- yAxis: [...],
- series: [
- { // other configurations of series 1
- type: 'bar',
- ...
- },
- { // other configurations of series 2
- type: 'line',
- ...
- },
- { // other configurations of series 3
- type: 'pie',
- ...
- }
- ]
+myChart.setOption({
+ // This is the properties of `baseOption`.
+ timeline: {
+ ...,
+ // each item in `timeline.data` corresponds to each
+ // `option` in `options` array.
+ data: ['2002-01-01', '2003-01-01', '2004-01-01']
+ },
+ title: {
+ subtext: ' Data is from National Bureau of Statistics '
+ },
+ grid: { ... },
+ xAxis: [ ... ],
+ yAxis: [ ... ],
+ series: [{
+ // other configurations of series 1
+ type: 'bar',
+ ...
+ }, {
+ // other configurations of series 2
+ type: 'line',
+ ...
+ }, {
+ // other configurations of series 3
+ type: 'pie',
+ ...
+ }],
+ // `switchableOption`s:
+ options: [{
+ // it is an option corresponding to '2002-01-01'
+ title: {
+ text: 'the statistics of the year 2002'
},
- options: [
- { // it is an option corresponding to '2002-01-01'
- title: {
- text: 'the statistics of the year 2002'
- },
- series: [
- {data: []}, // the data of series 1
- {data: []}, // the data of series 2
- {data: []} // the data of series 3
- ]
- },
- { // it is an option corresponding to '2003-01-01'
- title: {
- text: 'the statistics of the year 2003'
- },
- series: [
- {data: []},
- {data: []},
- {data: []}
- ]
- },
- { // it is an option corresponding to '2004-01-01'
- title: {
- text: 'the statistics of the year 2004'
- },
- series: [
- {data: []},
- {data: []},
- {data: []}
- ]
- }
+ series: [
+ { data: [] }, // the data of series 1
+ { data: [] }, // the data of series 2
+ { data: [] } // the data of series 3
+ ]
+ }, {
+ // it is an option corresponding to '2003-01-01'
+ title: {
+ text: 'the statistics of the year 2003'
+ },
+ series: [
+ { data: [] },
+ { data: [] },
+ { data: [] }
]
- }
-);
+ }, {
+ // it is an option corresponding to '2004-01-01'
+ title: {
+ text: 'the statistics of the year 2004'
+ },
+ series: [
+ { data: [] },
+ { data: [] },
+ { data: [] }
+ ]
+ }]
+});
```
-In the above example, each item in `timeline.data` corresponds to each `option` of `options` array.
-
<br>
-**Attention and Best Practice: **
-
-+ Shared configuration items are recommended to be set in `baseOption`. When switching in `timeline`, `option` in corresponding `options` array will be merged with `baseOption` to form the final `option`.
-
-+ In `options` array, if an attribute is configured in one of the options, then, it should also be configured in other options. Otherwise, this attribute will be ignored.
-
-+ `options` in *compound option* doesn't support merge.
-
- That is to say, when calling `chart.setOption(rawOption)` after the first time, if `rawOption` is a *compound option* (meaning that it contains an array of `options`), then the new `rawOption.options` will replace the old one, instead of merging with it. Of course, `rawOption.baseOption` will be merged with that of old option normally.
+**How the `finalOption` calculated?**
+{{ use: partial-timeline-merge-strategy }}
<br>
-**Compatibility with ECharts 2: **
-
-+ ECharts3 doesn't support `timeline.notMerge` parameter any more, which implies *notMerge mode* is no longer supported. If you need this function, you may manage the option in your own program before passing to `setOption(option, true)`.
+**Compatibility with ECharts 4:**
+
+We also support these equivalent setting styles:
+```js
+option = {
+ baseOption: {
+ timeline: {},
+ series: [],
+ // ... other properties of baseOption.
+ },
+ options: []
+};
+```
-+ Comparing ECharts 3 with ECharts 2, the definition location of timeline attributes are different. The one in ECharts 3 is moved to `baseOption` and is regarded as a seperate component, which is also compatible with the timeline definition location of ECharts 2. But it is not recommended to do so.
## show(boolean) = true
@@ -156,6 +160,19 @@ Indicates play speed (gap time between two state), whose unit is millisecond.
Whether the view updates in real time during dragging the control dot.
+## replaceMerge(Array|string) = undefined
+
+{{ use: partial-timeline-merge-strategy }}
+
+<br>
+
+The value of `replaceMerge` can be a `mainType` of a component, like `replaceMerge: 'xAxis'`, or an array of `mainType`s, like `replaceMerge: ['xAxis', 'series']`.
+
+`replaceMerge` is usually used in this scenario: if users intending to replace all of the current series with the new series corresponding to the next time tick without any merging, users can set: `replaceMerge: 'series'`, and make sure that the series are in different id or no id.
+
+See this [example](${galleryEditorPath}doc-example/timeline-dynamic-series&edit=1&reset=1).
+
+
## controlPosition(string) = 'left'
<ExampleUIControlEnum options="left,right" />
@@ -519,3 +536,12 @@ Rotation angle of `label`, in which positive values refer to counter clockwise r
) }}
{{ /if }}
+
+
+{{ target: partial-timeline-merge-strategy }}
+
+When initializing, a `switchableOption` corresponding to the current time tick are merged into `baseOption` to form the `finalOption`. Each time the current tick changed, the new `switchableOption` corresponding to the new time tick are merged into the `finalOption`.
+
+There are two merging strategy.
++ By default, use `NORMAL_MERGE`.
++ If [timeline.replaceMerge](~option.html#timeline.replaceMerge) is set, use `REPLACE_MERGE`. See [setOption](~api.html#echartsInstance.setOption) for more details of `REPLACE_MERGE`.
diff --git a/en/option/option.md b/en/option/option.md
index 0b08908..03c946f 100644
--- a/en/option/option.md
+++ b/en/option/option.md
@@ -106,3 +106,8 @@ The default value of `useUTC` is false, for sake of considering:
Notice: the setting only affects "display time", not "parse time".
For how time value (like `1491339540396`, `'2013-01-04'`, ...) is parsed in echarts, see [the time part in date](~series-line.data).
+
+
+# options(Array) = undefined
+
+Option array used in [timeline](option.html#timeline) or [media query](option.html#media). Each item of this array is an echarts option (`ECUnitOption`).
diff --git a/zh/option/component/timeline.md b/zh/option/component/timeline.md
index 1a65914..81c56bd 100644
--- a/zh/option/component/timeline.md
+++ b/zh/option/component/timeline.md
@@ -9,93 +9,100 @@
~[600x400](${galleryViewPath}doc-example/mix-timeline-all&edit=1&reset=1)
-`timeline` 和其他组件有些不同，它需要操作『多个option』。
-假设，我们把 ECharts 的传统的 option 称为*原子option*，那么使用 `timeline` 时，传入 ECharts 的 option 就成为了一个集合多个原子option的*复合option*。如下示例：
+`timeline` 和其他场景有些不同，它需要操作『多个option』。我们把传入 `setOption` 第一个参数的东西，称为 `ECOption`，然后称传统的 ECharts 单个 option 为 `ECUnitOption`。
+
++ 当 `timeline` 和 `media query` 没有被设置时，一个 `ECUnitOption` 就是一个 `ECOption`。
++ 当 `timeline` 或 `media query` 被使用设置时，一个 `ECOption` 由几个 `ECUnitOption` 组成。
+ + `ECOption` 的各个根属性，形成一个 `ECUnitOption`，叫做 `baseOption`，它代表了各种默认设置。
+ + `options` 数组每项，形成一个 `ECUnitOption`，我们为了方便也叫做 `switchableOption`，它代表了每个时间粒度对应的 option。
++ `baseOption` 和一个 `switchableOption` 会用来计算最终的 `finalOption`，图表就是根据这个最终结果绘制的。
+
+例如：
```javascript
-// 如下，baseOption 是一个 『原子option』，options 数组中的每一项也是一个 『原子option』。
+// 如下，baseOption 是一个 『原子option』，options 数组
+// 中的每一项也是一个 『原子option』。
// 每个『原子option』中就是本文档中描述的各种配置项。
-myChart.setOption(
- {
- baseOption: {
- timeline: {
- ...,
- data: ['2002-01-01', '2003-01-01', '2004-01-01']
- },
- grid: {...},
- xAxis: [...],
- yAxis: [...],
- series: [
- { // 系列一的一些其他配置
- type: 'bar',
- ...
- },
- { // 系列二的一些其他配置
- type: 'line',
- ...
- },
- { // 系列三的一些其他配置
- type: 'pie',
- ...
- }
- ]
+myChart.setOption({
+ // `baseOption` 的属性.
+ timeline: {
+ ...,
+ // `timeline.data` 中的每一项，对应于 `options`
+ // 数组中的每个 `option`
+ data: ['2002-01-01', '2003-01-01', '2004-01-01']
+ },
+ grid: { ... },
+ xAxis: [ ... ],
+ yAxis: [ ... ],
+ series: [{
+ // 系列一的一些其他配置
+ type: 'bar',
+ ...
+ }, {
+ // 系列二的一些其他配置
+ type: 'line',
+ ...
+ }, {
+ // 系列三的一些其他配置
+ type: 'pie',
+ ...
+ }],
+ // `switchableOption`s:
+ options: [{
+ // 这是'2002-01-01' 对应的 option
+ title: {
+ text: '2002年统计值'
},
- options: [
- { // 这是'2002-01-01' 对应的 option
- title: {
- text: '2002年统计值'
- },
- series: [
- {data: []}, // 系列一的数据
- {data: []}, // 系列二的数据
- {data: []} // 系列三的数据
- ]
- },
- { // 这是'2003-01-01' 对应的 option
- title: {
- text: '2003年统计值'
- },
- series: [
- {data: []},
- {data: []},
- {data: []}
- ]
- },
- { // 这是'2004-01-01' 对应的 option
- title: {
- text: '2004年统计值'
- },
- series: [
- {data: []},
- {data: []},
- {data: []}
- ]
- }
+ series: [
+ { data: [] }, // 系列一的数据
+ { data: [] }, // 系列二的数据
+ { data: [] } // 系列三的数据
]
- }
-);
+ }, {
+ // 这是'2003-01-01' 对应的 option
+ title: {
+ text: '2003年统计值'
+ },
+ series: [
+ { data: [] },
+ { data: [] },
+ { data: [] }
+ ]
+ }, {
+ // 这是'2004-01-01' 对应的 option
+ title: {
+ text: '2004年统计值'
+ },
+ series: [
+ { data: [] },
+ { data: [] },
+ { data: [] }
+ ]
+ }]
+});
```
-在上例中，`timeline.data` 中的每一项，对应于 `options` 数组中的每个 `option`。
-
<br>
-**使用注意与最佳实践：**
-
-+ 公有的配置项，推荐配置在 `baseOption` 中。`timeline` 播放切换时，会把 `options` 数组中的对应的 `option`，与 `baseOption` 进行 merge 形成最终的 `option`。
-
-+ `options` 数组中，如果某一数组项中配置了某个属性，那么其他数组项中也必须配置某个属性，而不能缺省。否则这个属性的执行效果会遗留。
-
-+ *复合 option* 中的 `options` 不支持 merge。
+**`finalOption` 是怎么计算出来的?**
- 也就是说，当第二（或三、四、五 ...）次 `chart.setOption(rawOption)` 时，如果 `rawOption` 是*复合 option*（即包含 `options` 列表），那么新的 `rawOption.options` 列表不会和老的 `options` 列表进行 merge，而是简单替代。当然，`rawOption.baseOption` 仍然会正常和老的 option 进行merge。
+{{ use: partial-timeline-merge-strategy }}
<br>
-**与 ECharts 2 的兼容性：**
+**兼容 ECharts4**
-+ ECharts 3 中不再支持 timeline.notMerge 参数，也就是不支持 notMerge 模式。如果遇到这种场景需要使用，可在外部进行option管理，并用 setOption(option, true) 这样的notMerge方式设置。
+如下这种设置方式，也支持：
+```js
+option = {
+ baseOption: {
+ timeline: {},
+ series: [],
+ // ... other properties of baseOption.
+ },
+ options: []
+};
+```
-+ ECharts 3 和 ECharts 2 相比，timeline 属性的定义位置有所不同，移到了 `baseOption` 中，统一作为一个普通的组件看待。但是，仍然兼容 ECharts2 的 timeline 定义位置，只是不再推荐这样写。
<ExampleBaseOption name="timeline" title="时间轴" title-en="Timeline">
@@ -515,6 +522,19 @@ const option = {
拖动圆点的时候，是否实时更新视图。
+## replaceMerge(Array|string) = undefined
+
+{{ use: partial-timeline-merge-strategy }}
+
+<br>
+
+`replaceMerge` 的值可以是一个组件的 `mainType`，例如 `replaceMerge: 'xAxis'`。也可以是 `mainType` 数组，例如 `replaceMerge: ['xAxis', 'series']`。
+
+常见需要使用 `replaceMerge` 的地方是，如果需要下一个时间刻度的 series 完全替换上一个时间刻度的 series 而不进行任何 merge ，可以设置 `replaceMerge: 'series'`，并且两个时间刻度的 series id 不相同或者没有 id 。
+
+参见这个 [示例](${galleryEditorPath}doc-example/timeline-dynamic-series&edit=1&reset=1)。
+
+
## controlPosition(string) = 'left'
<ExampleUIControlEnum options="left,right" />
@@ -877,3 +897,14 @@ const option = {
) }}
{{ /if }}
+
+
+{{ target: partial-timeline-merge-strategy }}
+
+初始化的时候，对应于当前时间的那个 `switchableOption` 会被合并（merge）到 `baseOption`，形成 `finalOption`。而每当时间变化时，对应于新时间的 `switchableOption` 会被合并（merge）到`finalOption`。
+
+有两种合并（merge）策略：
++ 默认使用 `NORMAL_MERGE`。
++ 如果 [timeline.replaceMerge](~option.html#timeline.replaceMerge) 被指定了，则使用 `REPLACE_MERGE`。如果要知道 `REPLACE_MERGE` 更多信息，可以参见 [setOption](~api.html#echartsInstance.setOption) 中 `REPLACE_MERGE` 一节。
+。
+
diff --git a/zh/option/option.md b/zh/option/option.md
index bf6224a..58b4579 100644
--- a/zh/option/option.md
+++ b/zh/option/option.md
@@ -121,3 +121,9 @@ ECharts 2 里是底层强制使用单独的层绘制高亮图形，但是会带
注意，这个参数实际影响的是『展示』，而非用户输入的时间值的解析。
关于用户输入的时间值（例如 `1491339540396`, `'2013-01-04'` 等）的解析，参见 [date 中时间相关部分](~series-line.data)。
+
+
+# options(Array)
+
+用于 [timeline](option.html#timeline) 或者 [media query](option.html#media) 的 option 数组。数组的每一项是一个 echarts option (`ECUnitOption`)。
+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org