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 2022/01/26 05:07:57 UTC
[echarts-doc] branch master updated: add ssr api
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 3147dca add ssr api
3147dca is described below
commit 3147dcadcbb6915754bfb67d7d18404bc23a1986
Author: pissang <bm...@gmail.com>
AuthorDate: Wed Jan 26 13:07:48 2022 +0800
add ssr api
---
en/api/echarts-instance.md | 234 ++++++++++++++++++-----------------
en/api/echarts.md | 94 ++++++++-------
zh/api/echarts-instance.md | 248 ++++++++++++++++++++------------------
zh/api/echarts.md | 98 +++++++--------
zh/option/component/geo-common.md | 1 -
5 files changed, 348 insertions(+), 327 deletions(-)
diff --git a/en/api/echarts-instance.md b/en/api/echarts-instance.md
index 055dc5d..7694bdd 100644
--- a/en/api/echarts-instance.md
+++ b/en/api/echarts-instance.md
@@ -54,26 +54,19 @@ chart.setOption(option, {
+ opts
- + `notMerge`: `boolean`
+ + `notMerge` Optional. Whether not to merge with previous `option`. `false` by default, means merge, see more details in **Component Merging Modes**. If `true`, all of the current components will be removed and new components will be created according to the new `option`.
- Optional; states whether not to merge with previous `option`; `false` by default, means merge, see more details in **Component Merging Modes**. If `true`, all of the current components will be removed and new components will be created according to the new `option`.
+ + `replaceMerge` Optional. Users can specify "component main types" here, which are the properties under the root of the option tree in [configuration item manual](option.html) (e.g., `xAxis`, `series`). The specified types of component will be merged in the mode "replaceMerge". If users intending to remove some part of components, `replaceMerge` can be used. See more details in **Component Merging Modes**.
- + `replaceMerge`: `string` | `string[]`
+ + `lazyUpdate` Opional. Whether not to update chart immediately. `false` by default, stating update chart synchronously. If `true`, the chart will be updated in the next animation frame.
- Optional; users can specify "component main types" here, which are the properties under the root of the option tree in [configuration item manual](option.html) (e.g., `xAxis`, `series`). The specified types of component will be merged in the mode "replaceMerge". If users intending to remove some part of components, `replaceMerge` can be used. See more details in **Component Merging Modes**.
+ + `silent` Optional. Whether not to prevent triggering events when calling `setOption`. `false` by default, stating trigger events.
- + `lazyUpdate`: `boolean`
- Optional; states whether not to update chart immediately; `false` by default, stating update chart synchronously. If `true`, the chart will be updated in the next animation frame.
-
- + `silent`: `boolean`
-
- Optional; states whether not to prevent triggering events when calling `setOption`; `false` by default, stating trigger events.
-
-
-**Component Merging Modes**
+<h4>Component Merging Modes</h4>
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`.
@@ -81,96 +74,106 @@ Within a specific type of components (more accurately, "component main type". e.
What is `Normal Merge` and `Replace 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 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:
- ```ts
- // Existing components:
- {
- xAxis: [
- { id: 'm', interval: 5 },
- { id: 'n', name: 'nnn', interval: 6 }
- { id: 'q', interval: 7 }
- ]
- }
- // Incoming option:
- chart.setOption({
- xAxis: [
- // No id given. Will be merged to the first unmatched existing component `id: 'q'`
- { interval: 77 },
- // No id given. Will create new component
- { interval: 88 },
- // No id given but name given. Will be merged to `name: 'nnn'`
- { name: 'nnn', interval: 66 },
- // id given. Will be merged to `id: 'm'`.
- { id: 'm', interval: 55 }
- ]
- });
- // Result components:
- {
- xAxis: [
- { id: 'm', interval: 55 },
- { id: 'n', name: 'nnn', interval: 66 },
- { id: 'q', interval: 77 },
- { interval: 88 }
- ]
- }
- ```
-+ `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`.
- + 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:
- ```ts
- // Existing components:
- {
- xAxis: [
- { id: 'm', interval: 5, min: 1000 },
- { id: 'n', name: 'nnn', interval: 6, min: 1000 }
- { id: 'q', interval: 7, min: 1000 }
- ]
- }
- // Incoming option:
- chart.setOption({
- xAxis: [
- { interval: 111 },
- // id given. Will be merged to the existing `id: 'q'`.
- { id: 'q', interval: 77 },
- // id given, but can not find in the existing components.
- { id: 't', interval: 222 },
- { interval: 333 }
- ]
- }, { replaceMerge: 'xAxis' });
- // Result components:
- {
- xAxis: [
- // The original component { id: 'm' } has been removed
- // and replaced to this new component. So `min: 1000` is discarded.
- { interval: 111 },
- // The original component { id: 'n' } has been removed
- // and replaced to this new component. So `min: 1000` is discarded.
- { id: 't', interval: 222 },
- // The original component has been merged with this new component.
- // So `min: 1000` is kept.
- { id: 'q', interval: 77, min: 1000 },
- { interval: 333 }
- ]
- }
- ```
+<h5>Normal Merge</h5>
+
+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 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:
+```ts
+// Existing components:
+{
+ xAxis: [
+ { id: 'm', interval: 5 },
+ { id: 'n', name: 'nnn', interval: 6 }
+ { id: 'q', interval: 7 }
+ ]
+}
+// Incoming option:
+chart.setOption({
+ xAxis: [
+ // No id given. Will be merged to the first unmatched existing component `id: 'q'`
+ { interval: 77 },
+ // No id given. Will create new component
+ { interval: 88 },
+ // No id given but name given. Will be merged to `name: 'nnn'`
+ { name: 'nnn', interval: 66 },
+ // id given. Will be merged to `id: 'm'`.
+ { id: 'm', interval: 55 }
+ ]
+});
+// Result components:
+{
+ xAxis: [
+ { id: 'm', interval: 55 },
+ { id: 'n', name: 'nnn', interval: 66 },
+ { id: 'q', interval: 77 },
+ { interval: 88 }
+ ]
+}
+```
+
+<h5>`Replace Merge`</h5>
+
+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`.
++ 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:
+```ts
+// Existing components:
+{
+ xAxis: [
+ { id: 'm', interval: 5, min: 1000 },
+ { id: 'n', name: 'nnn', interval: 6, min: 1000 }
+ { id: 'q', interval: 7, min: 1000 }
+ ]
+}
+// Incoming option:
+chart.setOption({
+ xAxis: [
+ { interval: 111 },
+ // id given. Will be merged to the existing `id: 'q'`.
+ { id: 'q', interval: 77 },
+ // id given, but can not find in the existing components.
+ { id: 't', interval: 222 },
+ { interval: 333 }
+ ]
+}, { replaceMerge: 'xAxis' });
+// Result components:
+{
+ xAxis: [
+ // The original component { id: 'm' } has been removed
+ // and replaced to this new component. So `min: 1000` is discarded.
+ { interval: 111 },
+ // The original component { id: 'n' } has been removed
+ // and replaced to this new component. So `min: 1000` is discarded.
+ { id: 't', interval: 222 },
+ // The original component has been merged with this new component.
+ // So `min: 1000` is kept.
+ { id: 'q', interval: 77, min: 1000 },
+ { interval: 333 }
+ ]
+}
+```
-**Remove Component**
+<h5>Remove Component</h5>
There are two ways to remove components:
+ Totally removal: use `notMerge: true`, all of the components will be removed.
@@ -254,25 +257,32 @@ Resizes chart, which should be called manually when container size changes.
**Parameters**
+ `opts`
- Optional; which may contain:
+ Optional. Which may contain:
+
+ + `width` Specify width explicitly, in pixel. If setting to `null`/`undefined`/`'auto'`, width of `dom` (instance container) will be used.
- + `width`
+ + `height` Specify height explicitly, in pixel. If setting to `null`/`undefined`/`'auto'`, height of `dom` (instance container) will be used.
- Specify width explicitly, in pixel. If setting to `null`/`undefined`/`'auto'`, width of `dom` (instance container) will be used.
+ + `silent` Specify whether or not to prevent triggering events.
- + `height`
+ + `animation` Whether to apply transition animation when resize, including `duration` and `easing`, the default `duration` is 0, that is, no transition animation is applied.
- Specify height explicitly, in pixel. If setting to `null`/`undefined`/`'auto'`, height of `dom` (instance container) will be used.
+**Tip:**
- + `silent`
+Sometimes charts may be placed in multiple tabs. Those in hidden labels may fail to initialize due to the ignorance of container width and height. So `resize` should be called manually to get the correct width and height when switching to the corresponding tabs, or specify width/heigth in `opts` explicitly.
- Specify whether or not to prevent triggering events.
+## renderToSVGString(Function)
- + `animation`
+Render to a SVG string. Available when setting `renderer: 'svg'` to use SVG rendering mode.
+
+Must use this method to render if server-side rendering is enabled with the `ssr` parameter in `echarts.init`
+
+**Parameters**
+
++ `opts`
- Whether to apply transition animation when resize, including `duration` and `easing`, the default `duration` is 0, that is, no transition animation is applied.
+ + `useViewBox` Whether to add [viewBox](https://developer.mozilla.org/zh-CN/docs/Web/SVG/Attribute/viewBox) in the generated SVG string
-**Tip:** Sometimes charts may be placed in multiple tabs. Those in hidden labels may fail to initialize due to the ignorance of container width and height. So `resize` should be called manually to get the correct width and height when switching to the corresponding tabs, or specify width/heigth in `opts` explicitly.
## dispatchAction(Function)
```ts
diff --git a/en/api/echarts.md b/en/api/echarts.md
index 5645701..b009aed 100644
--- a/en/api/echarts.md
+++ b/en/api/echarts.md
@@ -19,11 +19,9 @@ Creates an ECharts instance, and returns an [echartsInstance](~echartsInstance).
**Parameters**
+ `dom`
- Instance container, usually is a `div` element with height and width defined.
+ Instance container, usually is a DIV element with height and width defined. It's only optional when `opts.ssr` is enabled for server-side rendering.
- **Attention: **If `div` is hidden, ECharts initialization tends to fail due to the lack of width and height information. In this case, you can explicitly specify `style.width` and `style.height` of `div`, or manually call [echartsInstance.resize](~echartsInstance.resize) after showing `div`.
-
- ECharts 3 supports using `canvas` element as container directly, thus the canvas can be used somewhere else as image directly after rendering the chart. For example, canvas can be used as a texture in WebGL, which enables updating charts in real-time, as compared to using images generated with [echartsInstance.getDataURL](~echartsInstance.getDataURL).
+ It can also be a `canvas` element. thus the canvas can be used somewhere else as image directly after rendering the chart. For example, canvas can be used as a texture in WebGL, which enables updating charts in real-time, as compared to using images generated with [echartsInstance.getDataURL](~echartsInstance.getDataURL).
+ `theme`
@@ -35,6 +33,7 @@ Creates an ECharts instance, and returns an [echartsInstance](~echartsInstance).
+ `devicePixelRatio` Ratio of one physical pixel to the size of one device independent pixels. Browser's `window.devicePixelRatio` is used by default.
+ `renderer` Supports `'canvas'` or `'svg'`. See [Render by Canvas or SVG](${handbookPath}best-practices/canvas-vs-svg).
+ + `ssr` Whether to use server-side rendering. Only available in SVG rendering mode. When enabled, it will no longer render automatically every frame, you have to use the [renderToSVGString]((~echartsInstance.renderToSVGString) method to get the rendered SVG string.
+ `useDirtyRect` Enable dirty rectangle rendering or not, `false` by default. See [New features in ECharts 5](${handbookPath}basics/release-note/v5-feature).
+ `width` Specify width explicitly, in pixel. If setting to `null`/`undefined`/`'auto'`, width of `dom` (instance container) will be used.
+ `height` Specify height explicitly, in pixel. If setting to `null`/`undefined`/`'auto'`, height of `dom` (instance container) will be used.
@@ -45,6 +44,13 @@ Creates an ECharts instance, and returns an [echartsInstance](~echartsInstance).
const chart = echarts.init(dom, null, {renderer: 'svg'});
```
+**Note**
+
+If DIV is hidden, ECharts initialization tends to fail due to the lack of width and height information. In this case, you can explicitly specify `style.width` and `style.height` of DIV, or manually call [echartsInstance.resize](~echartsInstance.resize) after showing DIV.
+
+The height and width must be set via `opts.width` and `opts.height` in the server side rendering.
+
+
## connect(Function)
```ts
(group:string|Array)
@@ -123,6 +129,7 @@ echarts.use(
See [Use ECharts with bundler and NPM](${handbookPath}basics/import) for more detailed explaination.
## registerMap(Function)
+
```ts
(
mapName: string,
@@ -154,48 +161,42 @@ Please refer to [option.geo](option.html#geo.map) for usage.
+ `opt`
- + `geoJSON`
-
- Optional; Data in GeoJson format. See [https://geojson.org/](https://geojson.org/) for more format information. Can be a JSON string or a parsed object. This key can also be `geoJson`.
-
- + `svg`
-
- > Since `v5.1.0`
-
- Optional; Data in SVG format. Can be a SVG string or a parsed SVG DOM object. See more info in [SVG Base Map](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20SeriesSVG%20Base%20Map).
-
- + `specialAreas`
-
- Optional; zoomed part of a specific area in the map for better visual effect.
-
- Only work for `geoJSON`, not work for `svg`.
-
- **For example [USA Population Estimates](${galleryEditorPath}map-usa): **
- ```ts
- echarts.registerMap('USA', usaJson, {
- // Move Alaska to the bottom left of United States
- Alaska: {
- // Upper left longitude
- left: -131,
- // Upper left latitude
- top: 25,
- // Range of longitude
- width: 15
- },
- // Hawaii
- Hawaii: {
- left: -110,
- top: 28,
- width: 5
- },
- // Puerto Rico
- 'Puerto Rico': {
- left: -76,
- top: 26,
- width: 2
- }
- });
- ```
+ + `geoJSON` Optional. Data in GeoJson format. See [https://geojson.org/](https://geojson.org/) for more format information. Can be a JSON string or a parsed object. This key can also be `geoJson`.
+
+ + `svg` Optional. Data in SVG format. Can be a SVG string or a parsed SVG DOM object. See more info in [SVG Base Map](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20SeriesSVG%20Base%20Map). Introduced in v5.1.0
+
+ + `specialAreas` Optional. zoomed part of a specific area in the map for better visual effect. Only work for `geoJSON`.
+
+**For example [USA Population Estimates](${galleryEditorPath}map-usa): **
+```ts
+echarts.registerMap('USA', usaJson, {
+ // Move Alaska to the bottom left of United States
+ Alaska: {
+ // Upper left longitude
+ left: -131,
+ // Upper left latitude
+ top: 25,
+ // Range of longitude
+ width: 15
+ },
+ // Hawaii
+ Hawaii: {
+ left: -110,
+ top: 28,
+ width: 5
+ },
+ // Puerto Rico
+ 'Puerto Rico': {
+ left: -76,
+ top: 26,
+ width: 2
+ }
+});
+```
+
+Note:
+
+If you only import the required components in your project, starting from v5.3.0 `registerMap` has to be used after the `MapChart` or `GeoComponent` is imported.
## getMap(Function)
```ts
@@ -216,6 +217,7 @@ Get a registered map in the following format:
Note:
+ `geoJSON` can also be `geoJson`, they have the same reference.
+ SVG registered by `registerMap` can not be obtained by this method yet.
++ If you only import the required components in your project, starting from v5.3.0 `getMap` has to be used after the `MapChart` or `GeoComponent` is imported.
## registerTheme(Function)
diff --git a/zh/api/echarts-instance.md b/zh/api/echarts-instance.md
index 9793abd..8c4511f 100644
--- a/zh/api/echarts-instance.md
+++ b/zh/api/echarts-instance.md
@@ -24,7 +24,6 @@ or
~[500x400](${galleryViewPath}dynamic-data&reset=1&edit=1)
-**注：** ECharts 2.x 中的通过 `addData` , `setSeries` 方法设置配置项的方式将不再支持，在 ECharts 3 中统一使用 `setOption`，可以参考上面示例。
**参数：**
@@ -54,125 +53,125 @@ chart.setOption(option, {
+ opts
- + `notMerge`: `boolean`
+ + `notMerge` 可选。是否不跟之前设置的 `option` 进行合并。默认为 `false`。即表示合并。合并的规则，详见 **组件合并模式**。如果为 `true`，表示所有组件都会被删除，然后根据新 `option` 创建所有新组件。
+ + `replaceMerge` 可选。用户可以在这里指定一个或多个组件，如：`xAxis`, `series`，这些指定的组件会进行 "replaceMerge"。如果用户想删除部分组件，也可使用 "replaceMerge"。详见 **组件合并模式**。
+ + `lazyUpdate` 可选。在设置完 `option` 后是否不立即更新图表，默认为 `false`，即同步立即更新。如果为 `true`，则会在下一个 animation frame 中，才更新图表。
+ + `silent` 可选。阻止调用 `setOption` 时抛出事件，默认为 `false`，即抛出事件。
- 可选。是否不跟之前设置的 `option` 进行合并。默认为 `false`。即表示合并。合并的规则，详见 **组件合并模式**。如果为 `true`，表示所有组件都会被删除，然后根据新 `option` 创建所有新组件。
+<h4>组件合并模式</h4>
- + `replaceMerge`: `string` | `string[]`
+对于一种类型的组件（如：`xAxis`, `series`）：
- 可选。用户可以在这里指定一个或多个组件，如：`xAxis`, `series`，这些指定的组件会进行 "replaceMerge"。如果用户想删除部分组件，也可使用 "replaceMerge"。详见 **组件合并模式**。
++ 如果设置`opts.notMerge`为`true`，那么旧的组件会被完全移除，新的组件会根据`option`创建。
++ 如果设置`opts.notMerge`为`false`，或者没有设置 `opts.notMerge`：
+ + 如果在`opts.replaceMerge`里指定组件类型，这类组件会进行`替换合并`。
+ + 否则，会进行`普通合并`。
- + `lazyUpdate`: `boolean`
+什么是`普通合并`和`替换合并`？
- 可选。在设置完 `option` 后是否不立即更新图表，默认为 `false`，即同步立即更新。如果为 `true`，则会在下一个 animation frame 中，才更新图表。
+<h5>普通合并</h5>
- + `silent`: `boolean`
+对于一种类型的组件（如：`xAxis`, `series`），新来的 `option` 中的每个“组件描述”（如：`{type: 'xAxis', id: 'xx', name: 'kk', ...}`）会被尽量合并到已存在的组件中。剩余的情况，会在组件列表尾部创建新的组件。整体规则细节如下：
- 可选。阻止调用 `setOption` 时抛出事件，默认为 `false`，即抛出事件。
++ 先依次对 `option` 中每个有声明 `id` 或者 `name` 的“组件描述”，寻找能匹配其 `id` 或者 `name` 的已有的组件，找到的话则合并。
++ 再依次对 `option` 中剩余的“组件描述”，寻找还未执行过前一条的已有组件，找到的话则合并。
++ 其他 `option` 中剩余的“组件描述”，用于在组件列表尾部创建新组件。
-**组件合并模式**
+特点：
-对于一种类型的组件（如：`xAxis`, `series`）：
-+ 如果设置`opts.notMerge`为`true`，那么旧的组件会被完全移除，新的组件会根据`option`创建。
-+ 如果设置`opts.notMerge`为`false`，或者没有设置 `opts.notMerge`：
- + 如果在`opts.replaceMerge`里指定组件类型，这类组件会进行`替换合并`。
- + 否则，会进行`普通合并`。
++ 永远不会删除已存在的组件。也就是说，只支持增加，或者更新组件。
++ 组件的索引（componentIndex）永远不会改变。
++ 如果 `id` 和 `name` 没有在 `option` 中被指定（这是经常出现的情况），组件会按照它在 `option` 中的顺序一一合并到已有组件中。这种设定比较符合直觉。
-什么是`普通合并`和`替换合并`？
+例子：
+```ts
+// 已有组件：
+{
+ xAxis: [
+ { id: 'm', interval: 5 },
+ { id: 'n', name: 'nnn', interval: 6 }
+ { id: 'q', interval: 7 }
+ ]
+}
+// 新来的 option ：
+chart.setOption({
+ xAxis: [
+ // id 没有指定。会寻找到第一个没有进行过合并的已有组件，进行合并。
+ // 即合并到 `id: 'q'`。
+ { interval: 77 },
+ // id 没有指定。最终会创建新组件。
+ { interval: 88 },
+ // id 没有指定，但是 name 指定了。会被合并到已有的 `name: 'nnn'` 组件。
+ { name: 'nnn', interval: 66 },
+ // id 指定了，会被合并到已有的 `id: 'm'` 组件。
+ { id: 'm', interval: 55 }
+ ]
+});
+// 结果组件：
+{
+ xAxis: [
+ { id: 'm', interval: 55 },
+ { id: 'n', name: 'nnn', interval: 66 },
+ { id: 'q', interval: 77 },
+ { interval: 88 }
+ ]
+}
+```
-+ `普通合并`
-
- + 对于一种类型的组件（如：`xAxis`, `series`），新来的 `option` 中的每个“组件描述”（如：`{type: 'xAxis', id: 'xx', name: 'kk', ...}`）会被尽量合并到已存在的组件中。剩余的情况，会在组件列表尾部创建新的组件。整体规则细节如下：
- + 先依次对 `option` 中每个有声明 `id` 或者 `name` 的“组件描述”，寻找能匹配其 `id` 或者 `name` 的已有的组件，找到的话则合并。
- + 再依次对 `option` 中剩余的“组件描述”，寻找还未执行过前一条的已有组件，找到的话则合并。
- + 其他 `option` 中剩余的“组件描述”，用于在组件列表尾部创建新组件。
- + 特点：
- + 永远不会删除已存在的组件。也就是说，只支持增加，或者更新组件。
- + 组件的索引（componentIndex）永远不会改变。
- + 如果 `id` 和 `name` 没有在 `option` 中被指定（这是经常出现的情况），组件会按照它在 `option` 中的顺序一一合并到已有组件中。这种设定比较符合直觉。
- + 例子：
- ```ts
- // 已有组件：
- {
- xAxis: [
- { id: 'm', interval: 5 },
- { id: 'n', name: 'nnn', interval: 6 }
- { id: 'q', interval: 7 }
- ]
- }
- // 新来的 option ：
- chart.setOption({
- xAxis: [
- // id 没有指定。会寻找到第一个没有进行过合并的已有组件，进行合并。
- // 即合并到 `id: 'q'`。
- { interval: 77 },
- // id 没有指定。最终会创建新组件。
- { interval: 88 },
- // id 没有指定，但是 name 指定了。会被合并到已有的 `name: 'nnn'` 组件。
- { name: 'nnn', interval: 66 },
- // id 指定了，会被合并到已有的 `id: 'm'` 组件。
- { id: 'm', interval: 55 }
- ]
- });
- // 结果组件：
- {
- xAxis: [
- { id: 'm', interval: 55 },
- { id: 'n', name: 'nnn', interval: 66 },
- { id: 'q', interval: 77 },
- { interval: 88 }
- ]
- }
- ```
-+ `替换合并`
- + 对于一种类型的组件（如：`xAxis`, `series`），只有 `option` 中指定了 `id` 并且已有组件中有此 `id` 时，已有组件会和 `option` 相应组件描述进行合并。否则，已有组件都会删除，新组件会被根据 `option` 创建。细节规则如下：
- + 先依次对 `option` 中每个有声明 `id` 的“组件描述”，寻找能匹配其 `id` 或者 `name` 的已有的组件，找到的话则合并。
- + 删除其他没匹配到的已有组件。
- + 依次对 `option` 中剩余的“组件描述”，创建新组件，填入刚因删除而空出来的位置上，或者增加到末尾。
- + 特点：
- + 与 `普通合并` 相比，支持了组件删除。
- + 已有组件的索引永远不会变。这是为了保证，`option` 或者 API 中的 index 引用（例如：`xAxisIndex: 2`）仍能正常一致得使用。
- + 整个处理过程结束后，可能存在一些“洞”，也就是说，在组件列表中的某些 index 上，并没有组件存在（被删除了）。但是这是可以被开发者预期和控制的。
- + 例子：
- ```ts
- // 已有组件：
- {
- xAxis: [
- { id: 'm', interval: 5, min: 1000 },
- { id: 'n', name: 'nnn', interval: 6, min: 1000 }
- { id: 'q', interval: 7, min: 1000 }
- ]
- }
- // 新来的 option :
- chart.setOption({
- xAxis: [
- { interval: 111 },
- // id 已经指定了。因此会被合并进已有的组件 `id: 'q'`。
- { id: 'q', interval: 77 },
- // id 已经指定了。但是已有组件没有此 id 。
- { id: 't', interval: 222 },
- { interval: 333 }
- ]
- }, { replaceMerge: 'xAxis' });
- // 结果组件：
- {
- xAxis: [
- // 原来的 id 为 'm' 的组件，被移除。
- // 替换为新的组件。新组件中，并没有原来的 `min: 1000` 了。
- { interval: 111 },
- // 原来的 id 为 'n' 的组件，被移除。
- // 替换为新的组件。新组件中，并没有原来的 `min: 1000` 了。
- { id: 't', interval: 222 },
- // 原来的组件没有被移除，而是和 option 中的组件描述进行了合并。
- // 所以 `min: 1000` 被保留了。
- { id: 'q', interval: 77, min: 1000 },
- // 新添加的组件。
- { interval: 333 }
- ]
- }
- ```
+<h5>替换合并</h5>
+
+对于一种类型的组件（如：`xAxis`, `series`），只有 `option` 中指定了 `id` 并且已有组件中有此 `id` 时，已有组件会和 `option` 相应组件描述进行合并。否则，已有组件都会删除，新组件会被根据 `option` 创建。细节规则如下：
+
++ 先依次对 `option` 中每个有声明 `id` 的“组件描述”，寻找能匹配其 `id` 或者 `name` 的已有的组件，找到的话则合并。
++ 删除其他没匹配到的已有组件。
++ 依次对 `option` 中剩余的“组件描述”，创建新组件，填入刚因删除而空出来的位置上，或者增加到末尾。
+
+特点：
-**删除组件**
++ 与 `普通合并` 相比，支持了组件删除。
++ 已有组件的索引永远不会变。这是为了保证，`option` 或者 API 中的 index 引用（例如：`xAxisIndex: 2`）仍能正常一致得使用。
++ 整个处理过程结束后，可能存在一些“洞”，也就是说，在组件列表中的某些 index 上，并没有组件存在（被删除了）。但是这是可以被开发者预期和控制的。
+
+例子：
+```ts
+// 已有组件：
+{
+ xAxis: [
+ { id: 'm', interval: 5, min: 1000 },
+ { id: 'n', name: 'nnn', interval: 6, min: 1000 }
+ { id: 'q', interval: 7, min: 1000 }
+ ]
+}
+// 新来的 option :
+chart.setOption({
+ xAxis: [
+ { interval: 111 },
+ // id 已经指定了。因此会被合并进已有的组件 `id: 'q'`。
+ { id: 'q', interval: 77 },
+ // id 已经指定了。但是已有组件没有此 id 。
+ { id: 't', interval: 222 },
+ { interval: 333 }
+ ]
+}, { replaceMerge: 'xAxis' });
+// 结果组件：
+{
+ xAxis: [
+ // 原来的 id 为 'm' 的组件，被移除。
+ // 替换为新的组件。新组件中，并没有原来的 `min: 1000` 了。
+ { interval: 111 },
+ // 原来的 id 为 'n' 的组件，被移除。
+ // 替换为新的组件。新组件中，并没有原来的 `min: 1000` 了。
+ { id: 't', interval: 222 },
+ // 原来的组件没有被移除，而是和 option 中的组件描述进行了合并。
+ // 所以 `min: 1000` 被保留了。
+ { id: 'q', interval: 77, min: 1000 },
+ // 新添加的组件。
+ { interval: 333 }
+ ]
+}
+```
+
+<h5>删除组件</h5>
有两种方法能删除组件：
+ 删除所有：使用 `notMerge: true`，则所有组件都被删除。
@@ -252,28 +251,39 @@ myChart.setOption({
改变图表尺寸，在容器大小发生改变时需要手动调用。
-**参数**
+**参数解释**
+ `opts`
- opts 可缺省。有下面几个可选项：
+ opts 可缺省。有下面几个属性：
+
+ + `width` 可显式指定实例宽度，单位为像素。如果传入值为 `null`/`undefined`/`'auto'`，则表示自动取 `dom`（实例容器）的宽度。
+ + `height` 可显式指定实例高度，单位为像素。如果传入值为 `null`/`undefined`/`'auto'`，则表示自动取 `dom`（实例容器）的高度。
+ + `silent` 是否禁止抛出事件。默认为 `false`。
+ + `animation` resize 的时候是否应用过渡动画，包含时长`duration`和缓动`easing`两个配置，默认`duration`为 0，即不应用过渡动画。
+
+**Tip:** 有时候图表会放在多个标签页里，那些初始隐藏的标签在初始化图表的时候因为获取不到容器的实际高宽，可能会绘制失败，因此在切换到该标签页时需要手动调用 `resize` 方法获取正确的高宽并且刷新画布，或者在 `opts` 中显示指定图表高宽。
+
+## renderToSVGString(Function)
- + `width`
+```ts
+(opts?: {
+ useViewBox?: boolean
+}) => string
+```
- 可显式指定实例宽度，单位为像素。如果传入值为 `null`/`undefined`/`'auto'`，则表示自动取 `dom`（实例容器）的宽度。
+渲染得到 SVG 字符串。在设置`renderer: 'svg'`使用 SVG 渲染模式有效。
- + `height`
+如果在`echarts.init`的时候通过`ssr`参数开启了服务端渲染模式
- 可显式指定实例高度，单位为像素。如果传入值为 `null`/`undefined`/`'auto'`，则表示自动取 `dom`（实例容器）的高度。
- + `silent`
+**参数解释**
- 是否禁止抛出事件。默认为 `false`。
++ `opts`
- + `animation`
+ opts 可缺省。有下面几个属性：
- resize 的时候是否应用过渡动画，包含时长`duration`和缓动`easing`两个配置，默认`duration`为 0，即不应用过渡动画。
+ + `useViewBox` 是否在生成的 SVG 字符串中带入 [viewBox](https://developer.mozilla.org/zh-CN/docs/Web/SVG/Attribute/viewBox)
-**Tip:** 有时候图表会放在多个标签页里，那些初始隐藏的标签在初始化图表的时候因为获取不到容器的实际高宽，可能会绘制失败，因此在切换到该标签页时需要手动调用 `resize` 方法获取正确的高宽并且刷新画布，或者在 `opts` 中显示指定图表高宽。
## dispatchAction(Function)
```ts
diff --git a/zh/api/echarts.md b/zh/api/echarts.md
index f95e6bd..d90ee39 100644
--- a/zh/api/echarts.md
+++ b/zh/api/echarts.md
@@ -5,10 +5,11 @@
## init(Function)
```ts
-(dom: HTMLDivElement|HTMLCanvasElement, theme?: Object|string, opts?: {
+(dom?: HTMLDivElement|HTMLCanvasElement, theme?: Object|string, opts?: {
devicePixelRatio?: number,
renderer?: string,
useDirtyRect?: boolean, // 从 `v5.0.0` 开始支持
+ ssr?: boolean,
width?: number|string,
height?: number|string,
locale?: string
@@ -16,14 +17,13 @@
```
创建一个 ECharts 实例，返回 [echartsInstance](~echartsInstance)，不能在单个容器上初始化多个 ECharts 实例。
-**参数**
-+ `dom`
+**参数解释**
- 实例容器，一般是一个具有高宽的`div`元素。
++ `dom`
- **注：**如果`div`是隐藏的，ECharts 可能会获取不到`div`的高宽导致初始化失败，这时候可以明确指定`div`的`style.width`和`style.height`，或者在`div`显示后手动调用 [echartsInstance.resize](~echartsInstance.resize) 调整尺寸。
+ 实例容器，一般是一个具有高宽的 DIV 元素。只有在设置`opts.ssr`开启了服务端渲染后该参数才是可选。
- ECharts 3 中支持直接使用`canvas`元素作为容器，这样绘制完图表可以直接将 canvas 作为图片应用到其它地方，例如在 WebGL 中作为贴图，这跟使用 [echartsInstance.getDataURL](~echartsInstance.getDataURL) 生成图片链接相比可以支持图表的实时刷新。
+ 也支持直接使用`canvas`元素作为容器，这样绘制完图表可以直接将 canvas 作为图片应用到其它地方，例如在 WebGL 中作为贴图，这跟使用 [getDataURL](~echartsInstance.getDataURL) 生成图片链接相比可以支持图表的实时刷新。
+ `theme`
@@ -33,11 +33,12 @@
附加参数。有下面几个可选项：
- + `devicePixelRatio` 设备像素比，默认取浏览器的值`window.devicePixelRatio`。
- + `renderer` 渲染器，支持 `'canvas'` 或者 `'svg'`。参见 [使用 Canvas 或者 SVG 渲染](${handbookPath}best-practices/canvas-vs-svg)。
- + `useDirtyRect` 是否开启脏矩形渲染，默认为`false`。参见 [ECharts 5 新特性](${handbookPath}basics/release-note/v5-feature)。
- + `width` 可显式指定实例宽度，单位为像素。如果传入值为 `null`/`undefined`/`'auto'`，则表示自动取 `dom`（实例容器）的宽度。
- + `height` 可显式指定实例高度，单位为像素。如果传入值为 `null`/`undefined`/`'auto'`，则表示自动取 `dom`（实例容器）的高度。
+ + `devicePixelRatio`设备像素比，默认取浏览器的值`window.devicePixelRatio`。
+ + `renderer` 渲染模式，支持`'canvas'`或者`'svg'`。参见 [使用 Canvas 或者 SVG 渲染](${handbookPath}best-practices/canvas-vs-svg)。
+ + `ssr` 是否使用服务端渲染，只有在 SVG 渲染模式有效。开启后不再会每帧自动渲染，必须要调用 [renderToSVGString]((~echartsInstance.renderToSVGString) 方法才能得到渲染后 SVG 字符串。
+ + `useDirtyRect`是否开启脏矩形渲染，只有在 Canvas 渲染模式有效，默认为`false`。参见 [ECharts 5 新特性](${handbookPath}basics/release-note/v5-feature)。
+ + `width` 可显式指定实例宽度，单位为像素。如果传入值为`null`/`undefined`/`'auto'`，则表示自动取 `dom`（实例容器）的宽度。
+ + `height` 可显式指定实例高度，单位为像素。如果传入值为`null`/`undefined`/`'auto'`，则表示自动取 `dom`（实例容器）的高度。
+ `locale` 使用的语言，内置 `'ZH'` 和 `'EN'` 两个语言，也可以使用 [echarts.registerLocale](~echarts.registerLocale) 方法注册新的语言包。目前支持的语言见 [src/i18n](https://github.com/apache/echarts/tree/release/src/i18n)。
如果不指定主题，也需在传入`opts`前先传入`null`，如：
@@ -45,6 +46,11 @@
const chart = echarts.init(dom, null, {renderer: 'svg'});
```
+**注：**
+如果容器是隐藏的，ECharts 可能会获取不到 DIV 的高宽导致初始化失败，这时候可以明确指定 DIV 的`style.width`和`style.height`，或者在`div`显示后手动调用 [resize](~echartsInstance.resize) 调整尺寸。
+
+在使用服务端渲染的模式下，必须通过`opts.width`和`opts.height`设置高和宽。
+
## connect(Function)
```ts
@@ -122,6 +128,7 @@ echarts.use(
更详细的使用方式见 [在项目中引入 Apache ECharts](${handbookPath}basics/import) 一文
## registerMap(Function)
+
```ts
(
mapName: string,
@@ -153,49 +160,41 @@ echarts.use(
+ `opt`
- + `geoJSON`
-
- 可选。GeoJson 格式的数据，具体格式见 [https://geojson.org/](https://geojson.org/)。可以是 JSON 字符串，也可以是解析得到的对象。这个参数也可以写为 `geoJson`，效果相同。
+ + `geoJSON` 可选。GeoJson 格式的数据，具体格式见 [https://geojson.org/](https://geojson.org/)。可以是 JSON 字符串，也可以是解析得到的对象。这个参数也可以写为 `geoJson`，效果相同。
- + `svg`
+ + `svg` 可选。从 `v5.1.0` 开始支持SVG 格式的数据。可以是字符串，也可以是解析得到的 SVG DOM 对象。更多信息参见 [SVG 底图](tutorial.html#%E5%9C%B0%E7%90%86%E5%9D%90%E6%A0%87%E7%B3%BB%E5%92%8C%E5%9C%B0%E5%9B%BE%E7%B3%BB%E5%88%97%E7%9A%84%20SVG%20%E5%BA%95%E5%9B%BE)。
- > 从 `v5.1.0` 开始支持
+ + `specialAreas` 可选。将地图中的部分区域缩放到合适的位置，可以使得整个地图的显示更加好看。只在 `geoJSON` 中生效，`svg` 中不生效。
- 可选。SVG 格式的数据。可以是字符串，也可以是解析得到的 SVG DOM 对象。更多信息参见 [SVG 底图](tutorial.html#%E5%9C%B0%E7%90%86%E5%9D%90%E6%A0%87%E7%B3%BB%E5%92%8C%E5%9C%B0%E5%9B%BE%E7%B3%BB%E5%88%97%E7%9A%84%20SVG%20%E5%BA%95%E5%9B%BE)。
+示例 [USA Population Estimates](${galleryEditorPath}map-usa)：
- + `specialAreas`
-
- 可选。将地图中的部分区域缩放到合适的位置，可以使得整个地图的显示更加好看。
-
- 只在 `geoJSON` 中生效，`svg` 中不生效。
-
- **示例 [USA Population Estimates](${galleryEditorPath}map-usa)：**
- ```ts
- echarts.registerMap('USA', usaJson, {
- // 把阿拉斯加移到美国主大陆左下方
- Alaska: {
- // 左上角经度
- left: -131,
- // 左上角纬度
- top: 25,
- // 经度横跨的范围
- width: 15
- },
- // 夏威夷
- Hawaii: {
- left: -110,
- top: 28,
- width: 5
- },
- // 波多黎各
- 'Puerto Rico': {
- left: -76,
- top: 26,
- width: 2
- }
- });
- ```
+```ts
+echarts.registerMap('USA', usaJson, {
+ // 把阿拉斯加移到美国主大陆左下方
+ Alaska: {
+ // 左上角经度
+ left: -131,
+ // 左上角纬度
+ top: 25,
+ // 经度横跨的范围
+ width: 15
+ },
+ // 夏威夷
+ Hawaii: {
+ left: -110,
+ top: 28,
+ width: 5
+ },
+ // 波多黎各
+ 'Puerto Rico': {
+ left: -76,
+ top: 26,
+ width: 2
+ }
+});
+```
+注：如果你在项目中使用了按需引入，从 v5.3.0 开始`registerMap`必须要在引入地图组件后才能使用。
## getMap(Function)
```ts
@@ -215,6 +214,7 @@ echarts.use(
注：
+ `geoJSON` 也可写为 `geoJson`，二者引用的是相同的内容。
+ 对于 `registerMap` 所注册的 SVG ，暂并不支持从此方法中返回。
++ 如果你在项目中使用了按需引入，从 v5.3.0 开始`getMap`必须要在引入地图组件后才能使用。
## registerTheme(Function)
diff --git a/zh/option/component/geo-common.md b/zh/option/component/geo-common.md
index 7ae8d2b..15380c2 100644
--- a/zh/option/component/geo-common.md
+++ b/zh/option/component/geo-common.md
@@ -107,7 +107,6 @@ series: {
unproject: (point) => projection.invert(point)
}
}
-
```
注：自定义投影只有在使用`GeoJSON`作为数据源的时候有用。
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org