diff --git a/README.md b/README.md
index 62eb35bc..f8ce8fe0 100644
--- a/README.md
+++ b/README.md
@@ -63,21 +63,24 @@ These global variables can be used in doc:
+ `${galleryViewPath}`
+ `${galleryEditorPath}`
+ `${websitePath}`
++ `${handbookPath}`
+
+Note: All of them are ended with a `/`, therefore, use them like `${galleryEditorPath}pie-legend`.
See samples in "Reference of echarts-examples or other links"
### Reference of echarts-examples or Other Links
-Embed an example in doc:
+Embed an example in doc (display the example directly in doc with an iframe. To avoid performance issues, do not overuse it.):
```md
-~[700X300](${galleryEditorPath}pie-legend&edit=1&reset=1)
+~[700X300](${galleryViewPath}pie-legend&edit=1&reset=1)
~[700x300](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
```
Provide an example link in doc:
```md
[vertically scrollable legend](${galleryEditorPath}pie-legend&edit=1&reset=1)
-[aria pie](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
+[aria pie](${galleryEditorPath}doc-example/aria-pie&edit=1&reset=1)
```
Provide a website link in doc:
@@ -94,8 +97,10 @@ A `~` can be used to refer to a option item in the same doc. For example:
If intending to reference an anchor in different doc, it can be:
```md
-In api.html, reference
[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)
```
diff --git a/en/api/echarts-instance.md b/en/api/echarts-instance.md
index 57c250be..8fdf936f 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.
@@ -518,128 +518,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):
-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]);
-```
+ 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](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20Series)), 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]);
+ ```
+
+
+## convertToLayout(Function)
+
+{{ use: partial-version(version = "6.0.0") }}
-In a cooridinate 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.
-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 +819,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 +840,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 +974,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/option/component/matrix.md b/en/option/component/matrix.md
index 418fa205..1a2babc3 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 00000000..dd210ff2
--- /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/option.md b/en/option/option.md
index 64f11bfe..2e867780 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}}
diff --git a/en/option/partial/coord-sys.md b/en/option/partial/coord-sys.md
index 4efbf8d7..c7fabb17 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 ac5dc1d9..cc1aeed2 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/view-coord-sys.md b/en/option/partial/view-coord-sys.md
index 99bdbf50..f1984c22 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/custom.md b/en/option/series/custom.md
index d9fbfa91..2e78e1de 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/tutorial/media-query.md b/en/tutorial/media-query.md
index 6d5da12d..4e3b6faa 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/zh/api/echarts-instance.md b/zh/api/echarts-instance.md
index c1a60d4d..6d29d74b 100644
--- a/zh/api/echarts-instance.md
+++ b/zh/api/echarts-instance.md
@@ -513,124 +513,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](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20Series) 中的 “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 +815,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 +835,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 +969,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/option/component/matrix.md b/zh/option/component/matrix.md
index c6a57b8d..ff9d05fe 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 00000000..5dff544f
--- /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/option.md b/zh/option/option.md
index cbb37655..77048280 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}}
diff --git a/zh/option/partial/coord-sys.md b/zh/option/partial/coord-sys.md
index c050e006..60d1a40a 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 c25d93bf..16cf09f9 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/view-coord-sys.md b/zh/option/partial/view-coord-sys.md
index 0788a6a9..5c91241d 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/custom.md b/zh/option/series/custom.md
index 83d71a12..44f126ca 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/tutorial/media-query.md b/zh/tutorial/media-query.md
index d5ac8f35..817100ca 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).