diff --git a/README.md b/README.md
index 62eb35bc2..18040d3b7 100644
--- a/README.md
+++ b/README.md
@@ -60,42 +60,58 @@ For example,
### Global Variables
These global variables can be used in doc:
-+ `${galleryViewPath}`
-+ `${galleryEditorPath}`
-+ `${websitePath}`
++ `${galleryViewPath}`: Use it like `${galleryViewPath}pie-legend`.
++ `${galleryEditorPath}`: Use it like `${galleryEditorPath}pie-legend`.
++ `${optionDocPath}`: Use it like `${optionDocPath}#xAxis.type`.
++ `${apiDocPath}`: Use it like `${apiDocPath}#echarts.init`.
++ `${handbookPath}`: Use it like `${handbookPath}basics/import`.
++ `${websitePath}`: Use it like `${websitePath}/examples/en/index.html#chart-type-custom`.
See samples in "Reference of echarts-examples or other links"
-### Reference of echarts-examples or Other Links
+### Reference of Other ECharts Option
-Embed an example in doc:
+A `~` can be used to refer to a option item in the same doc. For example:
```md
-~[700X300](${galleryEditorPath}pie-legend&edit=1&reset=1)
-~[700x300](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
+[xAxis.name](~xAxis.name)
```
-Provide an example link in doc:
+To reference an anchor in different doc, it can be:
```md
-[vertically scrollable legend](${galleryEditorPath}pie-legend&edit=1&reset=1)
-[aria pie](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
+[itemStyle](option.html#series.itemStyle)
+[action.highlight](api.html#action.highlight)
+[Custom Series](tutorial.html#Custom%20Series)
+[Use ECharts with bundler and NPM](${handbookPath}basics/import)
```
-Provide a website link in doc:
+To add references in a code block, we have to:
```md
-[Apache ECharts website](${websitePath}/en/download.html)
+// See doc: ${optionDocPath}#series-bar.select
+// See doc: ${apiDocPath}#echarts.init
```
-### Reference of Other ECharts Option
+### Reference of echarts-examples or Other Links
-A `~` can be used to refer to a option item in the same doc. For example:
+Embed an example in doc (display the example directly in doc with an iframe. To avoid performance issues, do not overuse it.):
```md
-[xAxis.name](~xAxis.name)
+~[700X300](${galleryViewPath}pie-legend&edit=1&reset=1)
+~[700x300](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
```
-If intending to reference an anchor in different doc, it can be:
+Insert an image:
```md
-In api.html, reference
-[itemStyle](option.html#series.itemStyle)
+[600xauto](~axis-align-with-label.png)
+```
+
+Provide an example link in doc:
+```md
+[vertically scrollable legend](${galleryEditorPath}pie-legend&edit=1&reset=1)
+[aria pie](${galleryEditorPath}doc-example/aria-pie&edit=1&reset=1)
+```
+
+Provide a website link in doc:
+```md
+[Apache ECharts website](${websitePath}/en/download.html)
```
diff --git a/build/build-doc.js b/build/build-doc.js
index ac0d8e700..a7d49f9ca 100644
--- a/build/build-doc.js
+++ b/build/build-doc.js
@@ -23,7 +23,7 @@ const chalk = require('chalk');
const argv = require('yargs').argv;
const path = require('path');
const chokidar = require('chokidar');
-const {debounce} = require('lodash');
+const {debounce, cloneDeep} = require('lodash');
const {getDocJSONPVarNname} = require('../src/shared');
const {readConfigEnvFile} = require('./helper');
@@ -63,17 +63,24 @@ for (let key in config) {
}
async function md2jsonAsync(opt) {
-
var newOpt = Object.assign({
path: path.join(opt.language, opt.entry, '**/*.md'),
- tplEnv: Object.assign({}, config, {
- galleryViewPath: config.galleryViewPath.replace('${lang}', opt.language),
- galleryEditorPath: config.galleryEditorPath.replace('${lang}', opt.language),
- handbookPath: config.handbookPath.replace('${lang}', opt.language)
- }),
+ tplEnv: replaceLangInConfig(cloneDeep(config)),
imageRoot: config.imagePath
}, opt);
+ function replaceLangInConfig(config) {
+ for (const [prop, value] of Object.entries(config)) {
+ if (typeof value === 'object' && value) {
+ replaceLangInConfig(value)
+ }
+ else if (typeof value === 'string') {
+ config[prop] = value.replace('${lang}', opt.language)
+ }
+ }
+ return config;
+ }
+
function run(cb) {
md2json(newOpt).then(schema => {
writeSingleSchema(schema, opt.language, opt.entry, false);
diff --git a/config/env.asf.js b/config/env.asf.js
index df5487365..9bc9c9560 100644
--- a/config/env.asf.js
+++ b/config/env.asf.js
@@ -3,6 +3,8 @@ const path = require('path');
module.exports = {
galleryViewPath: 'https://echarts.apache.org/examples/${lang}/view.html?c=',
galleryEditorPath: 'https://echarts.apache.org/examples/${lang}/editor.html?c=',
+ optionDocPath: 'https://echarts.apache.org/${lang}/option.html',
+ apiDocPath: 'https://echarts.apache.org/${lang}/api.html',
handbookPath: 'https://echarts.apache.org/handbook/${lang}/',
websitePath: 'https://echarts.apache.org',
diff --git a/config/env.dev.js b/config/env.dev.js
index 127270d47..cdcb030ce 100644
--- a/config/env.dev.js
+++ b/config/env.dev.js
@@ -3,6 +3,8 @@ const path = require('path');
module.exports = {
galleryViewPath: 'http://localhost/echarts-website/examples/${lang}/view.html?c=',
galleryEditorPath: 'http://localhost/echarts-website/examples/${lang}/editor.html?c=',
+ optionDocPath: 'https://echarts.apache.org/${lang}/option.html',
+ apiDocPath: 'https://echarts.apache.org/${lang}/api.html',
handbookPath: 'http://localhost/echarts-website/handbook/${lang}/',
websitePath: 'http://localhost/echarts-website',
diff --git a/config/env.localsite.js b/config/env.localsite.js
index 242b29b76..91550c65c 100644
--- a/config/env.localsite.js
+++ b/config/env.localsite.js
@@ -3,6 +3,8 @@ const path = require('path');
module.exports = {
galleryViewPath: 'http://localhost/echarts-website/examples/${lang}/view.html?c=',
galleryEditorPath: 'http://localhost/echarts-website/examples/${lang}/editor.html?c=',
+ optionDocPath: 'https://echarts.apache.org/${lang}/option.html',
+ apiDocPath: 'https://echarts.apache.org/${lang}/api.html',
handbookPath: 'http://localhost/echarts-website/handbook/${lang}/',
websitePath: './',
diff --git a/en/api/action.md b/en/api/action.md
index 666038429..e3ac4a20b 100644
--- a/en/api/action.md
+++ b/en/api/action.md
@@ -28,6 +28,37 @@
name?: string,{{/target}}
+{{ target: action-axis-break-expand-collapse-common }}
+Can not be used to create a new axis break.
+```ts
+dispatchAction({
+ type: '${actionType}',
+
+ // The target axis components can be queried by either index, id, or name.
+ xAxisIndex?: 'all' | number;
+ xAxisId?: string | number;
+ xAxisName?: string;
+ yAxisIndex?: 'all' | number;
+ yAxisId?: string | number;
+ yAxisName?: string;
+ singleAxisIndex?: 'all' | number;
+ singleAxisId?: string | number;
+ singleAxisName?: number;
+
+ breaks: {
+ // Use the start/end to identify the target break items.
+ // See more details in doc: ${optionDocPath}#xAxis.breaks.start
+ start: string | number | Date,
+ end: string | number | Date,
+ }
+})
+```
+
+Then event [axisbreakchanged](~events.axisbreakchanged) is triggered.
+
+See also [axis break isExpanded](option.html#xAxis.breaks.isExpanded).
+{{/target}}
+
{{ target: action }}
# action
@@ -127,6 +158,39 @@ dispatchAction({
})
```
+
+## axis
+
+### expandAxisBreak
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Expand one or multiple existing axis break items.
+
+{{ use: action-axis-break-expand-collapse-common(
+ actionType = "expandAxisBreak"
+) }}
+
+### collapseAxisBreak
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Collapse one or multiple existing axis break items.
+
+{{ use: action-axis-break-expand-collapse-common(
+ actionType = "collapseAxisBreak"
+) }}
+
+### toggleAxisBreak
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Toggle (expand/collapse) one or multiple existing axis break items.
+
+{{ use: action-axis-break-expand-collapse-common(
+ actionType = "toggleAxisBreak"
+) }}
+
## legend
Actions related to [legend component](option.html#legend), [legend component](option.html#legend) should be imported before use.
diff --git a/en/api/echarts-instance.md b/en/api/echarts-instance.md
index 57c250bea..c9ac20b90 100644
--- a/en/api/echarts-instance.md
+++ b/en/api/echarts-instance.md
@@ -58,7 +58,7 @@ chart.setOption(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**.
- + `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.
+ + `lazyUpdate` Optional. 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` Optional. Whether not to prevent triggering events when calling `setOption`. `false` by default, stating trigger events.
@@ -240,12 +240,14 @@ myChart.setOption({
## setTheme(Function)
+{{ use: partial-version(version = "6.0.0") }}
+
```ts
(
-theme: string | Object
-opts?: {
- silent? boolean
-}
+ theme: string | Object,
+ opts?: {
+ silent?: boolean
+ }
) => void
```
@@ -256,17 +258,49 @@ Sets the theme for the chart instance.
Here is a demo of dynamically setting a theme after initialization:
+Method 1: Register and apply a named theme; the theme can be used in multiple charts.
+```js
+echarts.registerTheme('myTheme', { backgroundColor: 'red' });
+const chart1 = echarts.init(mainDOMElement1);
+chart1.setTheme('myTheme');
+chart1.setOption(...);
+const chart2 = echarts.init(mainDOMElement2);
+chart2.setTheme('myTheme');
+chart2.setOption(...);
+```
+
+Method 2: Apply an anonymous theme directly, which only serves the current chart.
+```js
+const chart1 = echarts.init(mainDOMElement);
+chart1.setTheme({ backgroundColor: 'red' });
+chart1.setOption(...);
+```
+
+**[CAVEAT]:**
+
+In the current implementation, calling `setOption` multiple times in merge mode is not supported when using `setTheme`. That is,
```js
-const chart = echarts.init(...);
-chart.setOption(...);
-// Method 1: Register and apply a named theme
-echarts.registerTheme('myTheme', {backgroundColor: 'red'});
-chart.setTheme('myTheme');
-// Method 2: Apply an anonymous theme directly
-chart.setTheme({backgroundColor: 'red'});
+// --- Bad (May be unexpected) ---
+const chart1 = echarts.init(mainDOMElement);
+chart1.setOption(option1);
+chart1.setOption(option2); // call `setOption` in "merge mode"
+chart1.setOption(option3);
+chart1.setTheme('dark');
+// After calling `setTheme`, the previous options (option1 and option2) are discarded.
+// Only the last option (option3) is retained.
+
+// --- Solution ---
+const chart1 = echarts.init(mainDOMElement);
+// Make sure every option contains all the information and using `notMerge mode` in `setOption`.
+chart1.setOption(option1, {notMerge: true});
+chart1.setOption(option2, {notMerge: true});
+chart1.setOption(option3, {notMerge: true});
+chart1.setTheme('dark');
+// The previous options (option1 and option2) are also discarded.
+// But the last option (option3) contains all the information and is retained,
+// so the finall effect is correct.
```
-If there are no other charts using this theme, the above two methods are the same. If not, you should use the former one, so that `setTheme('myTheme')` can be used in other charts.
## resize(Function)
```ts
@@ -302,7 +336,7 @@ Sometimes charts may be placed in multiple tabs. Those in hidden labels may fail
## renderToSVGString(Function)
-> Since `5.3.0`
+{{ use: partial-version(version = "5.3.0") }}
```ts
(opts?: {
@@ -518,128 +552,298 @@ Unbind event-handler function.
## convertToPixel(Function)
```ts
(
- // finder is used to indicate in which coordinate system conversion is performed.
- // Generally, index or id or name can be used to specify coordinate system.
+ // `finder` is used to indicate in which coordinate system or axis or series
+ // conversion is performed.
+ // Generally, it is identified by xxxIndex or xxxId or xxxName.
finder: {
- seriesIndex?: number,
- seriesId?: string,
- seriesName?: string,
- geoIndex?: number,
- geoId?: string,
- geoName?: string,
xAxisIndex?: number,
- xAxisId?: string,
+ xAxisId?: string | number,
xAxisName?: string,
yAxisIndex?: number,
- yAxisId?: string,
+ yAxisId?: string | number,
yAxisName?: string,
gridIndex?: number,
- gridId?: string,
- gridName?: string
+ gridId?: string | number,
+ gridName?: string,
+
+ polarIndex?: number,
+ polarId?: string | number,
+ polarName?: string,
+
+ geoIndex?: number,
+ geoId?: string | number,
+ geoName?: string,
+
+ singleAxisIndex?: number,
+ singleAxisId?: string | number,
+ singleAxisName?: string,
+
+ calendarIndex?: number,
+ calendarId?: string | number,
+ calendarName?: string,
+
+ matrixIndex?: number,
+ matrixId?: string | number,
+ matrixName?: string,
+
+ seriesIndex?: number,
+ seriesId?: string | number,
+ seriesName?: string,
},
- // The value to be converted.
- value: Array|string
- // Conversion result, in pixel coordinate system, where the origin ([0, 0])
- // is on the left-top of the main dom of echarts instance.
-) => Array|string
+ // The coord (on the specified coordinate system or axis or series) to be converted.
+ coord:
+ [(number | string), (number | string)]
+ | [
+ [(number | string), (number | string)],
+ [(number | string), (number | string)]
+ ]
+ | (number | string),
+ // Extra opt, defined by each coordinate systems.
+ opt?: unknown
+) =>
+ // The result pixel values on canvas, where [0, 0] is on the left-top of
+ // the main dom of echarts instance.
+ [number, number] | number
```
-Convert a point from logical coordinate (e.g., in geo, cartesian, graph, ...) to pixel coordinate.
+Convert the `coord` on coordinate system or axis or series (i.e., [cartesian2d (grid)](option.html#grid), [only xAxis](option.html#xAxis), [only yAxis](option.html#yAxis), [polar](option.html#polar), [geo](option.html#geo), [series.map](option.html#series-map), [singleAxis](option.html#singleAxis), [calender](option.html#calendar), [matrix](option.html#matrix)) to pixel on canvas.
+The format of the input `coord` and return type are defined by each coordinate system or axis or series:
++ In [cartesian2d (grid)](option.html#grid):
-For example:
+ The input `coord` is an two-item array, where `value[0]` and `value[1]` correspond to [xAxis](option.html#xAxis) and [yAxis](option.html#yAxis). The data types varies in terms of [axis.type](option.html#~xAxis.type):
-In [geo](option.html#geo) coordinate system, convert a point from latlong to pixel coordinate:
-```ts
-// [128.3324, 89.5344] represents [longitude, latitude].
-// Perform conversion in the first geo coordinate system:
-chart.convertToPixel('geo', [128.3324, 89.5344]); // The parameter 'geo' means {geoIndex: 0}.
-// Perform conversion in the second geo coordinate system:
-chart.convertToPixel({geoIndex: 1}, [128.3324, 89.5344]);
-// Perform conversion in the geo coordinate system with id 'bb':
-chart.convertToPixel({geoId: 'bb'}, [128.3324, 89.5344]);
-```
+ - If [axis.type](option.html#~xAxis.type) is `'value'`, `'log'`, the input `coord` should be `[number, number]`.
+ - If [axis.type](option.html#~xAxis.type) is `'category'`, the input `coord` can be `[(number | string), (number | string)]`, where `string` represents the original string in `series.data`, and `number` represents an ordinal number converted from the original string (be a non-negative integer that increases starting from `0`).
+ - If [axis.type](option.html#~xAxis.type) is `'time'`, the input `coord` can be `[(number | string | Date), (number | string | Date)]`, where `number` represents a timestamp, and `string | Date` represents any time format that can be parsed by [method `parseDate` in `echarts/src/util/number.ts`](https://github.com/apache/echarts/blob/master/src/util/number.ts).
-In cartesian (see [grid](option.html#grid)), convert a point to pixel coordinate:
-```ts
-// [300, 900] means [value on xAxis, value on yAxis].
-// Notice, there might be more than one xAxis or yAxis in a grid, and each a pair of
-// xAxis-yAxis constitudes a cartesian.
-// Perform conversion in the cartesian consist of the third xAxis and the yAxis with id 'y1'.
-chart.convertToPixel({xAxisIndex: 2, yAxisId: 'y1'}, [300, 900]);
-// Perform conversion in the first cartesian of the grid with id 'g1'.
-chart.convertToPixel({gridId: 'g1'}, [300, 900]);
-```
+ For example,
+ ```ts
+ // [300, 900] means [coord on xAxis, coord on yAxis].
+ // Notice, there might be more than one xAxis or yAxis in a grid, and each a pair of
+ // xAxis-yAxis constitutes a cartesian.
+ // Perform conversion in the cartesian consist of the third xAxis and the yAxis with id 'y1'.
+ chart.convertToPixel({xAxisIndex: 2, yAxisId: 'y1'}, [300, 900]);
+ // Perform conversion in the first cartesian of the grid with id 'g1'.
+ chart.convertToPixel({gridId: 'g1'}, [300, 900]);
+ ```
-Convert a axis value to pixel value:
-```ts
-// In the xAxis with id 'x0', convert value 3000 to the horizontal pixel coordinate:
-chart.convertToPixel({xAxisId: 'x0'}, 3000); // A number will be returned.
-// In the second yAxis, convert value 600 to the vertical pixel coordinate:
-chart.convertToPixel({yAxisIndex: 1}, 600); // A number will be returned.
-```
++ [only yAxis](option.html#xAxis) or [only yAxis](option.html#yAxis):
+
+ For example, convert a axis coord to pixel value:
+ ```ts
+ // In the xAxis with id 'x0' (type: number),
+ // convert coord 3000 to the horizontal pixel coordinate:
+ result = chart.convertToPixel({xAxisId: 'x0'}, 3000); // A pixel number will be returned.
+ // In the second yAxis (type: category),
+ // convert 'my category' to the vertical pixel coordinate:
+ result = chart.convertToPixel({yAxisIndex: 1}, 'my category'); // A pixel number will be returned.
+ ```
+
++ In [polar](option.html#polar):
+
+ It can be analogous to the `cartesian2d (grid)` case. But only support querying by `polarIndex`/`polarId`/`polarName`, but not support querying by `angleAxis` and `radiusAxis`.
+
++ In [geo](option.html#geo):
+
+ The input `coord` can be `[number, number]`, indicating `[longitude, latitude]` if the [map](option.html#geo.map) is `GeoJSON`, or `[x_on_SVG, y_on_SVG]` if the [map](option.html#geo.map) is `SVG`.
+
+ It can also be a `string`, indicating a `name` in `GeoJSON` (i.e., `features[i].properties.name`, see details in [registerMap](~echarts.registerMap)) or `SVG` (i.e., see "Named Element" in [SVG Base Map](${handbookPath}how-to/component-types/geo/svg-base-map)), and return the pixel point of the center of that area.
+
+ For example,
+ ```ts
+ // [128.3324, 89.5344] represents [longitude, latitude].
+ // Perform conversion in the first geo coordinate system:
+ result = chart.convertToPixel('geo', [128.3324, 89.5344]); // The parameter 'geo' means {geoIndex: 0}.
+ // Perform conversion in the second geo coordinate system:
+ result = chart.convertToPixel({geoIndex: 1}, [128.3324, 89.5344]);
+ // Perform conversion in the geo coordinate system with id 'bb':
+ result = chart.convertToPixel({geoId: 'bb'}, [128.3324, 89.5344]);
+ // Input a name in `features[i].properties.name:"Bern"` in `GeoJSON`
+ // or a shape with `name="Bern"` in SVG:
+ result = chart.convertToPixel({geoId: 'bb'}, 'Bern');
+ ```
+
++ In [series.map](option.html#series-map):
+
+ It can be analogous to the `geo` case. For example,
+ ```ts
+ result = chart.convertToPixel({seriesId: 'my_map'}, [128.3324, 89.5344]);
+ ```
+
++ In [singleAxis](option.html#singleAxis):
+
+ It can be analogous to the `only xAxis` or `only yAxis` cases. For example,
+ ```ts
+ result = chart.convertToPixel({singleAxisIndex: 0}, 333); // `axis.type` is `'value'`.
+ result = chart.convertToPixel({singleAxisIndex: 1}, 'my category'); // `axis.type` is `'category'`.
+ ```
+
++ In [calendar](option.html#calendar):
+ {{ use: partial-api-converter-calendar-coord-desc }}
+
++ In [matrix](option.html#matrix):
+ {{ use: partial-api-converter-matrix-coord-desc }}
+
++ In [series.graph](option.html#series-graph):
+
+ For example,
+ ```ts
+ // Since every graph series maintains a coordinate system for itself, we
+ // specify the graph series in `finder`.
+ // The input `coord` (e.g., [2000, 3500]) is in the graph original coordinates,
+ // that is in the same coord space as we used in `series.data[i].x` and
+ // `series.data[i].y`.
+ result = chart.convertToPixel({seriesIndex: 0}, [2000, 3500]);
+ result = chart.convertToPixel({seriesId: 'k2'}, [100, 500]);
+ ```
+
++ Other cases:
+
+ In a coordinate system (cartesian, geo, graph, ...) that contains the given series, convert a point to pixel coordinate:
+ ```ts
+ // Perform convert in the coordinate system that contains the first series.
+ result = chart.convertToPixel({seriesIndex: 0}, [128.3324, 89.5344]);
+ // Perform convert in the coordinate system that contains the series with id 'k2'.
+ result = chart.convertToPixel({seriesId: 'k2'}, [128.3324, 89.5344]);
+ ```
-In [graph](option.html#series-graph), convert a point to pixel coordinate:
-```ts
-// Since every graph series maintains a coordinate system for itself, we
-// specify the graph series in finder.
-chart.convertToPixel({seriesIndex: 0}, [2000, 3500]);
-chart.convertToPixel({seriesId: 'k2'}, [100, 500]);
-```
-In a cooridinate system (cartesian, geo, graph, ...) that contains the given series, convert a point to pixel coordinate:
+## convertToLayout(Function)
+
+{{ use: partial-version(version = "6.0.0") }}
+
```ts
-// Perform convert in the coordinate system that contains the first series.
-chart.convertToPixel({seriesIndex: 0}, [128.3324, 89.5344]);
-// Perform convert in the coordinate system that contains the series with id 'k2'.
-chart.convertToPixel({seriesId: 'k2'}, [128.3324, 89.5344]);
+(
+ // `finder` is used to indicate in which coordinate system
+ // conversion is performed.
+ // Generally, it is identified by xxxIndex or xxxId or xxxName.
+ finder: {
+ calendarIndex?: number,
+ calendarId?: string | number,
+ calendarName?: string,
+
+ matrixIndex?: number,
+ matrixId?: string | number,
+ matrixName?: string,
+ },
+ // The coord (on the specified coordinate system or axis or series) to be converted.
+ coord:
+ [(number | string), (number | string)]
+ | [
+ [(number | string), (number | string)],
+ [(number | string), (number | string)]
+ ]
+ | (number | string),
+ // Extra opt, defined by each coordinate systems.
+ opt?: unknown
+) =>
+ {
+ rect?: {x: number; y: number; width: number; height: number};
+ contentRect?: {x: number; y: number; width: number; height: number};
+ matrixXYLocatorRange?: [[number, number], [number, number]];
+ }
```
+Convert the `coord` on coordinate system (i.e., [calender](option.html#calendar), [matrix](option.html#matrix)) to layout info.
+
+The format of the input `coord` and return type are defined by each coordinate system:
++ In [calendar](option.html#calendar):
+ {{ use: partial-api-converter-calendar-coord-desc }}
+ The return type is:
+ ```ts
+ interface CoordinateSystemDataLayout {
+ // The cell rect for a data item. Whether cell border exists is
+ // not considered, that is, the adjacent cell rectangles touch.
+ rect: {x: number, y: number, width: number, height: number};
+ // Shinked from `rect` to exclude border width.
+ contentRect: {x: number, y: number, width: number, height: number};
+ }
+ ```
+
++ In [matrix](option.html#matrix):
+ {{ use: partial-api-converter-matrix-coord-desc }}
+ The return type is:
+ ```ts
+ interface CoordinateSystemDataLayout {
+ // The cell rect for a data item. Whether cell border exists is
+ // not considered, that is, the adjacent cell rectangles touch.
+ rect: {x: number, y: number, width: number, height: number};
+ // Note: The `contentRect` that exclude border width and padding is
+ // not provided, as matrix coordinate system support that the
+ // result crosses multiple cells.
+
+ // The range of ordinal numbers of X(col) and Y(row) of `rect`.
+ // It means `[[minXOrdinal, maxXOrdinal], [minYOrdinal, maxYOrdinal]]`
+ matrixXYLocatorRange: [[number, number], [number, number]];
+ }
+ ```
## convertFromPixel(Function)
```ts
(
- // finder is used to indicate in which coordinate system conversion is performed.
- // Generally, index or id or name can be used to specify coordinate system.
+ // `finder` is used to indicate in which coordinate system or axis or series
+ // conversion is performed.
+ // Generally, it is identified by xxxIndex or xxxId or xxxName.
finder: {
- seriesIndex?: number,
- seriesId?: string,
- seriesName?: string,
- geoIndex?: number,
- geoId?: string,
- geoName?: string,
xAxisIndex?: number,
- xAxisId?: string,
+ xAxisId?: string | number,
xAxisName?: string,
yAxisIndex?: number,
- yAxisId?: string,
+ yAxisId?: string | number,
yAxisName?: string,
gridIndex?: number,
- gridId?: string,
- gridName?: string
+ gridId?: string | number,
+ gridName?: string,
+
+ polarIndex?: number,
+ polarId?: string | number,
+ polarName?: string,
+
+ geoIndex?: number,
+ geoId?: string | number,
+ geoName?: string,
+
+ singleAxisIndex?: number,
+ singleAxisId?: string | number,
+ singleAxisName?: string,
+
+ calendarIndex?: number,
+ calendarId?: string | number,
+ calendarName?: string,
+
+ matrixIndex?: number,
+ matrixId?: string | number,
+ matrixName?: string,
+
+ seriesIndex?: number,
+ seriesId?: string | number,
+ seriesName?: string,
},
- // The value to be converted, in pixel coordinate system, where the origin ([0, 0])
- // is on the left-top of the main dom of echarts instance.
- value: Array|string
- // Conversion result
-) => Array|string
+ // The pixel values on canvas to be converted, where [0, 0] is on the left-top of
+ // the main dom of echarts instance.
+ value: [number, number] | number,
+ // Extra opt, defined by each coordinate systems.
+ opt?: unknown
+) =>
+ // The result coord
+ [number, number]
+ | [[number, number], [number, number]]
+ | number
```
-Convert a point from pixel coordinate to logical coordinate (e.g., in geo, cartesian, graph, ...). This method is the inverse operation of [convertToPixel](~echartsInstance.convertToPixel), where the examples can be referred.
+Convert a point from pixel coordinate to logical coordinate (e.g., in geo, cartesian, graph, ...).
+
+This method is the inverse operation of [convertToPixel](~echartsInstance.convertToPixel), where the examples can be referred.
## containPixel(Function)
```ts
(
- // finder is used to specify coordinate systems or series on which the judgement performed.
- // Generally, index or id or name can be used to specify coordinate system.
+ // `finder` is used to indicate in which coordinate system or axis or series
+ // conversion is performed.
+ // Generally, it is identified by xxxIndex or xxxId or xxxName.
finder: {
- seriesIndex?: number,
- seriesId?: string,
- seriesName?: string,
- geoIndex?: number,
- geoId?: string,
- geoName?: string,
xAxisIndex?: number,
xAxisId?: string,
xAxisName?: string,
@@ -649,6 +853,18 @@ Convert a point from pixel coordinate to logical coordinate (e.g., in geo, carte
gridIndex?: number,
gridId?: string,
gridName?: string
+
+ geoIndex?: number,
+ geoId?: string,
+ geoName?: string,
+
+ matrixIndex?: number,
+ matrixId?: string,
+ matrixName?: string
+
+ seriesIndex?: number,
+ seriesId?: string,
+ seriesName?: string,
},
// The value to be judged, in pixel coordinate system, where the origin ([0, 0])
// is on the left-top of the main dom of echarts instance.
@@ -658,20 +874,20 @@ Convert a point from pixel coordinate to logical coordinate (e.g., in geo, carte
Determine whether the given point is in the given coordinate systems or series.
-These coordinate systems or series are supported currently: [grid](option.html#grid), [polar](option.html#polar), [geo](option.html#geo), [series-map](option.html#series-map), [series-graph](option.html#series-graph), [series-pie](option.html#series-pie).
+These coordinate systems or series are supported currently: [grid](option.html#grid), [polar](option.html#polar), [geo](option.html#geo), [matrix](option.html#matrix), [series-map](option.html#series-map), [series-graph](option.html#series-graph), [series-pie](option.html#series-pie).
For example:
```ts
// Determine whether point [23, 44] is in the geo whose geoIndex 0.
-chart.containPixel('geo', [23, 44]); // Parameter 'geo' means {geoIndex: 0}
+result = chart.containPixel('geo', [23, 44]); // Parameter 'geo' means {geoIndex: 0}
// Determine whether point [23, 44] is in the grid whose gridId is 'z'.
-chart.containPixel({gridId: 'z'}, [23, 44]);
+result = chart.containPixel({gridId: 'z'}, [23, 44]);
// Determine whether point [23, 44] is in series whose index are 1, 4 or 5.
-chart.containPixel({seriesIndex: [1, 4, 5]}, [23, 44]);
+result = chart.containPixel({seriesIndex: [1, 4, 5]}, [23, 44]);
// Determine whether point [23, 44] is in series whose index are 1, 4 or 5,
// or is in grid whose name is 'a'.
-chart.containPixel({seriesIndex: [1, 4, 5], gridName: 'a'}, [23, 44]);
+result = chart.containPixel({seriesIndex: [1, 4, 5], gridName: 'a'}, [23, 44]);
```
@@ -792,3 +1008,80 @@ Returns whether current instance has been disposed.
## dispose
Disposes instance. Once disposed, the instance can not be used again.
+
+
+
+{{ target: partial-api-converter-calendar-coord-desc }}
+ The input `coord` can be `number | string | Date`, where `number` represents a timestamp, and `string | Date` represents any time format that can be parsed by [method `parseDate` in `echarts/src/util/number.ts`](https://github.com/apache/echarts/blob/master/src/util/number.ts). For example,
+ ```ts
+ result = chart.convertToLayout({calendarIndex: 0}, '2021-01-01');
+ result = chart.convertToLayout({calendarIndex: 0}, new Date(1609459200000));
+ result = chart.convertToLayout({calendarIndex: 0}, 1609459200000);
+ ```
+{{ /target }}
+
+
+{{ target: partial-api-converter-matrix-coord-desc }}
+ The input `coord` identifies a rectangle, whose the center point is return. See more details in [matrix.body.data.coord](option.html#matrix.body.data.coord). For example,
+ ```ts
+ chart.setOption({
+ matrix: {
+ x: {data: ['AA', 'BB', 'CC', 'DD']},
+ y: {data: ['MM', 'NN']}
+ }
+ });
+ result = chart.convertToPixel({matrixIndex: 0}, ['AA', 'NN']);
+ result = chart.convertToLayout({matrixIndex: 0}, ['AA', 'NN']);
+ // The rectangle can cross multiple cells:
+ result = chart.convertToPixel({matrixIndex: 0}, [['AA', 'CC'], 'MM']);
+ result = chart.convertToLayout({matrixIndex: 0}, [['AA', 'CC'], 'MM']);
+ // This is the ordinal number (non-negative, starting from 0) corresponding to
+ // the string name above.
+ result = chart.convertToPixel({matrixIndex: 0}, [1, 2]);
+ result = chart.convertToLayout({matrixIndex: 0}, [1, 2]);
+ result = chart.convertToPixel({matrixIndex: 0}, [[1, 3], [0, 1]]);
+ result = chart.convertToLayout({matrixIndex: 0}, [[1, 3], [0, 1]]);
+ ```
+
+ The input `opt` is optional:
+ ```ts
+ opt?: {
+ // Options:
+ // - `0`/`null`/`undefined` (default) means no clamp, that is, if the input
+ // `coord[0]` or `coord[1]` is `null`/`undefined`/`NaN`/"out of boundary",
+ // the corresponding result part is `NaN`, rather than clamp to the boundary
+ // of the matrix.
+ // - Otherwise, clamp, that is, clamp to the boundary of the matrix, where
+ // - `1`: Clampping in the area of the entire matrix.
+ // - `2`: Clampping in the area of matrix body.
+ // - `3`: Clampping in the area of matrix corner.
+ // Note:
+ // - this argument is supported in both
+ // `convertToPixel`, `convertToLayout` and `convertFromPixel`
+ // - X and Y is considered separately, that is, the result can be
+ // `rect: {x: NaN, width: NaN, y: 123, width: 456}` if only x is out of range.
+ clamp?: null | undefined | 0 | 1 | 2 | 3;
+
+ // If the result rectangular intersects with merged cells
+ // (i.e., `matrix['body'/'corner'].data.mergeCells: true`), whether to expand it
+ // to cover all of the merge cells. Be `false` by default.
+ ignoreMergeCells?: boolean;
+ }
+
+ // For example:
+ const {rect, matrixXYLocatorRange} = chart.convertToLayout(
+ {matrixIndex: 0},
+ [10000, 2],
+ {clamp: 0}
+ );
+ // `rect` is `{x: NaN, y: 10, width: NaN, height: 100}`.
+ // `matrixXYLocatorRange` is `[[NaN, NaN], [2, 2]]`.
+ const {rect, matrixXYLocatorRange} = chart.convertToLayout(
+ {matrixIndex: 0},
+ [10000, 2],
+ {clamp: 1}
+ );
+ // `rect` is `{x: 20, y: 10, width: 200, height: 100}`.
+ // `matrixXYLocatorRange` is `[[0, 3], [2, 2]]`.
+ ```
+{{ /target }}
diff --git a/en/api/echarts.md b/en/api/echarts.md
index 06cb9ddc6..6676c44dc 100644
--- a/en/api/echarts.md
+++ b/en/api/echarts.md
@@ -103,7 +103,7 @@ Returns chart instance of dom container.
## use(Function)
-> Since `5.0.1`
+{{ use: partial-version(version = "5.0.1") }}
Use components. Used with the new tree-shaking API.
@@ -196,7 +196,7 @@ Please refer to [option.geo](option.html#geo.map) for usage.
+ **@param `opt.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`.
+ Optional. Data in SVG format. Can be a SVG string or a parsed SVG DOM object. See more info in [SVG Base Map](${handbookPath}how-to/component-types/geo/svg-base-map). Introduced in `v5.1.0`.
For example, A minimal SVG:
```ts
@@ -263,6 +263,9 @@ Note:
## registerTheme(Function)
+
+{{ use: partial-version(version = "6.0.0") }}
+
```ts
(themeName: string, theme: Object)
```
@@ -320,7 +323,7 @@ chart.setOption(option);
## registerLocale(Function)
-> Since `5.0.0`
+{{ use: partial-version(version = "5.0.0") }}
```ts
(locale: string, localeCfg: Object)
@@ -330,7 +333,7 @@ Registers a locale, should be specified when [initialize the chart instance](~ec
## setPlatformAPI(Function)
-> Since `5.3.0`
+{{ use: partial-version(version = "5.3.0") }}
```ts
(platformAPI?: {
diff --git a/en/api/events.md b/en/api/events.md
index 398755013..7d3953853 100644
--- a/en/api/events.md
+++ b/en/api/events.md
@@ -202,6 +202,43 @@ Event when trigger legend scroll.
```
+## axisbreakchanged(Event)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+**ACTION:** [expandAxisBreak](~action.axis.expandAxisBreak), [collapseAxisBreak](~action.axis.collapseAxisBreak) and [toggleAxisBreak](~action.axis.toggleAxisBreak) will trigger this event.
+
+```ts
+{
+ type: 'axisbreakchanged';
+ // The type of the action that triggered this event.
+ fromAction: 'expandAxisBreak' | 'collapseAxisBreak' | 'toggleAxisBreak';
+ // The original input action payload.
+ fromActionPayload: Payload;
+ // This breaks array only includes only break items that is specified
+ // in the action, rather than all break items existing in axes.
+ breaks: {
+ // start/end is also the unique identifier of this break item.
+ start: number;
+ end: number;
+
+ // The index of the axis this break item belongs to.
+ xAxisIndex?: number;
+ yAxisIndex?: number;
+ singleAxisIndex?: number;
+
+ // The state after updating.
+ isExpanded: boolean;
+ old: {
+ // The previous state.
+ isExpanded: boolean;
+ };
+ }[]
+}
+```
+
+**Notice:**When using [chart.setOption](~echartsInstance.setOption) to update axis breaks, this event is not triggered. Only actions trigger this event.
+
## datazoom(Event)
**ACTION:** [dataZoom](~action.dataZoom.dataZoom)
@@ -221,6 +258,7 @@ Event emitted after zooming data area.
endValue?: number
}
```
+
## datarangeselected(Event)
**ACTION:** [selectDataRange](~action.dataRange.selectDataRange)
Event emitted after range is changed in visualMap.
diff --git a/en/api/version.md b/en/api/version.md
index 191ddadd7..09dee9a6d 100644
--- a/en/api/version.md
+++ b/en/api/version.md
@@ -1,9 +1,11 @@
{{ target: partial-version }}
+
{{ if: ${deprecated} }}
-> Deprecated since `v${version}`. ${deprecated}
+Deprecated since `v${version}`. ${deprecated}
{{ else }}
-> Since `v${version}`
+Since `v${version}`
{{ /if }}
+
{{ // this line break is necessary for md quote }}
diff --git a/en/option-gl/component/axis3D-axis-common.md b/en/option-gl/component/axis3D-axis-common.md
index 217577e7b..baf4e2260 100644
--- a/en/option-gl/component/axis3D-axis-common.md
+++ b/en/option-gl/component/axis3D-axis-common.md
@@ -52,7 +52,7 @@ In the category axis, it can also be set as the ordinal number. For example, if
The maximum value of the axis.
-It can be set to a special value `'dataMax'` so that the minimum value on this axis is set to be the maximum label.
+It can be set to a special value `'dataMax'` so that the maximum value on this axis is set to be the maximum label.
It will be automatically computed to make sure the axis tick is equally distributed when not set.
diff --git a/en/option-gl/component/axis3D-common.md b/en/option-gl/component/axis3D-common.md
index 6b04d27a4..472d979ad 100644
--- a/en/option-gl/component/axis3D-common.md
+++ b/en/option-gl/component/axis3D-common.md
@@ -82,7 +82,9 @@ The margin between the axis label and the axis line.
{{ /if }}
##${prefix|default('#')} formatter(string|Function) = null
-{{use: axis-common-formatter-desc}}
+{{ use: axis-common-formatter-desc(
+ componentType=${componentType}
+) }}
##${prefix|default('#')} textStyle(Object)
diff --git a/en/option-gl/partial/version.md b/en/option-gl/partial/version.md
index c0ff95323..825ccf4a5 100644
--- a/en/option-gl/partial/version.md
+++ b/en/option-gl/partial/version.md
@@ -1,8 +1,10 @@
{{ target: partial-version }}
+
{{ if: ${deprecated} }}
-> Deprecated since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`. ${deprecated}
+Deprecated since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`. ${deprecated}
{{ else }}
-> Since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`
+Since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`
{{ /if }}
+
diff --git a/en/option/component/axis-common.md b/en/option/component/axis-common.md
index 8642911fa..85c6cc005 100644
--- a/en/option/component/axis-common.md
+++ b/en/option/component/axis-common.md
@@ -25,6 +25,7 @@ Parameters of the event include:
}
```
+{{ if: ${hasJitter|default(false)} }}
#${prefix} jitter(number) = 0
{{ use: partial-version(version = "6.0.0") }}
@@ -46,6 +47,209 @@ Whether allow overlaping with [jitter](~${componentType}.jitter). If `false`, it
{{ use: partial-version(version = "6.0.0") }}
When setting [jitter](~${componentType}.jitter) and [jitterOverlap](~${componentType}.jitterOverlap) is `false`, the minimum distance between two scatters.
+{{ /if }}
+
+
+
+{{ if: ${hasBreakAxis|default(false)} }}
+#${prefix} breaks(Array)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Defines axis breaks. Each entry represents a collapsed or skipped range of the axis.
+
+~[800x400](${galleryViewPath}intraday-breaks-2&edit=1&reset=1)
+~[800x400](${galleryViewPath}intraday-breaks-1&edit=1&reset=1)
+~[800x400](${galleryViewPath}bar-breaks-brush&edit=1&reset=1)
+
+**Other examples:** [bar-breaks-simple](${galleryEditorPath}bar-breaks-simple&edit=1&reset=1), [line-fisheye-lens](${galleryEditorPath}line-fisheye-lens&edit=1&reset=1)
+
+
+> An axis break is a technique that collapses portions of the coordinate axis to compress the display space of non-critical data segments in charts. Its core purposes are:
+>
+> + **Highlight differences**: When there are extreme differences between data values (such as one value being much larger than others), it prevents large value bars from overwhelmingly occupying space, making small value differences difficult to distinguish.
+> + **Save space**: Reduces blank areas caused by extreme values, making charts more compact.
+>
+> Please note that axis breaks should only be used when necessary to avoid misleading users. When using axis breaks, the collapsed parts and corresponding values should usually be clearly indicated.
+>
+> Axis breaks cannot be used in category axes ([type](~${componentType}.type): `'category'`).
+
+
+If you import ECharts by [only importing the necessary components](${handbookPath}basics/import), you need to import and register the feature `AxisBreak` explicitly. For example,
+```ts
+import * as echarts from 'echarts/core';
+import { BarChart } from 'echarts/charts';
+import {
+ TitleComponent,
+ TooltipComponent,
+ GridComponent,
+ DatasetComponent,
+ TransformComponent
+} from 'echarts/components';
+
+// Import the feature AxisBreak
+import { AxisBreak } from 'echarts/features';
+
+import { CanvasRenderer } from 'echarts/renderers';
+
+// Register
+echarts.use([
+ BarChart,
+ TitleComponent,
+ TooltipComponent,
+ GridComponent,
+ DatasetComponent,
+ TransformComponent,
+ AxisBreak,
+ CanvasRenderer
+]);
+
+var myChart = echarts.init(document.getElementById('main'));
+myChart.setOption({
+ // ...
+});
+```
+
+
+##${prefix} start(string|number|Date)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+The start value for the axis break area, specified in data domain defined by `series.data`, rather than in pixels.
+
+{{ use: partial-scale-data-value-desc(
+ componentType = ${componentType},
+ notSupportCategory = true
+) }}
+
+{{ use: partial-axis-break-identifier-desc(
+ componentType = ${componentType}
+)}}
+
+##${prefix} end(string|number|Date)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+The end value for the axis break area, specified in data domain defined by `series.data`, rather than in pixels.
+
+{{ use: partial-scale-data-value-desc(
+ componentType = ${componentType},
+ notSupportCategory = true
+) }}
+
+{{ use: partial-axis-break-identifier-desc(
+ componentType = ${componentType}
+)}}
+
+##${prefix} gap(number|string)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+It determines the visual size of the axis break area.
+
++ Percentage (string):
+
+ Specifies the proportion relative to the axis. For example, `'5%'` means that the final size of the axis break area will always be `'5%'` of the axis length. Using a percentage ensures that the pixel size of the axis break area remains stable, and does not change when [${componentType}.min](~${componentType}.min), [${componentType}.max](~${componentType}.max), or [dataZoom](~dataZoom) are modified. For this reason, using a percentage is recommended in most scenarios.
++ Absolute value:
+
+ Its unit is the same as [start](~${componentType}.breaks.start) and [end](~${componentType}.breaks.end), referring to a value in the data domain defined by the business data (`series.data`), rather than pixels. It represents mapping (replacing) the `[start, end]` interval with `[start, start + gap]`. Therefore, if set as an absolute value, the pixel size of the axis break area will change when [${componentType}.min](~${componentType}.min), [${componentType}.max](~${componentType}.max), or [dataZoom](~dataZoom) are modified.
+
+**Notice:** Within a [${componentType}.breaks](~${componentType}.breaks) array, `gap` must be specified either entirely in percentages or entirely in absolute values. Mixing the two is not allowed, as it may lead to unexpected results.
+
+{{ use: partial-axis-break-identifier-desc(
+ componentType = ${componentType}
+)}}
+
+##${prefix} isExpanded(boolean) = false
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Whether this axis break area is expanded, default is `false`.
+
+{{ use: partial-axis-break-identifier-desc(
+ componentType = ${componentType}
+)}}
+
+#${prefix} breakArea
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Style of the axis break area.
+
+See also the introduction to the axis break in [${componentType}.breaks](~${componentType}breaks).
+
+##${prefix} show(boolean) = true
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Whether to show the axis break area.
+
+##${prefix} itemStyle
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Style of the axis break area.
+
+{{ use: partial-item-style(
+ prefix = '###',
+ defaultColor = "#fff",
+ defaultBorderColor = "'#b7b9be'",
+ defaultBorderWidth = 1,
+ defaultType = "[3, 3]",
+ defaultOpacity = 0.6
+) }}
+
+##${prefix} zigzagAmplitude(number) = 4
+
+{{ use: partial-version(version = "6.0.0") }}
+
+The amplitude (in the direction perpendicular to the coordinate axis) of the zigzag. The size of different teeth is always the same. The unit is pixel. If set to `0`, the zigzag degenerates into a straight line.
+
+##${prefix} zigzagMinSpan(number) = 4
+
+{{ use: partial-version(version = "6.0.0") }}
+
+The minimum size of each tooth. The unit is pixel.
+
+> The size of a tooth is a random number between `zigzagMinSpan` and `zigzagMaxSpan`. Randomness is used to simulate the effect of torn paper.
+
+##${prefix} zigzagMaxSpan(number) = 20
+
+{{ use: partial-version(version = "6.0.0") }}
+
+The maximum size of each tooth. The unit is pixel.
+
+> The size of a tooth is a random number between `zigzagMinSpan` and `zigzagMaxSpan`. Randomness is used to simulate the effect of torn paper.
+
+##${prefix} zigzagZ(number) = 100
+
+{{ use: partial-version(version = "6.0.0") }}
+
+The `z` value of the zigzag. Controls the front-to-back order of graphics. Graphics with smaller `z` values will be covered by graphics with larger `z` values.
+
+##${prefix} expandOnClick(boolean) = true
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Whether to expand the axis break area when clicking on it.
+
+#${prefix} breakLabelLayout(Object)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Axis breaks label layout.
+
+See also the introduction to the axis break in [${componentType}.breaks](~${componentType}breaks).
+
+
+##${prefix} moveOverlap(string|boolean) = 'auto'
+
+{{ use: partial-version(version = "6.0.0") }}
+
+When axis break labels overlap, whether to move labels to avoid overlap.
+
+`'auto'` or `true` means moving labels to avoid overlap when overlapping occurs; `false` means not moving.
+{{ /if }}
#${prefix} axisLine(Object)
@@ -155,7 +359,10 @@ The margin between the axis label and the axis line.
##${prefix} formatter(string|Function) = null
-{{ use: axis-common-formatter-desc() }}
+{{ use: axis-common-formatter-desc(
+ componentType = ${componentType},
+ supportAxisBreak = true
+) }}
##${prefix} showMinLabel(boolean) = null
@@ -710,7 +917,7 @@ min: function (value) {
The maximum value of axis.
-It can be set to a special value `'dataMax'` so that the minimum value on this axis is set to be the maximum label.
+It can be set to a special value `'dataMax'` so that the maximum value on this axis is set to be the maximum label.
It will be automatically computed to make sure axis tick is equally distributed when not set.
@@ -803,7 +1010,9 @@ To specify the start value of the axis.
{{ use: partial-axis-common-axis-line(
prefix = ${prefix},
- componentType = ${componentType}
+ componentType = ${componentType},
+ hasJitter = ${hasJitter},
+ hasBreakAxis = ${hasBreakAxis}
) }}
{{ use: partial-axis-common-axis-tick(
@@ -917,6 +1126,10 @@ The first parameter is index of category, and the second parameter is the name o
{{ target: axis-common-formatter-desc }}
+{{ if: !${axisTypeProp} }}
+{{ var: axisTypeProp = 'type' }}
+{{ /if }}
+
Formatter of axis label, which supports string template and callback function.
Example:
@@ -924,15 +1137,48 @@ Example:
// Use string template; template variable is the default label of axis {value}
formatter: '{value} kg'
// Use callback.
-formatter: function (value, index) {
+formatter: function (value, index, extra?) {
return value + 'kg';
}
```
---
-For axes of time [type](~${componentType}.type): `'time'`, `formatter` supports the following forms:
+
+
+{{ if: ${supportAxisBreak} }}
+**When [axis break](${componentType}.breaks) is used**
+
+The break info can be obtained from the `extra` param:
+```ts
+type AxisLabelFormatterExtraBreakPart = {
+ // If this label is a axis break start or end.
+ break?: {
+ type: 'start' | 'end';
+ // The parsed `start`/`end`, always be numbers, and has been
+ // sorted and intersection removed, therefore, they may not
+ // equal to the original input of `start`/`end`.
+ start: number;
+ end: number;
+ }
+}
+formatter = function (value, index, extra: AxisLabelFormatterExtraBreakPart) {
+ if (extra && extra.break) {
+ console.log(extra.break);
+ }
+ return value + 'kg';
+}
+```
+Notice: null checking must be performed.
+{{ /if }}
+---
+
+
+
+**For a time axis ([`${componentType}.${axisTypeProp}: 'time'`](~${componentType}.${axisTypeProp}))**
+
+`formatter` supports the following forms:
- **String Templates**: an easy and fast way to make frequently used date/time template, formed in `string`
- **Callback Functions**: customized formatter to make complex format, formed in `Function`
- **Cascading Templates**: to adopt different formatters for different time granularity, formed in `object`
@@ -994,6 +1240,17 @@ formatter: function (value, index) {
}
return texts.join('/');
}
+
+// Moreover, `echarts.time.format` can be used:
+formatter: function (value, index) {
+ // Follow the template rules above.
+ const timeStrLocal = echarts.time.format(value, '{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}');
+ // The third param `true` indicates that format time based on UTC.
+ const timeStrUTC = echarts.time.format(value, '{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}', true);
+ // Notice, if using UTC, ${optionDocPath}#useUTC need to be also set as `true`
+ // for consistency.
+ return timeStrLocal;
+}
```
** Cascading Templates **
@@ -1111,3 +1368,25 @@ Whether to show the tooltip. Defaults to `false`.
) }}
+
+{{ target: partial-scale-data-value-desc }}
+
+- If [axis.type](~${componentType}.type) is `'value'` or `'log'`, use `number` type values.
+{{ if: ${notSupportCategory} }}
+- If [axis.type](~${componentType}.type) is `'category'`: not supported yet.
+{{ else }}
+- If [axis.type](~${componentType}.type) is `'category'`, the value can be:
+ - The original string, such as `'categoryA'`, `'categoryB'`.
+ - The ordinal number. For example, if a catergory axis is defined as `data: ['categoryA', 'categoryB', 'categoryC']`, and the ordinal `2` represents `'categoryC'` (starting from `0`). Moreover, it can be set as negative number, like `-3`.
+{{ /if }}
+- If [axis.type](~${componentType}.type) is `'time'`, the value can be:
+ - `string` type represents any time format that can be parsed by [method `parseDate` in `echarts/src/util/number.ts`](https://github.com/apache/echarts/blob/master/src/util/number.ts), e.g., `'2024-04-09 13:00:00'`.
+ - `number` type represents a timestamp, e.g., `1712667600000`.
+ - `Date` type time objects, e.g., `new Date('2024-04-09T13:00:00Z')`.
+
+
+
+{{ target: partial-axis-break-identifier-desc }}
+
+Note: [${componentType}.breaks.start](~${componentType}.breaks.start) and [${componentType}.breaks.end](~${componentType}.breaks.end) are the unique identifiers for each break item. When calling [chart.setOption](api.html#echartsInstance.setOption) to modify [${componentType}.breaks.gap](~${componentType}.breaks.gap) or [${componentType}.breaks.isExpanded](~${componentType}.breaks.isExpanded), `start` and `end` must be specified. Update animations will only occur if `start` and `end` are not modified; no animation will occur if they are changed.
+
diff --git a/en/option/component/geo-common.md b/en/option/component/geo-common.md
index 5337e181c..c2b1c8f93 100644
--- a/en/option/component/geo-common.md
+++ b/en/option/component/geo-common.md
@@ -85,7 +85,7 @@ $.get('map/topographic_map.svg', function (svg) {
See also [Flight Seatmap](${galleryEditorPath}geo-seatmap-flight).
{{ /if }}
-The demo above shows that SVG format can be used in ECharts. See more info in [SVG Base Map](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20Series).
+The demo above shows that SVG format can be used in ECharts. See more info in [SVG Base Map](${handbookPath}how-to/component-types/geo/svg-base-map).
#${prefix} projection(Object)
diff --git a/en/option/component/matrix.md b/en/option/component/matrix.md
index 418fa205e..1a2babc35 100644
--- a/en/option/component/matrix.md
+++ b/en/option/component/matrix.md
@@ -8,7 +8,7 @@ Matrix coordinate system component.
The `matrix` coordinate system, like a table, can serve as the layout system of data items in a series, mainly used to display the relationship and interaction of multi-dimensional data. It presents data in the form of a rectangular grid, where each grid unit (or "cell") represents the value of a specific data point in series like `series.heatmap`, `series.scatter`, `series.custom`, etc. The entire layout is displayed in rows and columns to express the relationship of two-dimensional or higher-dimensional data.
-The `matrix` coordinate system can also serve as the layout system of the box of series like `series.pie`, `series.tree`, etc., or another coordinate systems like `grid` (i.e., Cartesian coordinate system), `geo`, `polar`, etc., or plain components like `legend`, `dataZoom`, etc. This character enables tiny charts to be laid out in a table, or enables the layout approach like [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout). Currently all the series and components can be laid out within a matrix. `matrix` can also be used purely as table for data texts.
+The `matrix` coordinate system can also serve as the layout system of the box of series like `series.pie`, `series.tree`, etc., or another coordinate systems like `grid` (i.e., Cartesian coordinate system), `geo`, `polar`, etc., or plain components like `legend`, `dataZoom`, etc. This character enables [mini charts](${galleryEditorPath}matrix-sparkline&edit=1&reset=1) to be laid out in a table, or enables the layout approach like [CSS grid layout](${galleryEditorPath}matrix-grid-layout&edit=1&reset=1). Currently all the series and components can be laid out within a matrix. `matrix` can also be used purely as table for data texts.
Correlation heat map using heat map in matrix coordinate system:
~[800x400](${galleryViewPath}matrix-correlation-heatmap&edit=1&reset=1)
@@ -25,8 +25,12 @@ Correlation pie chart using pie chart in matrix coordinate system. The example b
Confusion matrix using custom series in matrix coordinate system:
~[800x400](${galleryViewPath}matrix-confusion&edit=1&reset=1)
-Tiny line charts are laid out in a table:
-~[800x600](${galleryViewPath}matrix-cartesian-tiny&edit=1&reset=1)
+Mini charts are laid out in a table:
+~[800x600](${galleryViewPath}matrix-sparkline&edit=1&reset=1)
+~[800x600](${galleryViewPath}matrix-mini-bar-geo&edit=1&reset=1)
+
+And other **mini charts** examples: [matrix mini bar example](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1).
+
By flexibly using the combination of chart series, coordinate systems, and APIs, richer effects can be achieved.
@@ -52,7 +56,7 @@ X-axis header region.
{{ use: partial-matrix-header(
name = 'x-axis cells',
- prefix = '##'
+ matrixDim = 'x',
) }}
## y(Object)
@@ -63,7 +67,7 @@ Y-axis header region.
{{ use: partial-matrix-header(
name = 'y-axis cells',
- prefix = '##'
+ matrixDim = 'y',
) }}
## body(Object)
diff --git a/en/option/component/thumbnail.md b/en/option/component/thumbnail.md
new file mode 100644
index 000000000..dd210ff22
--- /dev/null
+++ b/en/option/component/thumbnail.md
@@ -0,0 +1,76 @@
+{{ target: component-thumbnail }}
+
+# thumbnail(Object)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Thumbnail component.
+
+Currently it only supports [series.graph](~series-graph).
+
+Examples: [graph NPM](${galleryEditorPath}graph-npm&edit=1&reset=1), [graph Webkit dep](${galleryEditorPath}graph-webkit-dep&edit=1&reset=1).
+
+
+{{ use: partial-component-id(
+ prefix = "#"
+) }}
+
+## show(boolean) = true
+
+Whether to display the thumbnail component.
+
+{{ use: partial-rect-layout-width-height(
+ componentName = "thumbnail",
+ defaultLeft = "25%",
+ defaultTop = "25%"
+) }}
+
+{{ use: partial-coord-sys(
+ version = '6.0.0',
+ nonSeriesComponentMainType = "thumbnail",
+ coordSysDefault = "'none'",
+ matrix = true,
+ calendar = true,
+ none = true
+) }}
+
+## itemStyle(Object)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+The style of the box and background of the thumbnail.
+
+{{ use: partial-item-style(
+ prefix = '##',
+ defaultBorderColor = "'#b7b9be'",
+ defaultBorderWidth = 2
+) }}
+
+## windowStyle(Object)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+The style of the window of the thumbnail.
+
+{{ use: partial-item-style(
+ prefix = '##',
+ defaultColor = "'#9ea0a5'",
+ defaultBorderColor = "'#b7b9be'",
+ defaultBorderWidth = 1,
+ defaultOpacity = 0.3
+) }}
+
+## seriesIndex(number)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Specify which series this thumbnail is for. Use the first [series.graph](~series-graph) by default.
+
+## seriesId(string|number)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Specify which series this thumbnail is for. Use the first [series.graph](~series-graph) by default.
+
+
+{{ /target }}
diff --git a/en/option/component/timeline.md b/en/option/component/timeline.md
index 8116e97cd..4d3dfaeba 100644
--- a/en/option/component/timeline.md
+++ b/en/option/component/timeline.md
@@ -527,7 +527,10 @@ Rotation angle of `label`, in which positive values refer to counter clockwise r
#${prefix} formatter(string|Function) = null
-{{ use: axis-common-formatter-desc() }}
+{{ use: axis-common-formatter-desc(
+ componentType = ${componentType},
+ axisTypeProp = 'axisType'
+) }}
{{ if: ${state} }}
{{ use: partial-text-style(
diff --git a/en/option/component/tooltip.md b/en/option/component/tooltip.md
index 2b3c261ba..3dc500d48 100644
--- a/en/option/component/tooltip.md
+++ b/en/option/component/tooltip.md
@@ -250,6 +250,18 @@ className: 'echarts-tooltip echarts-tooltip-dark'
The transition duration of tooltip's animation, in seconds. When it is set to be 0, it would move closely with the mouse.
+## displayTransition(boolean) = true
+
+
+
+{{ use: partial-version(
+ version = "6.0.0"
+) }}
+
+Whether to enable the display transition.
+
+By default, the tooltip uses the opacity fading to make itself invisible rather than setting the DOM element's `display` property to `'none'`. This might cause the scrollbar to be always visible when the tooltip content size is large, even if the tooltip is already invisible. In this scenario, or if you just want no fading, you can set this option to `false` to disable the display transition.
+
{{ use: partial-tooltip-common(
scope = 'global',
prefix = '#'
diff --git a/en/option/component/x-axis.md b/en/option/component/x-axis.md
index 3df7d353d..ec958710c 100644
--- a/en/option/component/x-axis.md
+++ b/en/option/component/x-axis.md
@@ -37,21 +37,23 @@ options:
+ `'top'`
+ `'bottom'`
-The first x axis in grid defaults to be on the bottom of the grid, and the second x axis is on the other side against the first x axis.
+The first x axis in grid defaults to be on the bottom of the grid, and the second x axis is on the other side against the first x axis.
Notice: Set `xAxis.axisLine.onZero` to `false` to activate this option.
## offset(number) = 0
-Offset of x axis relative to default position. Useful when multiple x axis has same [position](~xAxis.position) value.
+Offset of x axis relative to default position. Useful when multiple x axis has same [position](~xAxis.position) value.
Notice: Set `xAxis.axisLine.onZero` to `false` to activate this option.
{{ use: axis-common(
prefix = '#',
componentType = 'xAxis',
axisTypeDefault = "'category'",
- hasSplitLineAndArea = true
+ hasSplitLineAndArea = true,
+ hasJitter = true,
+ hasBreakAxis = true
) }}
{{ use: partial-z-zlevel(
diff --git a/en/option/component/y-axis.md b/en/option/component/y-axis.md
index 906774219..11e6a5e84 100644
--- a/en/option/component/y-axis.md
+++ b/en/option/component/y-axis.md
@@ -37,7 +37,7 @@ options:
+ `'left'`
+ `'right'`
-The first y axis in grid defaults to be the left (`'left'`) of the grid, and the second y axis is on the other side against the first y axis.
+The first y axis in grid defaults to be the left (`'left'`) of the grid, and the second y axis is on the other side against the first y axis.
Notice: Set `yAxis.axisLine.onZero` to `false` to activate this option.
## offset(number) = 0
@@ -51,7 +51,9 @@ Notice: Set `yAxis.axisLine.onZero` to `false` to activate this option.
prefix = '#',
componentType = 'yAxis',
axisTypeDefault = "'value'",
- hasSplitLineAndArea = true
+ hasSplitLineAndArea = true,
+ hasJitter = true,
+ hasBreakAxis = true
) }}
{{ use: partial-z-zlevel(
diff --git a/en/option/option.md b/en/option/option.md
index 64f11bfea..f90b7fd2a 100644
--- a/en/option/option.md
+++ b/en/option/option.md
@@ -23,6 +23,7 @@
{{import: component-graphic}}
{{import: component-calendar}}
{{import: component-matrix}}
+{{import: component-thumbnail}}
{{import: component-dataset}}
{{import: component-aria}}
@@ -163,6 +164,11 @@ 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).
+Notice: if you set `useUTC: true` and use the helper method `echarts.time.format` (or other similar third-party methods), it should also be configured to format in UTC. For example,
+```ts
+// The third param `true` indicates that format time based on UTC.
+const timeStrUTC = echarts.time.format(value, '{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}', true);
+```
{{import: partial-rich-inherit-plain-label}}
diff --git a/en/option/partial/coord-sys.md b/en/option/partial/coord-sys.md
index 4efbf8d75..c7fabb170 100644
--- a/en/option/partial/coord-sys.md
+++ b/en/option/partial/coord-sys.md
@@ -91,7 +91,7 @@ Options:
Lay out based on a [matrix coordinate system](~matrix). When multiple matrix coordinate systems exist within an ECharts instance, the corresponding system should be specified using [matrixIndex](~${componentNameInLink}.matrixIndex) or [matrixId](~${componentNameInLink}.matrixId).{{if: ${nonSeriesComponentMainType} === 'grid' }}
- See example [tiny Cartesians in matrix](${galleryEditorPath}matrix-cartesian-tiny&edit=1&reset=1).
+ See example [sparkline in matrix](${galleryEditorPath}matrix-sparkline&edit=1&reset=1).
{{ /if }}
{{ /if }}
@@ -158,7 +158,7 @@ Options:
The entire series or component is laid out as a whole based on the specified coordinate system - that is, the overall bounding rect or basic anchor point is calculated relative to the system.
- - For example, a [grid component](~grid) can be laid out in a [matrix coordinate system](~matrix) or a [calendar coordinate system](~calendar), where its layout rectangle is calculated by the specified [${componentNameInLink}.coords](~${componentNameInLink}.coords) in that system. See example [tiny Cartesians in matrix](${galleryEditorPath}matrix-cartesian-tiny&edit=1&reset=1).
+ - For example, a [grid component](~grid) can be laid out in a [matrix coordinate system](~matrix) or a [calendar coordinate system](~calendar), where its layout rectangle is calculated by the specified [${componentNameInLink}.coords](~${componentNameInLink}.coords) in that system. See example [sparkline in matrix](${galleryEditorPath}matrix-sparkline&edit=1&reset=1).
- For example, a [pie series](~series-pie) or a [chord series](~series-chord) can be laid out in a [geo coordinate system](~geo) or a [cartesian2d coordinate system](~grid), where the center is calculated by the specified [series-pie.coords](~series-pie.coords) or [series-pie.center](~series-pie.center) in that system. See example [pie in geo](${galleryEditorPath}map-iceland-pie&edit=1&reset=1).
{{ if: ${seriesType} }}
@@ -169,13 +169,13 @@ Most series only support `coordinateSystemUsage: 'data'` - such as [series-line]
See also [${componentNameInLink}.coordinateSystem](~${componentNameInLink}.coordinateSystem).
-## coord(Array|string)
+## coord(Array|number|string)
{{ use: partial-version(version = ${version|minVersion('6.0.0')}) }}
When [coordinateSystemUsage](~${componentNameInLink}.coordinateSystemUsage) is `'box'`, `coord` is used as the input to the coordinate system and calculate the layout rectangle or anchor point.
-Examples: [tiny Cartesians in matrix](${galleryEditorPath}matrix-cartesian-tiny&edit=1&reset=1), [grpah in matrix](${galleryEditorPath}doc-example/matrix-graph-box&edit=1&reset=1).
+Examples: [sparkline in matrix](${galleryEditorPath}matrix-sparkline&edit=1&reset=1), [grpah in matrix](${galleryEditorPath}doc-example/matrix-graph-box&edit=1&reset=1).
{{ if: ${seriesType} === 'pie' }}
[series-pie.center](~series-pie.center) and [series-pie.coord](~series-pie.coord) can be used interchangably in this case.
@@ -185,6 +185,8 @@ Examples: [tiny Cartesians in matrix](${galleryEditorPath}matrix-cartesian-tiny&
> Note: when [coordinateSystemUsage](~${componentNameInLink}.coordinateSystemUsage) is `'data'`, the input of coordinate system is `series.data[i]` rather than this `coord`.
+The format this `coord` is defined by each coordinate system, and it's the same as the second parameter of [chart.convertToPixel](api.html#echartsInstance.convertToPixel).
+
{{ if: ${cartesian2d} }}
## xAxisIndex(number) = 0
diff --git a/en/option/partial/matrix-header.md b/en/option/partial/matrix-header.md
index ac5dc1d95..cc1aeed29 100644
--- a/en/option/partial/matrix-header.md
+++ b/en/option/partial/matrix-header.md
@@ -19,6 +19,8 @@ data: ['A', 'B', 'C', 'D', 'E']
// Or if column/row names is not of concern, simply
data: Array(5).fill(null) // Five columns or rows
+// Note: DO NOT support array with empty slots：
+// data: Array(5) // ❌
// Data in a tree structure
data: [{
@@ -42,13 +44,37 @@ data: [{
}]
```
+If [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is not provided, it will be collected from `series.data` or `dataset.soruce`.
+
+See [matrix data collection example](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1).
+
+And in this case [series.encode](~series-scatter.encode) can be used to specify the dimension from which value is collected. For example,
+```js
+var option = {
+ // no matrix.x/y.data is specified;
+ // so collect from series.data or dataset.source (if any)
+ matrix: {},
+ series: {
+ type: 'scatter',
+ coordinateSystem: 'matrix',
+ // Collect values from dimension index 3 and 2.
+ encode: {x: 3, y: 2},
+ data: [
+ // 0 1 2 3 (dimension index)
+ [100, 111, 122, 133],
+ [200, 211, 222, 233],
+ ]
+ }
+}
+```
+
#### value(string|number)
{{ use: partial-version(version = "6.0.0") }}
The text in the header cell. Can also be used as a index of this column or row. Optional. If not specified, auto generate a text.
#### children(Array)
{{ use: partial-version(version = "6.0.0") }}
-See [matrix.x/y.data](~matrix.x.data).
+See [matrix.${matrixDim}.data](~matrix.${matrixDim}.data).
#### size(number)
{{ use: partial-version(version = "6.0.0") }}
diff --git a/en/option/partial/version.md b/en/option/partial/version.md
index ab87c8c82..60974bb52 100644
--- a/en/option/partial/version.md
+++ b/en/option/partial/version.md
@@ -1,9 +1,11 @@
{{ target: partial-version }}
+
{{ if: ${deprecated} }}
-> Deprecated since `v${version}`. ${deprecated}
+Deprecated since `v${version}`. ${deprecated}
{{ else }}
-> Since `v${version}`
+Since `v${version}`
{{ /if }}
+
diff --git a/en/option/partial/view-coord-sys.md b/en/option/partial/view-coord-sys.md
index 99bdbf500..f1984c22e 100644
--- a/en/option/partial/view-coord-sys.md
+++ b/en/option/partial/view-coord-sys.md
@@ -90,6 +90,9 @@ center: ['50%', '50%']
> The percentage string is introduced since `v5.3.3`. It is initially based on canvas width/height. But that is not reasonable, and then changed to be based on the bounding rect since `v6.0.0`.
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
#${prefix} zoom(number) = 1
@@ -103,6 +106,10 @@ Zoom rate of current viewport.
When [roaming](~${componentNameInLink}.roam), the values in [center](~${componentNameInLink}.center) and `zoom` will be modified correspondingly.
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
+
#${prefix} scaleLimit(Object)
{{ use: partial-scale-limit-desc(
@@ -131,9 +138,11 @@ Options:
{{ if: ${supportClip} }}If `clip: true`, the roaming can only be triggered at any position within the clipped area. Otherwise it can be triggered in canvas globally.{{ else }}The roaming can be triggered in canvas globally.{{ /if }}
-{{ if: ${isGeoOrMap} }}
-**See example:** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
-{{ /if }}
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
{{ target: partial-preserve-aspect }}
@@ -166,10 +175,12 @@ Options of `preserveAspect`:
{{ if: ${isGeoOrMap} }}
Notice: When using [layoutCenter](~${componentNameInLink}.layoutCenter) and [layoutSize](~${componentNameInLink}.layoutSize), the `aspect radio` is always preserved, regardless of this `preserveAspect`.
-
-**See example:** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
{{ /if }}
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
+
#${prefix} preserveAspectAlign(string) = 'center'
@@ -180,7 +191,9 @@ Options: `'left'` | `'right'` | `'center'`.
See [preserveAspect](~${componentNameInLink}.preserveAspect).
-See example [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
#${prefix} preserveAspectVerticalAlign(string) = 'middle'
@@ -192,7 +205,19 @@ Options: `'top'` | `'bottom'` | `'middle'`.
See [preserveAspect](~${componentNameInLink}.preserveAspect).
-See example [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
+
+{{ target: partial-view-coord-sys-indicator-example-link }}
+
+{{ if: ${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map' }}
+**See [geo roam indicator example](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1)** to understand the concept.
+{{ elif: ${componentNameInLink} === 'series-graph' }}
+**See [graph roam indicator example](${galleryEditorPath}doc-example/graph-roam-indicator&edit=1&reset=1)** to understand the concept.
+{{ /if }}
diff --git a/en/option/series/bar.md b/en/option/series/bar.md
index e19ad1615..5d17c9b0c 100644
--- a/en/option/series/bar.md
+++ b/en/option/series/bar.md
@@ -166,6 +166,8 @@ Stack order. Optional values:
+ `'seriesAsc'` (default, stack in series order)
+ `'seriesDesc'` (reverse stack order)
+**Note:** `stackOrder` should be defined for all series with the same `stack` name. If `stackOrder` is defined for only some of the series, the stack order may change unexpectedly when certain series are hidden (e.g., through legend toggle).
+
Not supported in polar coordinate system.
## sampling(string)
diff --git a/en/option/series/custom.md b/en/option/series/custom.md
index d9fbfa91c..2e78e1dee 100644
--- a/en/option/series/custom.md
+++ b/en/option/series/custom.md
@@ -147,10 +147,10 @@ The first parameter of `renderItem`, including:
},
coordSys: {
type: 'calendar',
- x: // {number} x of calendar rect
- y: // {number} y of calendar rect
- width: // {number} width of calendar rect
- height: // {number} height of calendar rect
+ x: // {number} x of the calendar component rect
+ y: // {number} y of the calendar component rect
+ width: // {number} width of the calendar component rect
+ height: // {number} height of the calendar component rect
cellWidth: // {number} calendar cellWidth
cellHeight: // {number} calendar cellHeight
rangeInfo: {
@@ -160,6 +160,13 @@ The first parameter of `renderItem`, including:
dayCount: // day count in calendar.
}
},
+ coordSys: {
+ type: 'matrix',
+ x: // {number} x of the matrix component rect
+ y: // {number} y of the matrix component rect
+ width: // {number} width of the matrix component rect
+ height: // {number} height of the matrix component rect
+ },
coordSys: {
type: 'geo',
x: // {number} x of geo rect
@@ -207,12 +214,17 @@ Get value on the given dimension.
Convert data to coordinate.
-```
-@param {Array.} data.
-@return {Array.} Point on canvas, at least includes [x, y].
- In polar, it also contains:
- polar: [x, y, radius, angle]
-```
+The behavior, parameters and returns are the same as [chart.convertToPixel](api.html#echartsInstance.convertToPixel) (only exclude its first parameter `finder`).
+
+##### layout(Function)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Convert data to the corresponding layout info based on the current coordinate system.
+
+The behavior, parameters and returns are the same as [chart.convertToLayout](api.html#echartsInstance.convertToLayout) (only exclude its first parameter `finder`).
+
+See [matrix api.layout example](${galleryEditorPath}matrix-mini-bar-data-collection).
##### size(Function)
diff --git a/en/option/series/line.md b/en/option/series/line.md
index 2d3531634..82e9ae54b 100644
--- a/en/option/series/line.md
+++ b/en/option/series/line.md
@@ -92,6 +92,8 @@ Stack order. Optional values:
+ `'seriesAsc'` (default, stack in series order)
+ `'seriesDesc'` (reverse stack order)
+**Note:** `stackOrder` should be defined for all series with the same `stack` name. If `stackOrder` is defined for only some of the series, the stack order may change unexpectedly when certain series are hidden (e.g., through legend toggle).
+
Not supported in polar coordinate system.
{{ use: partial-cursor() }}
diff --git a/en/tutorial/media-query.md b/en/tutorial/media-query.md
index 6d5da12d0..4e3b6faae 100644
--- a/en/tutorial/media-query.md
+++ b/en/tutorial/media-query.md
@@ -10,7 +10,7 @@ Besides, sometimes one chart may need to be displayed on both PC and mobile-end,
To solve this problem, ECharts improved component location algorithm, and implemented responsive ability similar to [CSS Media Query](https://www.w3.org/TR/css3-mediaqueries/).
-## Location and layout of ECharts components
+## Location and Layout of ECharts Components
Most *component* and *series* follow two locating methods:
@@ -212,7 +212,11 @@ But if the container DOM node needs to change size with dragging, you need to pa
When `chart.setOption(rawOption)` for the second, third, fourth, fifth, and etc. times, if `rawOption` is `composite option` (which means it contains `media` list), then, the new `rawOption.media` list will not merge with the old `media`. instead, it will simply replace the option. Of course, `baseOption` will still merge with the old option normally.
-
-Finally, let's see an example combining with timeline:
-~[750x700](${galleryViewPath}doc-example/bar-media-timeline&edit=1&reset=1)
+## Some Examples
+
+Use [matrix coordinate system (grid layout)](option.html#matrix) and media query:
+
+~[750x500](${galleryViewPath}matrix-grid-layout&edit=1&reset=1)
+
+This is another [media query example](${galleryEditorPath}doc-example/bar-media-timeline&edit=1&reset=1).
diff --git a/src/style/mixin.scss b/src/style/mixin.scss
index 664a87954..9dc0917f0 100644
--- a/src/style/mixin.scss
+++ b/src/style/mixin.scss
@@ -11,21 +11,18 @@
}
blockquote {
- font-size: 12px;
- color: #999;
- background-color: #fdfdfd;
+ background-color: #f3f3f3;
border-left: 2px solid #ddd;
margin-left: 0px;
- padding: 5px 10px;
+ padding: 10px 20px;
p {
- margin: 0;
- font-size: 12px;
+ font-size: 13px;
}
-
pre {
- font-size: 12px;
+ font-size: 13px;
+ background-color: #fff;
}
}
@@ -84,4 +81,16 @@
a {
font-family: 'Source Code Pro', STHeiti, "Microsoft Yahei", "WenQuanYi Micro Hei", sans-serif;
}
+
+ .doc-partial-version {
+ font-size: 12px;
+ background: #f3f3f3;
+ margin: 10px 20px 10px 0;
+ padding: 10px;
+ border-left: 2px solid #ddd;
+
+ code {
+ color: #0086b3;
+ }
+ }
}
diff --git a/zh/api/action.md b/zh/api/action.md
index fb802b251..85f729d40 100644
--- a/zh/api/action.md
+++ b/zh/api/action.md
@@ -28,6 +28,38 @@
name?: string,{{/target}}
+{{ target: action-axis-break-expand-collapse-common }}
+不能用于创建新的 axis break 。
+```ts
+dispatchAction({
+ type: '${actionType}',
+
+ // 坐标轴可以用 index、id 或 name 来检索到。
+ xAxisIndex?: 'all' | number;
+ xAxisId?: string | number;
+ xAxisName?: string;
+ yAxisIndex?: 'all' | number;
+ yAxisId?: string | number;
+ yAxisName?: string;
+ singleAxisIndex?: 'all' | number;
+ singleAxisId?: string | number;
+ singleAxisName?: number;
+
+ breaks: {
+ // 使用 start/end 来定位要更改的 break 项。
+ // 更多信息参见文档：${optionDocPath}#xAxis.breaks.start
+ start: string | number | Date,
+ end: string | number | Date,
+ }
+})
+```
+
+继而事件 [axisbreakchanged](~events.axisbreakchanged) 会被派发。
+
+也参见 [axis break isExpanded](option.html#xAxis.breaks.isExpanded)。
+{{/target}}
+
+
{{ target: action }}
# action
@@ -126,6 +158,39 @@ dispatchAction({
```
+## axis
+
+### expandAxisBreak
+
+{{ use: partial-version(version = "6.0.0") }}
+
+展开一个或多个已存在的 axis break 项。不能用于创建新的 axis break 。
+
+{{ use: action-axis-break-expand-collapse-common(
+ actionType = "expandAxisBreak"
+) }}
+
+### collapseAxisBreak
+
+{{ use: partial-version(version = "6.0.0") }}
+
+折叠一个或多个已存在的 axis break 项。不能用于创建新的 axis break 。
+
+{{ use: action-axis-break-expand-collapse-common(
+ actionType = "collapseAxisBreak"
+) }}
+
+### toggleAxisBreak
+
+{{ use: partial-version(version = "6.0.0") }}
+
+切换（展开/折叠）一个或多个已存在的 axis break 项。不能用于创建新的 axis break 。
+
+{{ use: action-axis-break-expand-collapse-common(
+ actionType = "toggleAxisBreak"
+) }}
+
+
## legend
[图例组件](option.html#legend)相关的行为，必须引入[图例组件](option.html#legend)后才能使用。
diff --git a/zh/api/echarts-instance.md b/zh/api/echarts-instance.md
index c1a60d4d5..af640b24c 100644
--- a/zh/api/echarts-instance.md
+++ b/zh/api/echarts-instance.md
@@ -238,12 +238,14 @@ myChart.setOption({
## setTheme(Function)
+{{ use: partial-version(version = "6.0.0") }}
+
```ts
(
-theme: string | Object
-opts?: {
- silent? boolean
-}
+ theme: string | Object,
+ opts?: {
+ silent?: boolean
+ }
) => void
```
@@ -254,17 +256,51 @@ opts?: {
以下是一个动态设置主题的例子：
+方式 1：注册一个具名主题，可以被多个 chart 实例使用。
+```js
+echarts.registerTheme('myTheme', { backgroundColor: 'red' });
+const chart1 = echarts.init(mainDOMElement1);
+chart1.setTheme('myTheme');
+chart1.setOption(...);
+const chart2 = echarts.init(mainDOMElement2);
+chart2.setTheme('myTheme');
+chart2.setOption(...);
+```
+
+方式 2：注册一个匿名主题，只被当前 chart 实例使用。
```js
-const chart = echarts.init(...);
-chart.setOption(...);
-// 图表已经初始化了，也可以调用 registerTheme 和 setTheme
-echarts.registerTheme('myTheme', {backgroundColor: 'red'});
-chart.setTheme('myTheme');
-// 或者直接
-chart.setTheme({backgroundColor: 'red'});
+const chart1 = echarts.init(mainDOMElement);
+chart1.setTheme({ backgroundColor: 'red' });
+chart1.setOption(...);
```
-如果这个主题不在其他图表中使用，那么这两种方式是等价的，否则应使用前一种，这样在其他图表中也可以使用 `setTheme('myTheme')` 使用该主题。
+注意：当前的实现中，如果在 `chart.setOption` 后调用
+
+**[注意]：**
+
+当前的实现中，并不支持使用 "merge 模式" 调用 `chart.setOption` 后调用 `setTheme`。即，
+```js
+// --- 可能不符合预期 ---
+const chart1 = echarts.init(mainDOMElement);
+chart1.setOption(option1);
+chart1.setOption(option2); // 使用 “merge 模式” 调用 `setOption`
+chart1.setOption(option3);
+chart1.setTheme('dark');
+// 调用 `setTheme` 后，之前的 options （option1 and option2）被丢弃了，
+// 只有最后的 option （option3）被留了下来。
+
+// --- 解决方案 ---
+const chart1 = echarts.init(mainDOMElement);
+// 保证每个 option 都含有全量信息，然后使用 “notMerge 模式” 调用 `setOption`
+chart1.setOption(option1, {notMerge: true});
+chart1.setOption(option2, {notMerge: true});
+chart1.setOption(option3, {notMerge: true});
+chart1.setTheme('dark');
+// 调用 `setTheme` 后，之前的 options （option1 and option2）仍然被丢弃了，
+// 但因为最后的 option （option3）中含有全量信息且被留了下来，最终效果是正确的。
+```
+
+
## resize(Function)
```ts
@@ -295,7 +331,7 @@ chart.setTheme({backgroundColor: 'red'});
## renderToSVGString(Function)
-> 从 `5.3.0` 开始支持
+{{ use: partial-version(version = "5.3.0") }}
```ts
(opts?: {
@@ -513,124 +549,299 @@ ECharts 中的事件有两种，一种是鼠标事件，在鼠标点击某个图
## convertToPixel(Function)
```ts
(
- // finder 用于指示『使用哪个坐标系进行转换』。
- // 通常地，可以使用 index 或者 id 或者 name 来定位。
+ // `finder` 用于指示『使用哪个坐标系或数轴或系列进行转换』。
+ // 通常使用 xxxIndex 或者 xxxId 或者 xxxName 来定位。
finder: {
- seriesIndex?: number,
- seriesId?: string,
- seriesName?: string,
- geoIndex?: number,
- geoId?: string,
- geoName?: string,
xAxisIndex?: number,
- xAxisId?: string,
+ xAxisId?: string | number,
xAxisName?: string,
yAxisIndex?: number,
- yAxisId?: string,
+ yAxisId?: string | number,
yAxisName?: string,
gridIndex?: number,
- gridId?: string,
- gridName?: string
+ gridId?: string | number,
+ gridName?: string,
+
+ polarIndex?: number,
+ polarId?: string | number,
+ polarName?: string,
+
+ geoIndex?: number,
+ geoId?: string | number,
+ geoName?: string,
+
+ singleAxisIndex?: number,
+ singleAxisId?: string | number,
+ singleAxisName?: string,
+
+ calendarIndex?: number,
+ calendarId?: string | number,
+ calendarName?: string,
+
+ matrixIndex?: number,
+ matrixId?: string | number,
+ matrixName?: string,
+
+ seriesIndex?: number,
+ seriesId?: string | number,
+ seriesName?: string,
},
- // 要被转换的值。
- value: Array|number
- // 转换的结果为像素坐标值，以 echarts 实例的 dom 节点的左上角为坐标 [0, 0] 点。
-) => Array|number
+ // 要被转换的坐标（基于指定的坐标系或数轴或系列）。
+ coord:
+ [(number | string), (number | string)]
+ | [
+ [(number | string), (number | string)],
+ [(number | string), (number | string)]
+ ]
+ | (number | string),
+ // 额外的可选参数，由每个坐标系自己定义。
+ opt?: unknown
+) =>
+ // 转换的结果为像素值，以 echarts 实例的 dom 节点的左上角为
+ // 坐标 [0, 0] 点。
+ [number, number] | number
```
-转换坐标系上的点到像素坐标值。
+转换坐标系或数轴或系列（即，[cartesian2d (grid)](option.html#grid), [only xAxis](option.html#xAxis), [only yAxis](option.html#yAxis), [polar](option.html#polar), [geo](option.html#geo), [series.map](option.html#series-map), [singleAxis](option.html#singleAxis), [calender](option.html#calendar), [matrix](option.html#matrix)）上的坐标到画布上的像素值。
+输入的 `coord` 以及返回值的格式由各个坐标系或坐标轴或系列定义：
++ [cartesian2d（grid）](option.html#grid)：
-例：
+ 输入的 `coord` 是一个两项数组，其中 `value[0]` 和 `value[1]` 分别对应 [xAxis](option.html#xAxis) 和 [yAxis](option.html#yAxis)。数据类型根据 [axis.type](option.html#~xAxis.type) 的不同而不同：
-在地理坐标系（[geo](option.html#geo)）上，把某个点的经纬度坐标转换成为像素坐标：
-```ts
-// [128.3324, 89.5344] 表示 [经度，纬度]。
-// 使用第一个 geo 坐标系进行转换：
-chart.convertToPixel('geo', [128.3324, 89.5344]); // 参数 'geo' 等同于 {geoIndex: 0}
-// 使用第二个 geo 坐标系进行转换：
-chart.convertToPixel({geoIndex: 1}, [128.3324, 89.5344]);
-// 使用 id 为 'bb' 的 geo 坐标系进行转换：
-chart.convertToPixel({geoId: 'bb'}, [128.3324, 89.5344]);
-```
+ - 如果 [axis.type](option.html#~xAxis.type) 为 `'value'`、`'log'`，则输入的 `coord` 应为 `[number, number]`。
+ - 如果 [axis.type](option.html#~xAxis.type) 为 `'category'`，则输入的 `coord` 可以是 `[(number | string), (number | string)]`，其中 `string` 表示 `series.data` 中的原始字符串，`number` 表示由原始字符串转换而来的序号（为非负整数，从 `0` 开始递增）。
+ - 如果 [axis.type](option.html#~xAxis.type) 为 `'time'`，则输入的 `coord` 可以是 `[(number | string | Date), (number | string | Date)]`，其中 `number` 表示时间戳，`string | Date` 表示可被 [`echarts/src/util/number.ts` 中的 `parseDate` 方法](https://github.com/apache/echarts/blob/master/src/util/number.ts) 解析的任意时间格式。
-在直角坐标系（cartesian，[grid](option.html#grid)）上，把某个点的坐标转换成为像素坐标：
-```ts
-// [300, 900] 表示该点 x 轴上对应刻度值 300，y 轴上对应刻度值 900。
-// 注意，一个 grid 可能含有多个 xAxis 和多个 yAxis，任何一对 xAxis-yAxis 形成一个 cartesian。
-// 使用第三个 xAxis 和 id 为 'y1' 的 yAxis 形成的 cartesian 进行转换：
-chart.convertToPixel({xAxisIndex: 2, yAxisId: 'y1'}, [300, 900]);
-// 使用 id 为 'g1' 的 grid 的第一个 cartesian 进行转换：
-chart.convertToPixel({gridId: 'g1'}, [300, 900]);
-```
+ 例如：
+ ```ts
+ // [300, 900] 表示该点 x 轴上对应刻度值 300，y 轴上对应刻度值 900。
+ // 注意，一个 grid 可能含有多个 xAxis 和多个 yAxis，任何一对 xAxis-yAxis 形成一个 cartesian。
+ // 使用第三个 xAxis 和 id 为 'y1' 的 yAxis 形成的 cartesian 进行转换：
+ result = chart.convertToPixel({xAxisIndex: 2, yAxisId: 'y1'}, [300, 900]);
+ // 使用 id 为 'g1' 的 grid 的第一个 cartesian 进行转换：
+ result = chart.convertToPixel({gridId: 'g1'}, [300, 900]);
+ ```
-把某个坐标轴的点转换成像素坐标：
-```ts
-// id 为 'x0' 的 xAxis 的刻度 3000 位置所对应的横向像素位置：
-chart.convertToPixel({xAxisId: 'x0'}, 3000); // 返回一个 number。
-// 第二个 yAxis 的刻度 600 位置所对应的纵向像素位置：
-chart.convertToPixel({yAxisIndex: 1}, 600); // 返回一个 number。
-```
++ [只转化 yAxis](option.html#xAxis) 或 [只转换 yAxis](option.html#yAxis)：
-把关系图（[graph](option.html#series-graph)）的点转换成像素坐标：
-```ts
-// 因为每个 graph series 自己持有一个坐标系，所以我们直接在 finder 中指定 series：
-chart.convertToPixel({seriesIndex: 0}, [2000, 3500]);
-chart.convertToPixel({seriesId: 'k2'}, [100, 500]);
-```
+ 例如，把某个坐标轴的点转换成像素坐标：
+ ```ts
+ // id 为 'x0' 的 xAxis (type: number) 的刻度 3000 位置所对应的横向像素位置：
+ result = chart.convertToPixel({xAxisId: 'x0'}, 3000); // 返回一个 number。
+ // 第二个 yAxis (type: category) 的刻度 'my category' 位置所对应的纵向像素位置：
+ result = chart.convertToPixel({yAxisIndex: 1}, 'my category'); // 返回一个 number。
+ ```
+
++ [polar](option.html#polar)：
+
+ 可类比于 `cartesian2d（grid）`。但仅支持通过 `polarIndex` / `polarId` / `polarName` 查询，不支持通过 `angleAxis` 和 `radiusAxis` 查询。
+
++ [geo](option.html#geo)：
+
+ 输入的 `coord` 可以是 `[number, number]`，当 [map](option.html#geo.map) 为 `GeoJSON` 时表示 `[longitude, latitude]`，当 [map](option.html#geo.map) 为 `SVG` 时表示 `[x_on_SVG, y_on_SVG]`。
+
+ 它也可以是一个 `string`，表示 `GeoJSON` 中的 `name`（即 `features[i].properties.name`，详见 [registerMap](~echarts.registerMap)）或 `SVG` 中的名称（即参见 [SVG Base Map](${handbookPath}how-to/component-types/geo/svg-base-map) 中的 “Named Element”），并返回该区域中心的像素点。
+
+ 例如，
+ ```ts
+ // [128.3324, 89.5344] represents [longitude, latitude].
+ // Perform conversion in the first geo coordinate system:
+ result = chart.convertToPixel('geo', [128.3324, 89.5344]); // The parameter 'geo' means {geoIndex: 0}.
+ // Perform conversion in the second geo coordinate system:
+ result = chart.convertToPixel({geoIndex: 1}, [128.3324, 89.5344]);
+ // Perform conversion in the geo coordinate system with id 'bb':
+ result = chart.convertToPixel({geoId: 'bb'}, [128.3324, 89.5344]);
+ // Input a name in `features[i].properties.name` in `GeoJSON`
+ // or a shape with `name="Bern"` in SVG:
+ result = chart.convertToPixel({geoId: 'bb'}, 'Bern');
+ ```
+
+ 在地理坐标系（[geo](option.html#geo)）上，把某个点的经纬度坐标转换成为像素坐标：
+ ```ts
+ // [128.3324, 89.5344] 表示 [经度，纬度]。
+ // 使用第一个 geo 坐标系进行转换：
+ result = chart.convertToPixel('geo', [128.3324, 89.5344]); // 参数 'geo' 等同于 {geoIndex: 0}
+ // 使用第二个 geo 坐标系进行转换：
+ result = chart.convertToPixel({geoIndex: 1}, [128.3324, 89.5344]);
+ // 使用 id 为 'bb' 的 geo 坐标系进行转换：
+ result = chart.convertToPixel({geoId: 'bb'}, [128.3324, 89.5344]);
+ // 输入一个名字，名字定义为 `GeoJSON` 中的 `features[i].properties.name:"Bern"`，
+ // 或者定义为 SVG 中的 `name="Bern"`：
+ result = chart.convertToPixel({geoId: 'bb'}, 'Bern');
+ ```
+
++ [series.map](option.html#series-map)：
+
+ 可类比于 `geo`。例如：
+ ```ts
+ result = chart.convertToPixel({seriesId: 'my_map'}, [128.3324, 89.5344]);
+ ```
+
++ [singleAxis](option.html#singleAxis)：
+
+ 可类比于 `only xAxis` 或 `only yAxis`。例如：
+ ```ts
+ result = chart.convertToPixel({singleAxisIndex: 0}, 333); // `axis.type` is `'value'`.
+ result = chart.convertToPixel({singleAxisIndex: 1}, 'my category'); // `axis.type` is `'category'`.
+ ```
+
++ [calendar](option.html#calendar)：
+ {{ use: partial-api-converter-calendar-coord-desc }}
+
++ In [matrix](option.html#matrix)：
+ {{ use: partial-api-converter-matrix-coord-desc }}
+
++ [series.graph](option.html#series-graph)：
+
+ 例如，
+ ```ts
+ // 因为每个 graph series 自己持有一个坐标系，所以我们直接在 `finder` 中指定 series：
+ // 输入的 `coord`（例如 [2000, 3500]）基于 graph 的原始坐标系，
+ // 即，与 `series.data[i].x` 和 `series.data[i].y` 所使用的坐标系相同。
+ result = chart.convertToPixel({seriesIndex: 0}, [2000, 3500]);
+ result = chart.convertToPixel({seriesId: 'k2'}, [100, 500]);
+ ```
+
++ 其他情况：
+
+ 在某个系列所在的坐标系（无论是 cartesian、geo、graph 等）中，转换某点成像素坐标：
+ ```ts
+ // 使用第一个系列对应的坐标系：
+ result = chart.convertToPixel({seriesIndex: 0}, [128.3324, 89.5344]);
+ // 使用 id 为 'k2' 的系列所对应的坐标系：
+ result = chart.convertToPixel({seriesId: 'k2'}, [128.3324, 89.5344]);
+ ```
+
+
+## convertToLayout(Function)
+
+{{ use: partial-version(version = "6.0.0") }}
-在某个系列所在的坐标系（无论是 cartesian、geo、graph 等）中，转换某点成像素坐标：
```ts
-// 使用第一个系列对应的坐标系：
-chart.convertToPixel({seriesIndex: 0}, [128.3324, 89.5344]);
-// 使用 id 为 'k2' 的系列所对应的坐标系：
-chart.convertToPixel({seriesId: 'k2'}, [128.3324, 89.5344]);
+(
+ // `finder` 用于指示『使用哪个坐标系或数轴或系列进行转换』。
+ // 通常使用 xxxIndex 或者 xxxId 或者 xxxName 来定位。
+ finder: {
+ calendarIndex?: number,
+ calendarId?: string | number,
+ calendarName?: string,
+
+ matrixIndex?: number,
+ matrixId?: string | number,
+ matrixName?: string,
+ },
+ // 要被转换的坐标（基于指定的坐标系或数轴或系列）。
+ coord:
+ [(number | string), (number | string)]
+ | [
+ [(number | string), (number | string)],
+ [(number | string), (number | string)]
+ ]
+ | (number | string),
+ // 额外的可选参数，由每个坐标系自己定义。
+ opt?: unknown
+) =>
+ {
+ rect?: {x: number; y: number; width: number; height: number};
+ contentRect?: {x: number; y: number; width: number; height: number};
+ matrixXYLocatorRange?: [[number, number], [number, number]];
+ }
```
+将坐标系上的 `coord`（即，[calendar](option.html#calendar)、[matrix](option.html#matrix)）转换为布局信息。
+
+输入的 `coord` 的格式和返回类型由各个坐标系定义：
++ [calendar](option.html#calendar):
+ {{ use: partial-api-converter-calendar-coord-desc }}
+ 返回值为:
+ ```ts
+ interface CoordinateSystemDataLayout {
+ // 每个单元格的矩形，不考虑单元格是否有边框，即，相邻单元格会贴着。
+ rect: {x: number, y: number, width: number, height: number};
+ // `rect` 减去边框得到的矩形。
+ contentRect: {x: number, y: number, width: number, height: number};
+ }
+ ```
+
++ In [matrix](option.html#matrix):
+ {{ use: partial-api-converter-matrix-coord-desc }}
+ 返回值为：
+ ```ts
+ interface CoordinateSystemDataLayout {
+ // 每个单元格的矩形，不考虑单元格是否有边框，即，相邻单元格会贴着。
+ rect: {x: number, y: number, width: number, height: number};
+ // 注：去除 border 和 padding 的 `contentRect` 并不提供，因为 matrix 坐标系支持结果跨越多个单元格。
+
+ // 序数（ordinal numbers）的范围。意为：
+ // `[[minXOrdinal, maxXOrdinal], [minYOrdinal, maxYOrdinal]]`
+ matrixXYLocatorRange: [[number, number], [number, number]];
+ }
+ ```
+
+
## convertFromPixel(Function)
```ts
(
- // finder 用于指示『使用哪个坐标系进行转换』。
- // 通常地，可以使用 index 或者 id 或者 name 来定位。
+ // `finder` 用于指示『使用哪个坐标系或数轴或系列进行转换』。
+ // 通常使用 xxxIndex 或者 xxxId 或者 xxxName 来定位。
finder: {
- seriesIndex?: number,
- seriesId?: string,
- seriesName?: string,
- geoIndex?: number,
- geoId?: string,
- geoName?: string,
xAxisIndex?: number,
- xAxisId?: string,
+ xAxisId?: string | number,
xAxisName?: string,
yAxisIndex?: number,
- yAxisId?: string,
+ yAxisId?: string | number,
yAxisName?: string,
gridIndex?: number,
- gridId?: string,
- gridName?: string
+ gridId?: string | number,
+ gridName?: string,
+
+ polarIndex?: number,
+ polarId?: string | number,
+ polarName?: string,
+
+ geoIndex?: number,
+ geoId?: string | number,
+ geoName?: string,
+
+ singleAxisIndex?: number,
+ singleAxisId?: string | number,
+ singleAxisName?: string,
+
+ calendarIndex?: number,
+ calendarId?: string | number,
+ calendarName?: string,
+
+ matrixIndex?: number,
+ matrixId?: string | number,
+ matrixName?: string,
+
+ seriesIndex?: number,
+ seriesId?: string | number,
+ seriesName?: string,
},
- // 要被转换的值，为像素坐标值，以 echarts 实例的 dom 节点的左上角为坐标 [0, 0] 点。
- value: Array|number
- // 转换的结果，为逻辑坐标值。
-) => Array|number
+ // 要被转换的值，为像素值，以 echarts 实例的 dom 节点的左上角为坐标 [0, 0] 点。
+ value: [number, number] | number,
+ // 额外的可选参数，由每个坐标系自己定义。
+ opt?: unknown
+) =>
+ // 转换的结果坐标（基于指定的坐标系或数轴或系列）。
+ [number, number]
+ | [[number, number], [number, number]]
+ | number
```
-转换像素坐标值到逻辑坐标系上的点。是 [convertToPixel](~echartsInstance.convertToPixel) 的逆运算。
+转换像素值到逻辑坐标系上的点。是 [convertToPixel](~echartsInstance.convertToPixel) 的逆运算。
+
具体实例可参考 [convertToPixel](~echartsInstance.convertToPixel)。
## containPixel(Function)
```ts
(
- // finder 用于指示『在哪个坐标系或者系列上判断』。
- // 通常地，可以使用 index 或者 id 或者 name 来定位。
+ // `finder` 用于指示『使用哪个坐标系或数轴或系列进行转换』。
+ // 通常使用 xxxIndex 或者 xxxId 或者 xxxName 来定位。
finder: {
- seriesIndex?: number,
- seriesId?: string,
- seriesName?: string,
- geoIndex?: number,
- geoId?: string,
- geoName?: string,
xAxisIndex?: number,
xAxisId?: string,
xAxisName?: string,
@@ -640,6 +851,18 @@ chart.convertToPixel({seriesId: 'k2'}, [128.3324, 89.5344]);
gridIndex?: number,
gridId?: string,
gridName?: string
+
+ geoIndex?: number,
+ geoId?: string,
+ geoName?: string,
+
+ matrixIndex?: number,
+ matrixId?: string,
+ matrixName?: string
+
+ seriesIndex?: number,
+ seriesId?: string,
+ seriesName?: string,
},
// 要被判断的点，为像素坐标值，以 echarts 实例的 dom 节点的左上角为坐标 [0, 0] 点。
value: Array
@@ -648,21 +871,22 @@ chart.convertToPixel({seriesId: 'k2'}, [128.3324, 89.5344]);
判断给定的点是否在指定的坐标系或者系列上。
-目前支持在这些坐标系和系列上进行判断：[grid](option.html#grid), [polar](option.html#polar), [geo](option.html#geo), [series-map](option.html#series-map), [series-graph](option.html#series-graph), [series-pie](option.html#series-pie)。
+目前支持在这些坐标系和系列上进行判断：[grid](option.html#grid), [polar](option.html#polar), [geo](option.html#geo), [matrix](option.html#matrix), [series-map](option.html#series-map), [series-graph](option.html#series-graph), [series-pie](option.html#series-pie)。
例：
```ts
// 判断 [23, 44] 点是否在 geoIndex 为 0 的 geo 坐标系上。
-chart.containPixel('geo', [23, 44]); // 'geo' 等同于 {geoIndex: 0}
+result = chart.containPixel('geo', [23, 44]); // 'geo' 等同于 {geoIndex: 0}
// 判断 [23, 44] 点是否在 gridId 为 'z' 的 grid 上。
-chart.containPixel({gridId: 'z'}, [23, 44]);
+result = chart.containPixel({gridId: 'z'}, [23, 44]);
// 判断 [23, 44] 点是否在 index 为 1，4，5 的系列上。
-chart.containPixel({seriesIndex: [1, 4, 5]}, [23, 44]);
+result = chart.containPixel({seriesIndex: [1, 4, 5]}, [23, 44]);
// 判断 [23, 44] 点是否在 index 为 1，4，5 的系列或者 gridName 为 'a' 的 grid 上。
-chart.containPixel({seriesIndex: [1, 4, 5], gridName: 'a'}, [23, 44]);
+result = chart.containPixel({seriesIndex: [1, 4, 5], gridName: 'a'}, [23, 44]);
```
+
## showLoading(Function)
```ts
(type?: string, opts?: Object)
@@ -781,3 +1005,77 @@ img.src = myChart.getDataURL({
## dispose
销毁实例，销毁后实例无法再被使用。
+
+
+
+{{ target: partial-api-converter-calendar-coord-desc }}
+ 输入的 `coord` 可以是 `number | string | Date`，其中 `number` 表示时间戳，`string | Date` 表示可被 [`echarts/src/util/number.ts` 中的 `parseDate` 方法](https://github.com/apache/echarts/blob/master/src/util/number.ts) 解析的任意时间格式。例如，
+ ```ts
+ result = chart.convertToPixel({calendarIndex: 0}, '2021-01-01');
+ result = chart.convertToPixel({calendarIndex: 0}, new Date(1609459200000));
+ result = chart.convertToPixel({calendarIndex: 0}, 1609459200000);
+ ```
+{{ /target }}
+
+
+{{ target: partial-api-converter-matrix-coord-desc }}
+ 输入的 `coord` 用于定位一个矩形，然后返回该矩形的中心点。更多详情参见 [matrix.body.data.coord](option.html#matrix.body.data.coord)。例如：
+ ```ts
+ chart.setOption({
+ matrix: {
+ x: {data: ['AA', 'BB', 'CC', 'DD']},
+ y: {data: ['MM', 'NN']}
+ }
+ });
+ result = chart.convertToPixel({matrixIndex: 0}, ['AA', 'NN']);
+ result = chart.convertToLayout({matrixIndex: 0}, ['AA', 'NN']);
+ // 这个矩形可以跨越多个单元格：
+ result = chart.convertToPixel({matrixIndex: 0}, [['AA', 'CC'], 'MM']);
+ result = chart.convertToLayout({matrixIndex: 0}, [['AA', 'CC'], 'MM']);
+ // 这些数值是序数（非负整数，从 0 自增），对应于上述字符串名字。
+ result = chart.convertToPixel({matrixIndex: 0}, [1, 2]);
+ result = chart.convertToLayout({matrixIndex: 0}, [1, 2]);
+ result = chart.convertToPixel({matrixIndex: 0}, [[1, 3], [0, 1]]);
+ result = chart.convertToLayout({matrixIndex: 0}, [[1, 3], [0, 1]]);
+ ```
+
+ 输入的 `opt` 是可选的:
+ ```ts
+ opt?: {
+ // 可选值：
+ // - `0`/`null`/`undefined`（默认），不把结果限制到边界内，即，如果输入的
+ // `coord[0]` 或 `coord[1]` 是 `null`/`undefined`/`NaN`/"超出边界"，
+ // 则相应的结果值是 `NaN`，而非使用一个边界值。
+ // - 否则，限制到边界内。其中：
+ // - `1`: 限制在整个矩形坐标系的范围中。
+ // - `2`: 限制在矩形坐标系的 body 范围中。
+ // - `3`: 限制在矩形坐标系的 corner 范围中。
+ // 注：
+ // - 此参数在 `convertToPixel`、`convertToLayout` 和 `convertFromPixel` 都支持。
+ // - X 和 Y 分别计算，即，如果只有 X 超出边界，结果可能为
+ // `rect: {x: NaN, width: NaN, y: 123, width: 456}`
+ clamp?: null | undefined | 0 | 1 | 2 | 3;
+
+ // 如果“结果矩形区域”和“合并的单元格”相交（即，
+ // `matrix['body'/'corner'].data.mergeCells: true`）
+ // 是否扩展“结果矩形区域”以完全覆盖“合并的单元格”。默认为 `false`。
+ ignoreMergeCells?: boolean;
+ }
+
+ // 例如：
+ const {rect, matrixXYLocatorRange} = chart.convertToLayout(
+ {matrixIndex: 0},
+ [10000, 2],
+ {clamp: 0}
+ );
+ // `rect` 为 `{x: NaN, y: 10, width: NaN, height: 100}`。
+ // `matrixXYLocatorRange` 为 `[[NaN, NaN], [2, 2]]`。
+ const {rect, matrixXYLocatorRange} = chart.convertToLayout(
+ {matrixIndex: 0},
+ [10000, 2],
+ {clamp: 1}
+ );
+ // `rect` 为 `{x: 20, y: 10, width: 200, height: 100}`.
+ // `matrixXYLocatorRange` 为 `[[0, 3], [2, 2]]`.
+ ```
+{{ /target }}
diff --git a/zh/api/echarts.md b/zh/api/echarts.md
index e08cf7958..54b449a91 100644
--- a/zh/api/echarts.md
+++ b/zh/api/echarts.md
@@ -102,7 +102,7 @@ echarts.connect([chart1, chart2]);
## use(Function)
-> 从 `5.0.1` 开始支持
+{{ use: partial-version(version = "5.0.1") }}
使用组件，配合新的按需引入的接口使用。
@@ -196,7 +196,7 @@ echarts.use(
+ **@param `opt.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` 开始支持SVG 格式的数据。可以是字符串，也可以是解析得到的 SVG DOM 对象。更多信息参见 [SVG 底图](${handbookPath}how-to/component-types/geo/svg-base-map)。
例如，一个极小的 SVG：
```ts
@@ -262,6 +262,9 @@ echarts.use(
## registerTheme(Function)
+
+{{ use: partial-version(version = "6.0.0") }}
+
```ts
(themeName: string, theme: Object)
```
@@ -321,7 +324,7 @@ chart.setOption(option);
## registerLocale(Function)
-> 从 `5.0.0` 开始支持
+{{ use: partial-version(version = "5.0.0") }}
```ts
(locale: string, localeCfg: Object)
@@ -331,7 +334,7 @@ chart.setOption(option);
## setPlatformAPI(Function)
-> 从 `5.3.0` 开始支持
+{{ use: partial-version(version = "5.3.0") }}
```ts
(platformAPI?: {
diff --git a/zh/api/events.md b/zh/api/events.md
index e4953f1a2..6ce19f90b 100644
--- a/zh/api/events.md
+++ b/zh/api/events.md
@@ -201,6 +201,44 @@ chart.on('mouseover', {seriesIndex: 1, name: 'xx'}, function (params) {
```
+## axisbreakchanged(Event)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+**ACTION:** [expandAxisBreak](~action.axis.expandAxisBreak), [collapseAxisBreak](~action.axis.collapseAxisBreak) and [toggleAxisBreak](~action.axis.toggleAxisBreak) 会派发本事件。
+
+```ts
+{
+ type: 'axisbreakchanged';
+ // 触发本事件的 action 的 type 。
+ fromAction: 'expandAxisBreak' | 'collapseAxisBreak' | 'toggleAxisBreak';
+ // 触发本事件的 action 的 payload 。
+ fromActionPayload: Payload;
+ // 本 breaks 数组里只包含 action 里指定的 break 项，
+ // 而非 axis 里存在的所有 break 项。
+ breaks: {
+ // start/end 也被用于本 break 项的唯一标识。
+ start: number;
+ end: number;
+
+ // 本 break item 所在的 axis 的 index。
+ xAxisIndex?: number;
+ yAxisIndex?: number;
+ singleAxisIndex?: number;
+
+ // 更新后的状态。
+ isExpanded: boolean;
+ old: {
+ // 更新前的状态。
+ isExpanded: boolean;
+ };
+ }[]
+}
+```
+
+**注意：**使用 [chart.setOption](~echartsInstance.setOption) 更新 axis breaks 时，不会触发本事件。只有 action 会触发本事件。
+
+
## datazoom(Event)
**ACTION:** [dataZoom](~action.dataZoom.dataZoom)
diff --git a/zh/api/version.md b/zh/api/version.md
index aea7002e6..36f0782a5 100644
--- a/zh/api/version.md
+++ b/zh/api/version.md
@@ -1,9 +1,11 @@
{{ target: partial-version }}
+
{{ if: ${deprecated} }}
-> 从 `v${version}` 开始不推荐使用（deprecated）。${deprecated}
+从 `v${version}` 开始不推荐使用（deprecated）。${deprecated}
{{ else }}
-> 从 `v${version}` 开始支持
+从 `v${version}` 开始支持
{{ /if }}
+
{{ // this line break is necessary for md quote }}
diff --git a/zh/option-gl/component/axis3D-common.md b/zh/option-gl/component/axis3D-common.md
index 9a8747543..8d5a055d0 100644
--- a/zh/option-gl/component/axis3D-common.md
+++ b/zh/option-gl/component/axis3D-common.md
@@ -82,7 +82,9 @@ formatter: function (value, index) {
{{ /if }}
##${prefix|default('#')} formatter(string|Function) = null
-{{use: axis-common-formatter-desc}}
+{{ use: axis-common-formatter-desc(
+ componentType=${componentType}
+) }}
##${prefix|default('#')} textStyle(Object)
diff --git a/zh/option-gl/partial/version.md b/zh/option-gl/partial/version.md
index 45166dd61..cf9cb8a55 100644
--- a/zh/option-gl/partial/version.md
+++ b/zh/option-gl/partial/version.md
@@ -1,8 +1,10 @@
{{ target: partial-version }}
+
{{ if: ${deprecated} }}
-> 从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始不推荐使用（deprecated）。${deprecated}
+从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始不推荐使用（deprecated）。${deprecated}
{{ else }}
-> 从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始支持
+从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始支持
{{ /if }}
+
diff --git a/zh/option/component/axis-common.md b/zh/option/component/axis-common.md
index a1904f0f3..e60d3cdc8 100644
--- a/zh/option/component/axis-common.md
+++ b/zh/option/component/axis-common.md
@@ -23,6 +23,7 @@
}
```
+{{ if: ${hasJitter|default(false)} }}
#${prefix} jitter(number) = 0
{{ use: partial-version(version = "6.0.0") }}
@@ -44,6 +45,209 @@
{{ use: partial-version(version = "6.0.0") }}
在设置了 [jitter](~${componentType}.jitter) 且 [jitterOverlap](~${componentType}.jitterOverlap) 为 `false` 的情况下，两个数据点之间的最小距离。
+{{ /if }}
+
+
+
+{{ if: ${hasBreakAxis|default(false)} }}
+#${prefix} breaks(Array)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+断轴的截断数据，每一个子元素表示一段截断的空间。
+
+~[800x400](${galleryViewPath}intraday-breaks-2&edit=1&reset=1)
+~[800x400](${galleryViewPath}intraday-breaks-1&edit=1&reset=1)
+~[800x400](${galleryViewPath}bar-breaks-brush&edit=1&reset=1)
+
+**其他例子：** [bar-breaks-simple](${galleryEditorPath}bar-breaks-simple&edit=1&reset=1), [line-fisheye-lens](${galleryEditorPath}line-fisheye-lens&edit=1&reset=1)
+
+
+> 断轴是一种通过在坐标轴上截断部分区域，从而压缩图表中非关键数据段的展示空间的技术。其核心目的是：
+>
+> + **突出差异**：当数据间存在极端差异时（如一个值远大于其他值），避免大数值柱子压倒性占据空间，导致小数值差异难以辨认。
+> + **节省空间**：减少因极值导致的空白区域，使图表更紧凑。
+>
+> 请注意仅在必要的时候使用断轴，以免给用户带来理解上的误导。当使用断轴时，通常应当明确示意截断部分和对应的数值。
+>
+> 断轴无法在类目轴（[type](~${componentType}.type): `'category'`）中使用。
+
+如果 ECharts 的 `import` 方式是 [只 `import` 所需要的组件](${handbookPath}basics/import)，断轴功能需要被手动 `import` 和注册。例如，
+```ts
+import * as echarts from 'echarts/core';
+import { BarChart } from 'echarts/charts';
+import {
+ TitleComponent,
+ TooltipComponent,
+ GridComponent,
+ DatasetComponent,
+ TransformComponent
+} from 'echarts/components';
+
+// import 断轴功能
+import { AxisBreak } from 'echarts/features';
+
+import { CanvasRenderer } from 'echarts/renderers';
+
+// 注册
+echarts.use([
+ BarChart,
+ TitleComponent,
+ TooltipComponent,
+ GridComponent,
+ DatasetComponent,
+ TransformComponent,
+ AxisBreak,
+ CanvasRenderer
+]);
+
+var myChart = echarts.init(document.getElementById('main'));
+myChart.setOption({
+ // ...
+});
+```
+
+##${prefix} start(string|number|Date)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+开始截断的值。它是业务数据（`series.data`）所定义的值域中的某个值，而非像素值。
+
+{{ use: partial-scale-data-value-desc(
+ componentType = ${componentType},
+ notSupportCategory = true
+) }}
+
+{{ use: partial-axis-break-identifier-desc(
+ componentType = ${componentType}
+)}}
+
+##${prefix} end(string|number|Date)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+结束截断的值。它是业务数据（`series.data`）所定义的值域中的某个值，而非像素值。
+
+{{ use: partial-scale-data-value-desc(
+ componentType = ${componentType},
+ notSupportCategory = true
+) }}
+
+{{ use: partial-axis-break-identifier-desc(
+ componentType = ${componentType}
+)}}
+
+##${prefix} gap(number|string)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+决定了断轴截断区域最终展示的尺寸（高或者宽）。其值可为：
+
++ 百分比（字符串）：
+
+ 表示相对于坐标轴的比例。例如 `'5%'`，表示断轴截断区域最终显示的尺寸总为坐标轴尺寸的 `'5%'`。使用百分比能保证断轴截断区域的像素尺寸稳定，不随着 [${componentType}.min](~${componentType}.min)、[${componentType}.max](~${componentType}.max)、[dataZoom](~dataZoom) 变化而变化，因此目前大多数场景都适合使用百分比。
++ 绝对值：
+
+ 其单位和 [start](~${componentType}.breaks.start) 与 [end](~${componentType}.breaks.end) 相同，是业务数据（`series.data`）所定义的值域中的某个值，而非像素值。它表示把 `[start, end]` 这个区间映射（替换）为 `[start, start + gap]`。因此，设为绝对值时，断轴截断区域的像素尺寸会随着 [${componentType}.min](~${componentType}.min)、[${componentType}.max](~${componentType}.max)、[dataZoom](~dataZoom) 变化而变化。
+
+**注意：**在一个 [${componentType}.breaks](~${componentType}.breaks) 数组中，`gap` 只允许全使用百分比，或者全使用绝对值，不允许混合使用，否者效果可能不符合预期。
+
+{{ use: partial-axis-break-identifier-desc(
+ componentType = ${componentType}
+)}}
+
+##${prefix} isExpanded(boolean) = false
+
+{{ use: partial-version(version = "6.0.0") }}
+
+该截断区域是否已展开，默认为 `false`。
+
+{{ use: partial-axis-break-identifier-desc(
+ componentType = ${componentType}
+)}}
+
+#${prefix} breakArea
+
+{{ use: partial-version(version = "6.0.0") }}
+
+断轴截断区域的样式。
+
+断轴的基本介绍参见 [${componentType}.breaks](~${componentType}breaks)。
+
+##${prefix} show(boolean) = true
+
+{{ use: partial-version(version = "6.0.0") }}
+
+是否显示截断区域。
+
+##${prefix} itemStyle
+
+{{ use: partial-version(version = "6.0.0") }}
+
+截断区域样式。
+
+{{ use: partial-item-style(
+ prefix = '###',
+ defaultColor = "#fff",
+ defaultBorderColor = "'#b7b9be'",
+ defaultBorderWidth = 1,
+ defaultType = "[3, 3]",
+ defaultOpacity = 0.6
+) }}
+
+##${prefix} zigzagAmplitude(number) = 4
+
+{{ use: partial-version(version = "6.0.0") }}
+
+锯齿的振幅（垂直于坐标轴方向上）大小。这个大小在不同锯齿上总是相同的。单位为像素。如果设为 `0` 则锯齿退化成一条直线。
+
+##${prefix} zigzagMinSpan(number) = 4
+
+{{ use: partial-version(version = "6.0.0") }}
+
+每个锯齿跨度的最小值。单位为像素。
+
+> 每个锯齿跨度大小是 `zigzagMinSpan` 和 `zigzagMaxSpan` 之间的随机数。通过随机来模拟纸片撕开的效果。
+
+##${prefix} zigzagMaxSpan(number) = 20
+
+{{ use: partial-version(version = "6.0.0") }}
+
+每个锯齿跨度的最大值。单位为像素。
+
+> 每个锯齿跨度大小是 `zigzagMinSpan` 和 `zigzagMaxSpan` 之间的随机数。通过随机来模拟纸片撕开的效果。
+
+##${prefix} zigzagZ(number) = 100
+
+{{ use: partial-version(version = "6.0.0") }}
+
+锯齿的 `z` 值。控制图形的前后顺序。`z` 值小的图形会被 `z` 值大的图形覆盖。
+
+##${prefix} expandOnClick(boolean) = true
+
+{{ use: partial-version(version = "6.0.0") }}
+
+点击断轴截断区域是否展开截断区域。
+
+#${prefix} breakLabelLayout(Object)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+断轴文字布局。
+
+断轴的基本介绍参见 [${componentType}.breaks](~${componentType}breaks)。
+
+
+##${prefix} moveOverlap(string|boolean) = 'auto'
+
+{{ use: partial-version(version = "6.0.0") }}
+
+当断轴文字重叠时，是否移动文字来避免重叠。
+
+`'auto'` 或 `true` 表示重叠时移动文字来避免重叠；`false` 表示不移动。
+{{ /if }}
+
+
#${prefix} axisLine(Object)
@@ -153,7 +357,10 @@ X 轴或者 Y 轴的轴线是否在另一个轴的 0 刻度上，只有在另一
##${prefix} formatter(string|Function)
-{{ use: axis-common-formatter-desc() }}
+{{ use: axis-common-formatter-desc(
+ componentType = ${componentType},
+ supportAxisBreak = true
+) }}
##${prefix} showMinLabel(boolean)
@@ -345,7 +552,7 @@ textStyle: {
###${prefix} color(Color)
-刻度线的颜色，默认取 [axisTick.lineStyle.color](~${componentType}.axisTick.lineStyle.color)。
+刻度线的颜色，默认取 [axisLine.lineStyle.color](~${componentType}.axisLine.lineStyle.color)。
##${prefix} customValues(Array)
@@ -688,7 +895,7 @@ boundaryGap: ['20%', '20%']
不设置时会自动计算最小值保证坐标轴刻度的均匀分布。
-在类目轴中，也可以设置为类目的序数（如类目轴 `data: ['类A', '类B', '类C']` 中，序数 `2` 表示 `'类C'`。也可以设置为负数，如 `-3`）。
+{{ use: partial-scale-data-value-desc() }}
当设置成 `function` 形式时，可以根据计算得出的数据最大最小值设定坐标轴的最小值。如：
@@ -710,7 +917,7 @@ min: function (value) {
不设置时会自动计算最大值保证坐标轴刻度的均匀分布。
-在类目轴中，也可以设置为类目的序数（如类目轴 `data: ['类A', '类B', '类C']` 中，序数 `2` 表示 `'类C'`。也可以设置为负数，如 `-3`）。
+{{ use: partial-scale-data-value-desc() }}
当设置成 `function` 形式时，可以根据计算得出的数据最大最小值设定坐标轴的最小值。如：
@@ -800,7 +1007,9 @@ max: function (value) {
{{ use: partial-axis-common-axis-line(
prefix = ${prefix},
- componentType = ${componentType}
+ componentType = ${componentType},
+ hasJitter = ${hasJitter},
+ hasBreakAxis = ${hasBreakAxis}
) }}
{{ use: partial-axis-common-axis-tick(
@@ -912,6 +1121,10 @@ ${name}的显示间隔，在类目轴中有效。{{ if: !${isAxisLabel} }}默认
{{ target: axis-common-formatter-desc }}
+{{ if: !${axisTypeProp} }}
+{{ var: axisTypeProp = 'type' }}
+{{ /if }}
+
刻度标签的内容格式器，支持字符串模板和回调函数两种形式。
示例:
@@ -919,15 +1132,47 @@ ${name}的显示间隔，在类目轴中有效。{{ if: !${isAxisLabel} }}默认
// 使用字符串模板，模板变量为刻度默认标签 {value}
formatter: '{value} kg'
// 使用函数模板，函数参数分别为刻度数值（类目），刻度的索引
-formatter: function (value, index) {
+formatter: function (value, index, extra?) {
return value + 'kg';
}
```
---
-对于时间轴（[type](~${componentType}.type): `'time'`），`formatter` 的字符串模板支持多种形式：
+
+
+{{ if: ${supportAxisBreak} }}
+**如果使用了 [axis break](${componentType}.breaks)**
+break 信息可以在参数 `extra` 里被获取：
+```ts
+type AxisLabelFormatterExtraBreakPart = {
+ // 如果这个 label 是 break 的 start 或者 end
+ break?: {
+ type: 'start' | 'end';
+ // 这是解析过的 `start`/`end` 值，必然为 number，且进行过排序和重叠
+ // 去除，所以不一定和原先输入的 `start`/`end` 的类型和值相同。
+ start: number;
+ end: number;
+ }
+}
+formatter = function (value, index, extra: AxisLabelFormatterExtraBreakPart) {
+ if (extra && extra.break) {
+ console.log(extra.break);
+ }
+ return value + 'kg';
+}
+```
+注意：使用前需要判空。
+{{ /if }}
+
+---
+
+
+
+**对于时间轴（[`${componentType}.${axisTypeProp}: 'time'`](~${componentType}.${axisTypeProp})）**
+
+`formatter` 的字符串模板支持多种形式：
- **字符串模板**：简单快速实现常用日期时间模板，`string` 类型
- **回调函数**：自定义 formatter，可以用来实现复杂高级的格式，`Function` 类型
- **分级模板**：为不同时间粒度的标签使用不同的 formatter，`object` 类型
@@ -987,6 +1232,16 @@ formatter: function (value, index) {
}
return texts.join('/');
}
+
+// 另外，`echarts.time.format` 也可以被使用：
+formatter: function (value, index) {
+ // 时间模版的规则如上描述。
+ const timeStrLocal = echarts.time.format(value, '{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}');
+ // 第三个参数表示，基于 UTC 解析时间。
+ const timeStrUTC = echarts.time.format(value, '{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}', true);
+ // 注意：如果使用 UTC，${optionDocPath}#useUTC 也要设置为 `true`，保持一致。
+ return timeStrLocal;
+}
```
** 分级模板 **
@@ -1105,3 +1360,24 @@ xAxis: {
) }}
+
+{{ target: partial-scale-data-value-desc }}
+
+- 如果 [axis.type](~${componentType}.type) 是 `'value'` 或 `'log'`，则使用 `number` 类型的值。
+{{ if: ${notSupportCategory} }}
+- 如果 [axis.type](~${componentType}.type) 是 `'category'`：不支持。
+{{ else }}
+- 如果 [axis.type](~${componentType}.type) 是 `'category'`，值可以是：
+ - 原始字符串，例如 `'categoryA'`、`'categoryB'`。
+ - 序号。例如，如果类目轴定义为 `data: ['categoryA', 'categoryB', 'categoryC']`，则序号 `2` 表示 `'categoryC'`（从 `0` 开始计数）。此外，也可以设置为负数，例如 `-3`。
+{{ /if }}
+- 如果 [axis.type](~${componentType}.type) 是 `'time'`，值可以是：
+ - `string` 类型，表示任意能被 [方法 `parseDate` (`echarts/src/util/number.ts`)](https://github.com/apache/echarts/blob/master/src/util/number.ts) 解析的时间格式，例如 `'2024-04-09 13:00:00'`。
+ - `number` 类型，表示时间戳，例如 `1712667600000`。
+ - `Date` 类型的时间对象，例如 `new Date('2024-04-09T13:00:00Z')`。
+
+
+
+{{ target: partial-axis-break-identifier-desc }}
+
+注：[${componentType}.breaks.start](~${componentType}.breaks.start) 和 [${componentType}.breaks.end](~${componentType}.breaks.end) 是每个 break 项的唯一标志。当调用 [chart.setOption](api.html#echartsInstance.setOption) 修改 [${componentType}.breaks.gap](~${componentType}.breaks.gap) 或 [${componentType}.breaks.isExpanded](~${componentType}.breaks.isExpanded) 时，`start` `end` 必须指定，且如果 `start` `end` 不修改才会有更新动画，修改了则无。
diff --git a/zh/option/component/geo-common.md b/zh/option/component/geo-common.md
index 67cb49a80..399c0ec86 100644
--- a/zh/option/component/geo-common.md
+++ b/zh/option/component/geo-common.md
@@ -85,7 +85,7 @@ $.get('map/topographic_map.svg', function (svg) {
也参见示例 [Flight Seatmap](${galleryEditorPath}geo-seatmap-flight)。
{{ /if }}
-如上所示，ECharts 也可以使用 SVG 格式的地图。详情参见：[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)。
+如上所示，ECharts 也可以使用 SVG 格式的地图。详情参见：[SVG 底图](${handbookPath}how-to/component-types/geo/svg-base-map)。
#${prefix} projection(Object)
diff --git a/zh/option/component/matrix.md b/zh/option/component/matrix.md
index c6a57b8d2..ff9d05fe3 100644
--- a/zh/option/component/matrix.md
+++ b/zh/option/component/matrix.md
@@ -8,7 +8,7 @@
矩阵坐标系（`matrix`）类似表格，可作为系列（`series`）中数据项的布局系统，主要用于展示多维数据的关系与交互。它以矩形网格形式呈现数据，每个网格单元（或"单元格"）代表 `series.heatmap`、`series.scatter`、`series.custom` 等系列中某个数据点的值。整体布局以行列形式展示，用于表达二维或高维数据之间的关系。
-矩阵坐标系（`matrix`）还可作为盒布局系统，布局各个系列、其他坐标系（如 `grid`（即笛卡尔坐标系）、`geo`、`polar` 等）和普通组件（如 `legend`、`dataZoom` 等）。该特性支持在表格中布局微型图表，或使用类似 [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) 的布局方式进行排版。目前，所有系列和组件均可在 `matrix` 中布局。`matrix` 也可纯用作文字数据表。
+矩阵坐标系（`matrix`）还可作为盒布局系统，布局各个系列、其他坐标系（如 `grid`（即笛卡尔坐标系）、`geo`、`polar` 等）和普通组件（如 `legend`、`dataZoom` 等）。该特性支持在表格中布局 [微型图表](${galleryEditorPath}matrix-sparkline&edit=1&reset=1)，或使用类似 [CSS grid layout](${galleryEditorPath}matrix-grid-layout&edit=1&reset=1) 的布局方式进行排版。目前，所有系列和组件均可在 `matrix` 中布局。`matrix` 也可纯用作文字数据表。
在矩阵坐标系中使用热力图的相关矩阵图：
~[800x400](${galleryViewPath}matrix-correlation-heatmap&edit=1&reset=1)
@@ -25,6 +25,13 @@
在矩阵坐标系中使用自定义系列的混淆矩阵图：
~[800x400](${galleryViewPath}matrix-confusion&edit=1&reset=1)
+矩阵中的微型图表：
+~[800x600](${galleryViewPath}matrix-sparkline&edit=1&reset=1)
+~[800x600](${galleryViewPath}matrix-mini-bar-geo&edit=1&reset=1)
+
+以及其他 **微型图** 的例子：[矩阵中的微型柱状图和地图](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1)。
+
+
灵活利用图表系列、坐标系、API 的组合，可以实现更丰富的效果。
引用：
@@ -48,7 +55,8 @@
x 轴表头区。
{{ use: partial-matrix-header(
- name: 'x 轴表头区单元格'
+ name: 'x 轴表头区单元格',
+ matrixDim = 'x',
) }}
## y(Object)
@@ -58,7 +66,8 @@ x 轴表头区。
y 轴表头区。
{{ use: partial-matrix-header(
- name: 'y 轴表头区单元格'
+ name: 'y 轴表头区单元格',
+ matrixDim = 'y',
) }}
## body(Object)
diff --git a/zh/option/component/thumbnail.md b/zh/option/component/thumbnail.md
new file mode 100644
index 000000000..5dff544fa
--- /dev/null
+++ b/zh/option/component/thumbnail.md
@@ -0,0 +1,75 @@
+{{ target: component-thumbnail }}
+
+# thumbnail(Object)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+缩略图组件。
+
+现在仅支持用在 [关系图系列（series.graph）](~series-graph) 上。
+
+示例：[graph NPM](${galleryEditorPath}graph-npm&edit=1&reset=1)、[graph Webkit dep](${galleryEditorPath}graph-webkit-dep&edit=1&reset=1)。
+
+
+{{ use: partial-component-id(
+ prefix = "#"
+) }}
+
+## show(boolean) = true
+
+是否显示缩略图组件。
+
+{{ use: partial-rect-layout-width-height(
+ componentName = "缩略图组件（thumbnail）",
+ defaultLeft = "25%",
+ defaultTop = "25%"
+) }}
+
+{{ use: partial-coord-sys(
+ version = '6.0.0',
+ nonSeriesComponentMainType = "thumbnail",
+ coordSysDefault = "'none'",
+ matrix = true,
+ calendar = true,
+ none = true
+) }}
+
+## itemStyle(Object)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+外壳的样式。
+
+{{ use: partial-item-style(
+ prefix = '##',
+ defaultBorderColor = "'#b7b9be'",
+ defaultBorderWidth = 2
+) }}
+
+## windowStyle(Object)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+缩略图窗口的样式。
+
+{{ use: partial-item-style(
+ prefix = '##',
+ defaultColor = "'#9ea0a5'",
+ defaultBorderColor = "'#b7b9be'",
+ defaultBorderWidth = 1,
+ defaultOpacity = 0.3
+) }}
+
+## seriesIndex(number)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+指定此缩略图作用在哪个系列上。默认取第一个 [关系图系列（series.graph）](~series-graph)。
+
+## seriesId(string|number)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+指定此缩略图作用在哪个系列上。默认取第一个 [关系图系列（series.graph）](~series-graph)。
+
+{{ /target }}
diff --git a/zh/option/component/timeline.md b/zh/option/component/timeline.md
index e03b98e4f..e0ebe91e4 100644
--- a/zh/option/component/timeline.md
+++ b/zh/option/component/timeline.md
@@ -887,7 +887,10 @@ const option = {
#${prefix} formatter(string|Function) = null
-{{ use: axis-common-formatter-desc() }}
+{{ use: axis-common-formatter-desc(
+ componentType = ${componentType},
+ axisTypeProp = 'axisType'
+) }}
{{ if: ${state} }}
{{ use: partial-text-style(
diff --git a/zh/option/component/tooltip.md b/zh/option/component/tooltip.md
index f75360d7a..c767e259b 100644
--- a/zh/option/component/tooltip.md
+++ b/zh/option/component/tooltip.md
@@ -250,6 +250,18 @@ className: 'echarts-tooltip echarts-tooltip-dark'
提示框浮层的移动动画过渡时间，单位是 s，设置为 0 的时候会紧跟着鼠标移动。
+## displayTransition(boolean) = true
+
+
+
+{{ use: partial-version(
+ version = "6.0.0"
+) }}
+
+提示框显示/隐藏时是否启用过渡动画。
+
+默认情况下，提示框通过透明度淡入淡出过渡效果来实现显示/隐藏，而不是直接将 DOM 元素的 `display` 属性设置为 `'none'`。这在提示框内容比较多出现滚动条时，可能导致提示框隐藏后滚动条仍然存在的问题。在这种情况下，或者如果只是不想使用淡入淡出效果，可以将此选项设置为 `false` 以禁用显示/隐藏过渡动画。
+
{{ use: partial-tooltip-common(
scope = 'global',
prefix = '#'
diff --git a/zh/option/component/x-axis.md b/zh/option/component/x-axis.md
index 3704a4f07..26aa8125b 100644
--- a/zh/option/component/x-axis.md
+++ b/zh/option/component/x-axis.md
@@ -74,21 +74,21 @@ x 轴的位置。
+ `'top'`
+ `'bottom'`
-默认 grid 中的第一个 x 轴在 grid 的下方（`'bottom'`），第二个 x 轴视第一个 x 轴的位置放在另一侧。
-注：若未将 `xAxis.axisLine.onZero` 设为 `false` , 则该项无法生效
+默认 grid 中的第一个 x 轴在 grid 的下方（`'bottom'`），第二个 x 轴视第一个 x 轴的位置放在另一侧。注：若未将 `xAxis.axisLine.onZero` 设为 `false` , 则该项无法生效。
## offset(number) = 0
-X 轴相对于默认位置的偏移，在相同的 `position` 上有多个 X 轴的时候有用。
-注：若未将 `xAxis.axisLine.onZero` 设为 `false` , 则该项无法生效
+X 轴相对于默认位置的偏移，在相同的 `position` 上有多个 X 轴的时候有用。注：若未将 `xAxis.axisLine.onZero` 设为 `false` , 则该项无法生效。
{{ use: axis-common(
prefix = '#',
componentType = 'xAxis',
axisTypeDefault = "'category'",
- hasSplitLineAndArea = true
+ hasSplitLineAndArea = true,
+ hasJitter = true,
+ hasBreakAxis = true
) }}
{{ use: partial-z-zlevel(
diff --git a/zh/option/component/y-axis.md b/zh/option/component/y-axis.md
index 3530f2b6b..54e533dd5 100644
--- a/zh/option/component/y-axis.md
+++ b/zh/option/component/y-axis.md
@@ -118,15 +118,13 @@ y 轴的位置。
+ `'left'`
+ `'right'`
-默认 grid 中的第一个 y 轴在 grid 的左侧（`'left'`），第二个 y 轴视第一个 y 轴的位置放在另一侧。
-注：若未将 `yAxis.axisLine.onZero` 设为 `false` , 则该项无法生效
+默认 grid 中的第一个 y 轴在 grid 的左侧（`'left'`），第二个 y 轴视第一个 y 轴的位置放在另一侧。注：若未将 `yAxis.axisLine.onZero` 设为 `false` , 则该项无法生效。
## offset(number) = 0
-Y 轴相对于默认位置的偏移，在相同的 `position` 上有多个 Y 轴的时候有用。
-注：若未将 `yAxis.axisLine.onZero` 设为 `false` , 则该项无法生效
+Y 轴相对于默认位置的偏移，在相同的 `position` 上有多个 Y 轴的时候有用。注：若未将 `yAxis.axisLine.onZero` 设为 `false` , 则该项无法生效。
需要配合其他配置项共同实现动态排序柱状图效果，具体参见[动态排序柱状图](${handbookPath}how-to/chart-types/bar/bar-race)教程。
@@ -134,7 +132,9 @@ Y 轴相对于默认位置的偏移，在相同的 `position` 上有多个 Y 轴
prefix = '#',
componentType = 'yAxis',
axisTypeDefault = "'value'",
- hasSplitLineAndArea = true
+ hasSplitLineAndArea = true,
+ hasJitter = true,
+ hasBreakAxis = true
) }}
{{ use: partial-z-zlevel(
diff --git a/zh/option/option.md b/zh/option/option.md
index cbb376551..685adc7b5 100644
--- a/zh/option/option.md
+++ b/zh/option/option.md
@@ -23,6 +23,7 @@
{{import: component-graphic}}
{{import: component-calendar}}
{{import: component-matrix}}
+{{import: component-thumbnail}}
{{import: component-dataset}}
{{import: component-aria}}
@@ -163,6 +164,12 @@ ECharts 2 里是底层强制使用单独的层绘制高亮图形，但是会带
注意，这个参数实际影响的是『展示』，而非用户输入的时间值的解析。
关于用户输入的时间值（例如 `1491339540396`, `'2013-01-04'` 等）的解析，参见 [date 中时间相关部分](~series-line.data)。
+注意，如果设置了 `useUTC: true`，并且使用了帮助函数 `echarts.time.format`（或者其他第三方类似函数），它同样要设置成按照 UTC 运作。例如，
+```ts
+// 第三个参数 `true` 表示，按照 UTC 来解释时间。
+const timeStrUTC = echarts.time.format(value, '{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}', true);
+```
+
{{import: partial-rich-inherit-plain-label }}
diff --git a/zh/option/partial/coord-sys.md b/zh/option/partial/coord-sys.md
index c050e0061..60d1a40ae 100644
--- a/zh/option/partial/coord-sys.md
+++ b/zh/option/partial/coord-sys.md
@@ -91,7 +91,7 @@
布局在一个 [矩阵坐标系](~matrix)中。当一个 ECharts 实例中存在多个矩阵坐标系时，须通过 [matrixIndex](~${componentNameInLink}.matrixIndex) 或 [matrixId](~${componentNameInLink}.matrixId) 指定所使用的矩阵坐标系。{{if: ${nonSeriesComponentMainType} === 'grid' }}
- 参见示例 [矩阵坐标系中直角坐标系](${galleryEditorPath}matrix-cartesian-tiny&edit=1&reset=1)。
+ 参见示例 [矩阵坐标系中的微型折线图](${galleryEditorPath}matrix-sparkline&edit=1&reset=1)。
{{ /if }}
{{ /if }}
@@ -159,7 +159,7 @@
此系列或组件作为一个整体，在指定的坐标系中进行布局——即根据坐标系计算整体的包围盒或基础锚点。
- - 例如，[grid 组件](~grid) 可以布局在 [matrix 坐标系](~matrix) 或 [calendar 坐标系](~calendar) 中，这时其布局矩形是由 [${componentNameInLink}.coords](~${componentNameInLink}.coords) 在坐标系中计算出来的。参见示例：[矩阵中的小型直角坐标系](${galleryEditorPath}matrix-cartesian-tiny&edit=1&reset=1)。
+ - 例如，[grid 组件](~grid) 可以布局在 [matrix 坐标系](~matrix) 或 [calendar 坐标系](~calendar) 中，这时其布局矩形是由 [${componentNameInLink}.coords](~${componentNameInLink}.coords) 在坐标系中计算出来的。参见示例：[矩阵中的微型折线图](${galleryEditorPath}matrix-sparkline&edit=1&reset=1)。
- 又如，[饼图系列](~series-pie) 或 [和弦图系列](~series-chord) 可以布局在 [geo 坐标系](~geo) 或 [cartesian2d 坐标系](~grid) 中，这时其中心点是由 [series-pie.coords](~series-pie.coords) 或 [series-pie.center](~series-pie.center) 在坐标系中计算出来的。参见示例：[地理坐标系中的饼图](${galleryEditorPath}map-iceland-pie&edit=1&reset=1)。
{{ if: ${seriesType} }}
@@ -172,13 +172,13 @@
另参考：[${componentNameInLink}.coordinateSystem](~${componentNameInLink}.coordinateSystem)。
-## coord(Array|string)
+## coord(Array|number|string)
{{ use: partial-version(version = ${version|minVersion('6.0.0')}) }}
当 [coordinateSystemUsage](~${componentNameInLink}.coordinateSystemUsage) 为 `'box'` 时, `coord` 被输入给坐标系，计算得到布局位置（布局盒或者中心点）。
-例子：[微型直角坐标系矩阵](${galleryEditorPath}matrix-cartesian-tiny&edit=1&reset=1), [矩阵中的关系图](${galleryEditorPath}doc-example/matrix-graph-box&edit=1&reset=1).
+例子：[矩阵中的微型折线图](${galleryEditorPath}matrix-sparkline&edit=1&reset=1), [矩阵中的关系图](${galleryEditorPath}doc-example/matrix-graph-box&edit=1&reset=1).
{{ if: ${seriesType} === 'pie' }}
在此场景下，[series-pie.center](~series-pie.center) 和 [series-pie.coord](~series-pie.coord) 起同样作用。
@@ -188,6 +188,8 @@
> 注：当 [coordinateSystemUsage](~${componentNameInLink}.coordinateSystemUsage) 为 `'data'` 时，输入给坐标系的是 `series.data[i]` 而非此 `coord`。
+`coord` 的具体格式定义，取决于每个坐标系，并且，和 [chart.convertToPixel](api.html#echartsInstance.convertToPixel) 的第二个参数相同。
+
{{ if: ${cartesian2d} }}
## xAxisIndex(number) = 0
diff --git a/zh/option/partial/matrix-header.md b/zh/option/partial/matrix-header.md
index c25d93bf9..16cf09f96 100644
--- a/zh/option/partial/matrix-header.md
+++ b/zh/option/partial/matrix-header.md
@@ -19,6 +19,8 @@ data: ['A', 'B', 'C', 'D', 'E']
// 或者如果不关心列/行名称，可以直接
data: Array(5).fill(null) // 五列或五行
+// 注：不支持未初始化数组项的数组：
+// data: Array(5) // ❌
// 树状结构的数据
data: [{
@@ -42,6 +44,31 @@ data: [{
}]
```
+如果 [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) 没有提供，它会从 `series.data` 或者 `dataset.source` 中自动收集。
+
+参见 [示例](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1)。
+
+在这种情况下，[series.encode](~series-scatter.encode) 可指定从哪个维度收集数据。例如：
+```js
+var option = {
+ // matrix.x/y.data 没有指定。
+ // 于是从 series.data or dataset.source 收集。
+ matrix: {},
+ series: {
+ type: 'scatter',
+ coordinateSystem: 'matrix',
+ // 指定从 dimension index 为 3 和 2 的列收集数据。
+ encode: {x: 3, y: 2},
+ data: [
+ // 0 1 2 3 (dimension index)
+ [100, 111, 122, 133],
+ [200, 211, 222, 233],
+ ]
+ }
+}
+```
+
+
#### value(string|number)
{{ use: partial-version(version = "6.0.0") }}
@@ -50,7 +77,7 @@ data: [{
#### children(Array)
{{ use: partial-version(version = "6.0.0") }}
-见 [matrix.x/y.data](~matrix.x.data).
+见 [matrix.${matrixDim}.data](~matrix.${matrixDim}.data).
#### size(number)
{{ use: partial-version(version = "6.0.0") }}
diff --git a/zh/option/partial/version.md b/zh/option/partial/version.md
index 8f2d72e37..fbcd0fe5b 100644
--- a/zh/option/partial/version.md
+++ b/zh/option/partial/version.md
@@ -1,7 +1,10 @@
{{ target: partial-version }}
+
+
{{ if: ${deprecated} }}
-> 从 `v${version}` 开始不推荐使用（deprecated）。${deprecated}
+从 `v${version}` 开始不推荐使用（deprecated）。${deprecated}
{{ else }}
-> 从 `v${version}` 开始支持
+从 `v${version}` 开始支持
{{ /if }}
+
diff --git a/zh/option/partial/view-coord-sys.md b/zh/option/partial/view-coord-sys.md
index 0788a6a9c..5c91241d3 100644
--- a/zh/option/partial/view-coord-sys.md
+++ b/zh/option/partial/view-coord-sys.md
@@ -89,6 +89,9 @@ center: ['50%', '50%']
> 百分比字符串从 `v5.3.3` 开始引入。最初是分母是画布的宽高，但这种方式并不合理，因此从 `v6.0.0` 起改为基于包围盒。
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
#${prefix} zoom(number) = 1
@@ -102,6 +105,10 @@ center: ['50%', '50%']
当 [平移缩放（roam）](~${componentNameInLink}.roam) 时，[center](~${componentNameInLink}.center) 和 `zoom` 的值会被相应改变。
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
+
#${prefix} scaleLimit(Object)
{{ use: partial-scale-limit-desc(
@@ -130,12 +137,11 @@ Options:
{{ if: ${supportClip} }}如果 `clip: true`，缩放和平移的触发点是剪裁矩形中的任何地方；否则，触发点是画布中的任何地方。{{ else }}缩放和平移的触发点是画布中的任何地方。{{ /if }}
-{{ if: ${isGeoOrMap} }}
-参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
-{{ /if }}
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
-{{ target: partial-geo-preserve-aspect }}
{{ target: partial-preserve-aspect }}
@@ -168,10 +174,12 @@ Options:
{{ if: ${isGeoOrMap} }}
注意：当使用 [layoutCenter](~${componentNameInLink}.layoutCenter) 和 [layoutSize](~${componentNameInLink}.layoutSize) 时，始终会保留宽高比，无论 `preserveAspect` 配置为何值。
-
-**参见示例：** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
{{ /if }}
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
+
#${prefix} preserveAspectAlign(string) = 'center'
@@ -182,7 +190,9 @@ Options:
参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。
-参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
#${prefix} preserveAspectVerticalAlign(string) = 'middle'
@@ -194,7 +204,20 @@ Options: `'top'` | `'bottom'` | `'middle'`。
参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。
-参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
+{{ use: partial-view-coord-sys-indicator-example-link(
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
+
+{{ target: partial-view-coord-sys-indicator-example-link }}
+
+{{ if: ${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map' }}
+**参考示例**来理解此概念：[geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
+{{ elif: ${componentNameInLink} === 'series-graph' }}
+**参考示例**来理解此概念：[graph roam indicator](${galleryEditorPath}doc-example/graph-roam-indicator&edit=1&reset=1).
+{{ /if }}
+
diff --git a/zh/option/series/bar.md b/zh/option/series/bar.md
index 1ab0bd410..3c88cfed9 100644
--- a/zh/option/series/bar.md
+++ b/zh/option/series/bar.md
@@ -243,6 +243,8 @@ option = {
+ `'seriesAsc'`（默认，系列顺序堆叠）
+ `'seriesDesc'`（反向堆叠）
+**注意：** `stackOrder` 应该为所有具有相同 `stack` 名称的系列定义。如果只为部分系列定义 `stackOrder`，当某些系列被隐藏（如通过图例切换）时，可能会导致堆叠顺序发生意外变化。
+
当前不支持极坐标系。
## sampling(string)
diff --git a/zh/option/series/custom.md b/zh/option/series/custom.md
index 83d71a125..44f126cac 100644
--- a/zh/option/series/custom.md
+++ b/zh/option/series/custom.md
@@ -136,10 +136,10 @@ renderItem 函数的第一个参数，含有：
},
coordSys: {
type: 'calendar',
- x: // {number} calendar rect 的 x
- y: // {number} calendar rect 的 y
- width: // {number} calendar rect 的 width
- height: // {number} calendar rect 的 height
+ x: // {number} calendar 组件 rect 的 x
+ y: // {number} calendar 组件 rect 的 y
+ width: // {number} calendar 组件 rect 的 width
+ height: // {number} calendar 组件 rect 的 height
cellWidth: // {number} calendar cellWidth
cellHeight: // {number} calendar cellHeight
rangeInfo: {
@@ -149,6 +149,13 @@ renderItem 函数的第一个参数，含有：
dayCount: // calendar 日数
}
},
+ coordSys: {
+ type: 'matrix',
+ x: // {number} matrix 组件 rect 的 x
+ y: // {number} matrix 组件 rect 的 y
+ width: // {number} matrix 组件 rect 的 width
+ height: // {number} matrix 组件 rect 的 height
+ },
coordSys: {
type: 'geo',
x: // {number} geo rect 的 x
@@ -194,14 +201,17 @@ renderItem 函数的第二个参数。
##### coord(Function)
-将数据值映射到坐标系上。
+将数据值转换成坐标系的坐标。
-```
-@param {Array.} data 数据值。
-@return {Array.} 画布上的点的坐标，至少包含：[x, y]
- 对于polar坐标系，还会包含其他信息：
- polar: [x, y, radius, angle]
-```
+其行为、输入参数和返回值和 [chart.convertToPixel](api.html#echartsInstance.convertToPixel) 相同（只是去除它的第一个参数 `finder`）。
+
+##### layout(Function)
+
+{{ use: partial-version(version = "6.0.0") }}
+
+将数据值转换成坐标系上的布局信息。
+
+其行为、输入参数和返回值和 [chart.convertToLayout](api.html#echartsInstance.convertToLayout) 相同（只是去除它的第一个参数 `finder`）。
##### size(Function)
diff --git a/zh/option/series/line.md b/zh/option/series/line.md
index 4df15daf9..b45cfc10e 100644
--- a/zh/option/series/line.md
+++ b/zh/option/series/line.md
@@ -119,6 +119,8 @@ const option = {
+ `'seriesAsc'`（默认，系列顺序堆叠）
+ `'seriesDesc'`（反向堆叠）
+**注意：** `stackOrder` 应该为所有具有相同 `stack` 名称的系列定义。如果只为部分系列定义 `stackOrder`，当某些系列被隐藏（如通过图例切换）时，可能会导致堆叠顺序发生意外变化。
+
当前不支持极坐标系。
{{ use: partial-cursor() }}
diff --git a/zh/tutorial/media-query.md b/zh/tutorial/media-query.md
index d5ac8f35d..817100ca2 100644
--- a/zh/tutorial/media-query.md
+++ b/zh/tutorial/media-query.md
@@ -219,7 +219,10 @@ media: [
-
-最后看一个和时间轴结合的例子：
+## 一些示例
+
+使用 [矩阵坐标系进行 grid layout](option.html#matrix) 和 media query:
+
+~[750x500](${galleryViewPath}matrix-grid-layout&edit=1&reset=1)
-~[750x700](${galleryViewPath}doc-example/bar-media-timeline&edit=1&reset=1)
+This is another [media query example](${galleryEditorPath}doc-example/bar-media-timeline&edit=1&reset=1).