From 393ba3ada0b9b7a638139566560fd699812d92b9 Mon Sep 17 00:00:00 2001 From: 100pah Date: Sat, 9 Aug 2025 18:08:05 +0800 Subject: [PATCH 1/3] Enhance coord sys doc. --- en/option/component/matrix.md | 14 +++++++---- en/option/partial/coord-sys.md | 6 ++--- en/option/partial/matrix-header.md | 28 ++++++++++++++++++++- en/option/partial/view-coord-sys.md | 39 +++++++++++++++++++++++------ zh/option/component/matrix.md | 15 ++++++++--- zh/option/partial/coord-sys.md | 6 ++--- zh/option/partial/matrix-header.md | 29 ++++++++++++++++++++- zh/option/partial/view-coord-sys.md | 39 +++++++++++++++++++++++------ 8 files changed, 145 insertions(+), 31 deletions(-) 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/partial/coord-sys.md b/en/option/partial/coord-sys.md index 4efbf8d7..2bc78ff9 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} }} @@ -175,7 +175,7 @@ See also [${componentNameInLink}.coordinateSystem](~${componentNameInLink}.coord 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. 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/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/partial/coord-sys.md b/zh/option/partial/coord-sys.md index c050e006..88d46995 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} }} @@ -178,7 +178,7 @@ 当 [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) 起同样作用。 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 }} + From 4c36a0b01bd78019ee5cbfa58326e52486ca1d92 Mon Sep 17 00:00:00 2001 From: 100pah Date: Sun, 10 Aug 2025 19:31:48 +0800 Subject: [PATCH 2/3] Supplement coord sys related API doc, custom series doc, media query doc. --- README.md | 13 +- en/api/echarts-instance.md | 436 ++++++++++++++++++++++++++------- en/option/partial/coord-sys.md | 4 +- en/option/series/custom.md | 30 ++- en/tutorial/media-query.md | 12 +- zh/api/echarts-instance.md | 429 +++++++++++++++++++++++++------- zh/option/partial/coord-sys.md | 4 +- zh/option/series/custom.md | 30 ++- zh/tutorial/media-query.md | 9 +- 9 files changed, 758 insertions(+), 209 deletions(-) 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..fccadb2d 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,295 @@ 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 cooridinate system (cartesian, geo, graph, ...) that contains the given series, convert a point to pixel coordinate: + 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) ```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 +816,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 +837,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 +971,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/partial/coord-sys.md b/en/option/partial/coord-sys.md index 2bc78ff9..c7fabb17 100644 --- a/en/option/partial/coord-sys.md +++ b/en/option/partial/coord-sys.md @@ -169,7 +169,7 @@ 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')}) }} @@ -185,6 +185,8 @@ Examples: [sparkline in matrix](${galleryEditorPath}matrix-sparkline&edit=1&rese > 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/series/custom.md b/en/option/series/custom.md index d9fbfa91..12dbd7a3 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,15 @@ 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) + +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..c3989d1d 100644 --- a/zh/api/echarts-instance.md +++ b/zh/api/echarts-instance.md @@ -513,124 +513,296 @@ 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。 + ``` -在某个系列所在的坐标系（无论是 cartesian、geo、graph 等）中，转换某点成像素坐标： ++ [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) ```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 +812,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 +832,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 +966,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/partial/coord-sys.md b/zh/option/partial/coord-sys.md index 88d46995..60d1a40a 100644 --- a/zh/option/partial/coord-sys.md +++ b/zh/option/partial/coord-sys.md @@ -172,7 +172,7 @@ 另参考：[${componentNameInLink}.coordinateSystem](~${componentNameInLink}.coordinateSystem)。 -## coord(Array|string) +## coord(Array|number|string) {{ use: partial-version(version = ${version|minVersion('6.0.0')}) }} @@ -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/series/custom.md b/zh/option/series/custom.md index 83d71a12..59218a85 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,15 @@ 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) + +将数据值转换成坐标系上的布局信息。 + +其行为、输入参数和返回值和 [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). From fa0989bda874c555256348d43d6b24d6a3a37d4d Mon Sep 17 00:00:00 2001 From: 100pah Date: Sun, 10 Aug 2025 21:11:46 +0800 Subject: [PATCH 3/3] Add thumbnail component doc. --- en/api/echarts-instance.md | 3 ++ en/option/component/thumbnail.md | 76 ++++++++++++++++++++++++++++++++ en/option/option.md | 1 + en/option/series/custom.md | 2 + zh/api/echarts-instance.md | 3 ++ zh/option/component/thumbnail.md | 75 +++++++++++++++++++++++++++++++ zh/option/option.md | 1 + zh/option/series/custom.md | 2 + 8 files changed, 163 insertions(+) create mode 100644 en/option/component/thumbnail.md create mode 100644 zh/option/component/thumbnail.md diff --git a/en/api/echarts-instance.md b/en/api/echarts-instance.md index fccadb2d..8fdf936f 100644 --- a/en/api/echarts-instance.md +++ b/en/api/echarts-instance.md @@ -676,6 +676,9 @@ The format of the input `coord` and return type are defined by each coordinate s ## convertToLayout(Function) + +{{ use: partial-version(version = "6.0.0") }} + ```ts ( // `finder` is used to indicate in which coordinate system 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/series/custom.md b/en/option/series/custom.md index 12dbd7a3..2e78e1de 100644 --- a/en/option/series/custom.md +++ b/en/option/series/custom.md @@ -218,6 +218,8 @@ The behavior, parameters and returns are the same as [chart.convertToPixel](api. ##### 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`). diff --git a/zh/api/echarts-instance.md b/zh/api/echarts-instance.md index c3989d1d..6d29d74b 100644 --- a/zh/api/echarts-instance.md +++ b/zh/api/echarts-instance.md @@ -679,6 +679,9 @@ ECharts 中的事件有两种，一种是鼠标事件，在鼠标点击某个图 ## convertToLayout(Function) + +{{ use: partial-version(version = "6.0.0") }} + ```ts ( // `finder` 用于指示『使用哪个坐标系或数轴或系列进行转换』。 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/series/custom.md b/zh/option/series/custom.md index 59218a85..44f126ca 100644 --- a/zh/option/series/custom.md +++ b/zh/option/series/custom.md @@ -207,6 +207,8 @@ renderItem 函数的第二个参数。 ##### layout(Function) +{{ use: partial-version(version = "6.0.0") }} + 将数据值转换成坐标系上的布局信息。 其行为、输入参数和返回值和 [chart.convertToLayout](api.html#echartsInstance.convertToLayout) 相同（只是去除它的第一个参数 `finder`）。