This is an automated email from the ASF dual-hosted git repository. sushuang pushed a commit to branch v6-doc-supplement-2 in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
commit 9328d92d2ac83f2b7250a0dde44c032080a69d1d Author: 100pah <[email protected]> AuthorDate: Thu Aug 7 06:21:20 2025 +0800 Add doc geo.clip and roamTrigger. --- en/option/component/axis-common.md | 2 ++ en/option/component/geo-common.md | 17 ++++++++++- en/option/partial/coord-sys.md | 2 +- en/option/partial/view-coord-sys.md | 53 +++++++++++++++++++++++++++++++---- en/option/series/sankey.md | 3 +- en/option/series/tree.md | 3 +- zh/option/component/axis-common.md | 2 ++ zh/option/component/geo-common.md | 16 ++++++++++- zh/option/partial/coord-sys.md | 2 +- zh/option/partial/view-coord-sys.md | 56 ++++++++++++++++++++++++++++++++----- zh/option/series/sankey.md | 3 +- zh/option/series/tree.md | 3 +- 12 files changed, 141 insertions(+), 21 deletions(-) diff --git a/en/option/component/axis-common.md b/en/option/component/axis-common.md index 41482796..8642911f 100644 --- a/en/option/component/axis-common.md +++ b/en/option/component/axis-common.md @@ -654,6 +654,8 @@ The content displayed at the end of the text after truncation. {{ if: ${componentType} === 'xAxis' || ${componentType} === 'yAxis' }} #${prefix} nameMoveOverlap(boolean) = true +<ExampleUIControlBoolean default="true"/> + {{ use: partial-version(version = "6.0.0") }} Whether to move axis name to avoid overlap with axis labels. diff --git a/en/option/component/geo-common.md b/en/option/component/geo-common.md index 1c422638..5337e181 100644 --- a/en/option/component/geo-common.md +++ b/en/option/component/geo-common.md @@ -167,7 +167,8 @@ Note: `stream` is not required in the `projection`. {{ use: partial-view-coord-sys-common( prefix = ${prefix}, componentMainType = ${componentMainType}, - componentSubType = ${componentSubType} + componentSubType = ${componentSubType}, + supportClip = true ) }} @@ -342,6 +343,20 @@ Size of map, see [layoutCenter](${componentNameInLink}.layoutCenter) for more in componentNameInLink = ${componentNameInLink} ) }} +#${prefix} clip(boolean) = false + +{{ use: partial-version(version = "6.0.0") }} + +{{ use: partial-view-coord-sys-allocated-rect-desc( + componentNameReadable = ${componentNameReadable}, + componentNameInLink = ${componentNameInLink}, + isGeoOrMap = true +) }} + +`clip` specifies whether to hide the outside part of the map with respect to the allocated rect. + +**See example:** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1). + {{ target: partial-geo-common-state }} diff --git a/en/option/partial/coord-sys.md b/en/option/partial/coord-sys.md index 3b4eebbc..4efbf8d7 100644 --- a/en/option/partial/coord-sys.md +++ b/en/option/partial/coord-sys.md @@ -276,7 +276,7 @@ When `geoIndex` or `geoId` is specified, [series-map.map](~series-map.map) other ## geoId(number) = undefined {{ if: ${version} }} -{{ use: partial-version(version = ${version}) }} +{{ use: partial-version(version = ${version|minVersion('6.0.0')}) }} {{ /if }} The id of the [geographic coordinate system](~geo) to base on. When mutiple `geographic` exist within an ECharts instance, use this to specify the corresponding `geographic`. diff --git a/en/option/partial/view-coord-sys.md b/en/option/partial/view-coord-sys.md index 0f2ad29f..99bdbf50 100644 --- a/en/option/partial/view-coord-sys.md +++ b/en/option/partial/view-coord-sys.md @@ -116,27 +116,58 @@ When [roaming](~${componentNameInLink}.roam), the values in [center](~${componen When roaming, the values in [center](~${componentNameInLink}.center) and [zoom](~${componentNameInLink}.zoom) will be modified correspondingly. +#${prefix} roamTrigger(string) = ${roamTriggerDefault|default("'selfRect'")} +{{ use: partial-version(version = "6.0.0") }} + +[Roaming](~${componentNameInLink}.roam) can be triggered by mouse dragging or mouse wheel. + +Options: +- `'selfRect'`: + + The roaming can only be triggered on the bounding rect of the graphic elements. + +- `'global'`: + + {{ 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 }} {{ target: partial-preserve-aspect }} #${prefix} preserveAspect(boolean|string) = ${preserveAspectDefault|default(false)} +{{ if: ${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map' }} +{{ var: isGeoOrMap = true }} +{{ /if }} + <ExampleUIControlBoolean default="false" /> {{ use: partial-version(version = "6.0.0") }} -`aspect ratio` here refers to `width / height` of the original bounding rect of the content to be rendered. +`aspect ratio` here refers to `width / height`. -Suppose a `rectangular area` allocated to `${componentNameReadable}` is defined by [${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height). +"preserve aspect" refers whether to preserve the `aspect ratio` of the original bounding rect of the content to be rendered. + +{{ use: partial-view-coord-sys-allocated-rect-desc( + componentNameReadable = ${componentNameReadable}, + componentNameInLink = ${componentNameInLink}, + isGeoOrMap = ${isGeoOrMap} +) }} + +But the `aspect ratio` of this rectangle may not match that of the content's original bounding rect, which may cause distortion. Options of `preserveAspect`: -- `null`/`undefined`/`false` (default): `aspect ratio` will not be preserved, but stretched to fill the `${componentNameReadable} rectangular area`, which may cause distortion. -- `'contain'`/`true`: The `aspect ratio` is preserved; the bounding rect of the content are fully contained by the `${componentNameReadable} rectangular area`, and scaled up as much as possible to meet the `${componentNameReadable} rectangular area`. [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) and [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) can be used to adjust the position in this case. -- `'cover'`: The `aspect ratio` is preserved; the bounding rect of the content covers the `${componentNameReadable} rectangular area`, and scaled down as much as possible to meet the `${componentNameReadable} rectangular area`. [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) and [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) can be used to adjust the position in this case. +- `null`/`undefined`/`false` (default): The original `aspect ratio` of the content will not be preserved, but stretched to fill the `${componentNameReadable} rectangular area`, which may cause distortion. +- `'contain'`/`true`: The original `aspect ratio` of the content is preserved; the bounding rect of the content are fully contained by the `${componentNameReadable} rectangular area`, and scaled up as much as possible to meet the `${componentNameReadable} rectangular area`. [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) and [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) can be used to adjust the position in this case. +- `'cover'`: The original `aspect ratio` of the content is preserved; the bounding rect of the content covers the `${componentNameReadable} rectangular area`, and scaled down as much as possible to meet the `${componentNameReadable} rectangular area`. [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) and [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) can be used to adjust the position in this case. -{{ if: (${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map') }} +{{ 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 }} #${prefix} preserveAspectAlign(string) = 'center' @@ -149,6 +180,8 @@ Options: `'left'` | `'right'` | `'center'`. See [preserveAspect](~${componentNameInLink}.preserveAspect). +See example [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1). + #${prefix} preserveAspectVerticalAlign(string) = 'middle' <ExampleUIControlEnum options="top,bottom,middle" default="middle" /> @@ -158,3 +191,11 @@ See [preserveAspect](~${componentNameInLink}.preserveAspect). Options: `'top'` | `'bottom'` | `'middle'`. See [preserveAspect](~${componentNameInLink}.preserveAspect). + +See example [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1). + + + +{{ target: partial-view-coord-sys-allocated-rect-desc }} + +A `rectangular area` allocated to `${componentNameReadable}` is determined by [${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height){{ if: ${isGeoOrMap} }} / [.aspectScale](~${componentNameInLink}.aspectScale){{ /if }}. \ No newline at end of file diff --git a/en/option/series/sankey.md b/en/option/series/sankey.md index 399c898e..16d0b10b 100644 --- a/en/option/series/sankey.md +++ b/en/option/series/sankey.md @@ -95,7 +95,8 @@ The drag-and-drop interaction of the node, which is enabled by default. After op {{ use: partial-view-coord-sys-common( prefix = '#', componentMainType = 'series', - componentSubType = 'sankey' + componentSubType = 'sankey', + roamTriggerDefault = "'global'", ) }} diff --git a/en/option/series/tree.md b/en/option/series/tree.md index 06856bdf..83c5fde1 100644 --- a/en/option/series/tree.md +++ b/en/option/series/tree.md @@ -48,7 +48,8 @@ The tree diagram is mainly used to visualize the tree data structure, which is a {{ use: partial-view-coord-sys-common( prefix = '#', componentMainType = 'series', - componentSubType = 'tree' + componentSubType = 'tree', + roamTriggerDefault = "'global'" ) }} diff --git a/zh/option/component/axis-common.md b/zh/option/component/axis-common.md index d17e064d..a1904f0f 100644 --- a/zh/option/component/axis-common.md +++ b/zh/option/component/axis-common.md @@ -650,6 +650,8 @@ splitLine: { {{ if: ${componentType} === 'xAxis' || ${componentType} === 'yAxis' }} #${prefix} nameMoveOverlap(boolean) = true +<ExampleUIControlBoolean default="true"/> + {{ use: partial-version(version = "6.0.0") }} 当 axis name 和 axis label 重叠时，是否自动移动 axis name 来避免重叠。 diff --git a/zh/option/component/geo-common.md b/zh/option/component/geo-common.md index 0770313f..67cb49a8 100644 --- a/zh/option/component/geo-common.md +++ b/zh/option/component/geo-common.md @@ -165,7 +165,8 @@ series: { {{ use: partial-view-coord-sys-common( prefix = ${prefix}, componentMainType = ${componentMainType}, - componentSubType = ${componentSubType} + componentSubType = ${componentSubType}, + supportClip = true ) }} @@ -336,6 +337,19 @@ layoutSize: 100 componentNameInLink = ${componentNameInLink} ) }} +#${prefix} clip(boolean) = false + +{{ use: partial-version(version = "6.0.0") }} + +{{ use: partial-view-coord-sys-allocated-rect-desc( + componentNameReadable = ${componentNameReadable}, + componentNameInLink = ${componentNameInLink}, + isGeoOrMap = true +) }} + +当地图超出这个分配的矩形区域时，`clip` 决定了是否剪裁超出部分。 + +**参见示例：** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1). {{ target: partial-geo-common-state }} diff --git a/zh/option/partial/coord-sys.md b/zh/option/partial/coord-sys.md index ea32c5c7..c050e006 100644 --- a/zh/option/partial/coord-sys.md +++ b/zh/option/partial/coord-sys.md @@ -279,7 +279,7 @@ ## geoId(number) = undefined {{ if: ${version} }} -{{ use: partial-version(version = ${version}) }} +{{ use: partial-version(version = ${version|minVersion('6.0.0')}) }} {{ /if }} 布局时所基于的 [地理坐标系](~geo) 的 id。当一个 ECharts 实例中存在多个地理坐标系时，用其指定所使用的坐标系。 diff --git a/zh/option/partial/view-coord-sys.md b/zh/option/partial/view-coord-sys.md index 487b11e2..0788a6a9 100644 --- a/zh/option/partial/view-coord-sys.md +++ b/zh/option/partial/view-coord-sys.md @@ -115,6 +115,24 @@ center: ['50%', '50%'] 当缩放和平移时，[center](~${componentNameInLink}.center) 和 [zoom](~${componentNameInLink}.zoom) 的值会被相应改变。 +#${prefix} roamTrigger(string) = ${roamTriggerDefault|default("'selfRect'")} + +{{ use: partial-version(version = "6.0.0") }} + +[缩放和平移（roam）](~${componentNameInLink}.roam) 可被鼠标触发。 + +Options: +- `'selfRect'`: + + 缩放和平移的触发点只能是图形元素形成的包围盒中。 + +- `'global'`: + + {{ if: ${supportClip} }}如果 `clip: true`，缩放和平移的触发点是剪裁矩形中的任何地方；否则，触发点是画布中的任何地方。{{ else }}缩放和平移的触发点是画布中的任何地方。{{ /if }} + +{{ if: ${isGeoOrMap} }} +参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1). +{{ /if }} {{ target: partial-geo-preserve-aspect }} @@ -123,22 +141,35 @@ center: ['50%', '50%'] #${prefix} preserveAspect(boolean|string) = ${preserveAspectDefault|default(false)} +{{ if: ${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map' }} +{{ var: isGeoOrMap = true }} +{{ /if }} + <ExampleUIControlBoolean default="false" /> {{ use: partial-version(version = "6.0.0") }} -`aspect ratio`（宽高比）在此处指的是要渲染的内容的原始包围盒的 `width / height`。 +`aspect ratio` 指 `width / height`。 + +"preserve aspect" 指是否要保持被渲染的内容的原始包围盒的 `aspect ratio`。 + +{{ use: partial-view-coord-sys-allocated-rect-desc( + componentNameReadable = ${componentNameReadable}, + componentNameInLink = ${componentNameInLink}, + isGeoOrMap = ${isGeoOrMap} +) }} -假设为 ${componentNameReadable} 分配的 `矩形区域` 是通过以下配置定义的： -[${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height)。 +但是这个矩形的 `aspect ratio` 不一定和内容的原始 `aspect ratio` 一致，从而可能导致内容被拉伸而失真。 `preserveAspect` 的不同选项有如下效果： -- `null` / `undefined` / `false`（默认）：不会保留宽高比，而是拉伸内容以填满 `${componentNameReadable}矩形区域`。拉伸有可能导致图形失真。 -- `'contain'` / `true`：保留宽高比。内容的包围盒被完整地包含在 `${componentNameReadable}矩形区域` 中，并尽可能放大以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。 -- `'cover'`：保留宽高比。内容的包围盒会覆盖整个 `${componentNameReadable}矩形区域`，并尽可能缩小以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。 +- `null` / `undefined` / `false`（默认）：不会保持内容的原始 `aspect ratio`，而是拉伸内容以填满 `${componentNameReadable}矩形区域`。拉伸有可能导致图形失真。 +- `'contain'` / `true`：保持内容的 `aspect ratio`。内容的包围盒被完整地包含在 `${componentNameReadable}矩形区域` 中，并尽可能放大以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。 +- `'cover'`：保持内容的原始 `aspect ratio`。内容的包围盒会覆盖整个 `${componentNameReadable}矩形区域`，并尽可能缩小以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。 -{{ if: (${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map') }} +{{ if: ${isGeoOrMap} }} 注意：当使用 [layoutCenter](~${componentNameInLink}.layoutCenter) 和 [layoutSize](~${componentNameInLink}.layoutSize) 时，始终会保留宽高比，无论 `preserveAspect` 配置为何值。 + +**参见示例：** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1). {{ /if }} #${prefix} preserveAspectAlign(string) = 'center' @@ -151,6 +182,8 @@ center: ['50%', '50%'] 参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。 +参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1). + #${prefix} preserveAspectVerticalAlign(string) = 'middle' <ExampleUIControlEnum options="top,bottom,middle" default="middle" /> @@ -160,3 +193,12 @@ center: ['50%', '50%'] Options: `'top'` | `'bottom'` | `'middle'`。 参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。 + +参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1). + + + +{{ target: partial-view-coord-sys-allocated-rect-desc }} + +为 ${componentNameReadable} 分配的 `矩形区域` 是通过以下配置决定的： +[${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height){{ if: ${isGeoOrMap} }} / [.aspectScale](~${componentNameInLink}.aspectScale){{ /if }}。 diff --git a/zh/option/series/sankey.md b/zh/option/series/sankey.md index ed6da977..01632a44 100644 --- a/zh/option/series/sankey.md +++ b/zh/option/series/sankey.md @@ -98,7 +98,8 @@ const option = {"tooltip":{"trigger":"item","triggerOn":"mousemove"},"series":[{ {{ use: partial-view-coord-sys-common( prefix = '#', componentMainType = 'series', - componentSubType = 'sankey' + componentSubType = 'sankey', + roamTriggerDefault = "'global'" ) }} diff --git a/zh/option/series/tree.md b/zh/option/series/tree.md index f0f77155..5777251c 100644 --- a/zh/option/series/tree.md +++ b/zh/option/series/tree.md @@ -91,7 +91,8 @@ const option = { {{ use: partial-view-coord-sys-common( prefix = '#', componentMainType = 'series', - componentSubType = 'tree' + componentSubType = 'tree', + roamTriggerDefault = "'global'" ) }} --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
