This is an automated email from the ASF dual-hosted git repository. sushuang pushed a commit to branch coord-sys-doc-enhancement in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
commit 393ba3ada0b9b7a638139566560fd699812d92b9 Author: 100pah <[email protected]> AuthorDate: Sat Aug 9 18:08:05 2025 +0800 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 [...] -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 [...] +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&e [...] 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' <ExampleUIControlEnum options="left,right,center" default="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' <ExampleUIControlEnum options="left,right,center" default="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 }} + --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
