You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by su...@apache.org on 2025/08/05 19:57:24 UTC
(echarts-doc) 04/04: Add doc for preserveAspect.
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 19fdd60cb99bd98a9cf855512493bf14103d75d0
Author: 100pah <su...@gmail.com>
AuthorDate: Wed Aug 6 03:44:13 2025 +0800
Add doc for preserveAspect.
---
en/option/component/geo-common.md | 32 ++++++++++---
en/option/partial/rect-layout-width-height.md | 20 +++++++-
en/option/partial/rect-layout.md | 68 +++++++++++++++++++++++++--
en/option/partial/view-coord-sys.md | 43 +++++++++++++++++
en/option/series/graph.md | 10 +++-
zh/option/component/geo-common.md | 33 ++++++++++---
zh/option/partial/rect-layout-width-height.md | 20 +++++++-
zh/option/partial/rect-layout.md | 68 +++++++++++++++++++++++++--
zh/option/partial/view-coord-sys.md | 46 ++++++++++++++++++
zh/option/series/graph.md | 10 +++-
10 files changed, 326 insertions(+), 24 deletions(-)
diff --git a/en/option/component/geo-common.md b/en/option/component/geo-common.md
index 3cc37e71..1c422638 100644
--- a/en/option/component/geo-common.md
+++ b/en/option/component/geo-common.md
@@ -3,10 +3,12 @@
{{ if: ${inMap} }}
{{ var: componentNameInLink = 'series-map' }}
+{{ var: componentNameReadable = 'map series' }}
{{ var: componentMainType = 'series' }}
{{ var: componentSubType = 'map' }}
{{ else }}
{{ var: componentNameInLink = 'geo' }}
+{{ var: componentNameReadable = 'geo component' }}
{{ var: componentMainType = 'geo' }}
{{ var: componentSubType = null }}
{{ /if }}
@@ -297,15 +299,17 @@ Map area style in blurred state.
) }}
{{ /if }}
-{{ use: partial-rect-layout(
- prefix = ${prefix}
+{{ use: partial-rect-layout-width-height(
+ prefix = ${prefix},
+ hostName = ${componentNameReadable},
+ hintPreserveAspect = true,
+ hintGeoRectLayoutApproaches = true,
+ componentNameInLink = ${componentNameInLink}
) }}
#${prefix} layoutCenter(Array) = null
-`layoutCenter` and `layoutSize` provides layout strategy other than `left/right/top/bottom/width/height`.
-
-When using `left/right/top/bottom/width/height`, it is hard to put the map inside a box area with a fixed width-height ratio. In this case, `layoutCenter` attribute can be used to define the center position of map, and `layoutSize` can be used to define the size of map. For example:
+`layoutCenter` and `layoutSize` can specify the rectangular area allocated to ${componentNameReadable}, where `layoutCenter` defines the center position of the area, and `layoutSize` defines the size of the area. For example:
```ts
layoutCenter: ['30%', '30%'],
@@ -317,10 +321,26 @@ layoutSize: 100
After setting these two values, `left/right/top/bottom/width/height` becomes invalid.
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = true,
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
#${prefix} layoutSize(number|string)
-Size of map, see `layoutCenter` for more information. Percentage relative to screen width, and absolute pixel values are supported.
+Size of map, see [layoutCenter](${componentNameInLink}.layoutCenter) for more information. Percentage relative to container width/height, and absolute pixel values are supported.
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = true,
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-preserve-aspect(
+ prefix = ${prefix},
+ componentNameReadable = ${componentNameReadable},
+ componentNameInLink = ${componentNameInLink}
+) }}
{{ target: partial-geo-common-state }}
diff --git a/en/option/partial/rect-layout-width-height.md b/en/option/partial/rect-layout-width-height.md
index bdc8ff1c..be3b9f42 100644
--- a/en/option/partial/rect-layout-width-height.md
+++ b/en/option/partial/rect-layout-width-height.md
@@ -15,7 +15,10 @@
defaultLeft = ${defaultLeft},
defaultTop = ${defaultTop},
defaultRight = ${defaultRight},
- defaultBottom = ${defaultBottom}
+ defaultBottom = ${defaultBottom},
+ hintPreserveAspect = ${hintPreserveAspect},
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
) }}
#${prefix|default("#")} width(string|number) = ${defaultWidth|default("'auto'")}
@@ -26,6 +29,14 @@
Width of ${hostNameStr}. {{ if: !${defaultWidth} }}Adaptive by default.{{ /if }}
+`width` can be a pixel value like `20`; it can also be a percentage value relative to the container width like `'20%'`.
+
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
#${prefix|default("#")} height(string|number) = ${defaultHeight|default("'auto'")}
{{ if: ${version} }}
@@ -34,3 +45,10 @@ Width of ${hostNameStr}. {{ if: !${defaultWidth} }}Adaptive by default.{{ /if }}
Height of ${hostNameStr}. {{ if: !${defaultHeight} }}Adaptive by default.{{ /if }}
+`height` can be a pixel value like `20`; it can also be a percentage value relative to the container height like `'20%'`.
+
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
diff --git a/en/option/partial/rect-layout.md b/en/option/partial/rect-layout.md
index 986fa56b..3c1e977d 100644
--- a/en/option/partial/rect-layout.md
+++ b/en/option/partial/rect-layout.md
@@ -23,10 +23,21 @@
Distance between ${hostNameStr} and the left side of the container.
-`left` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`; and it can also be `'left'`, `'center'`, or `'right'`.
+`left` can be a pixel value like `20`; it can also be a percentage value relative to the container width like `'20%'`; and it can also be `'left'`, `'center'`, or `'right'`.
If the `left` value is set to be `'left'`, `'center'`, or `'right'`, then the component will be aligned automatically based on position.
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
#${prefix|default("#")} top(string|number) = ${defaultTop|default("'auto'")}
{{ if: ${version} }}
@@ -35,10 +46,21 @@ If the `left` value is set to be `'left'`, `'center'`, or `'right'`, then the co
Distance between ${hostNameStr} and the top side of the container.
-`top` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`; and it can also be `'top'`, `'middle'`, or `'bottom'`.
+`top` can be a pixel value like `20`; it can also be a percentage value relative to the container height like `'20%'`; and it can also be `'top'`, `'middle'`, or `'bottom'`.
If the `top` value is set to be `'top'`, `'middle'`, or `'bottom'`, then the component will be aligned automatically based on position.
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
#${prefix|default("#")} right(string|number) = ${defaultRight|default("'auto'")}
{{ if: ${version} }}
@@ -47,10 +69,21 @@ If the `top` value is set to be `'top'`, `'middle'`, or `'bottom'`, then the com
Distance between ${hostNameStr} and the right side of the container.
-`right` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`.
+`right` can be a pixel value like `20`; it can also be a percentage value relative to the container width like `'20%'`.
{{ if: !${defaultRight} }}Adaptive by default.{{ /if }}
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
#${prefix|default("#")} bottom(string|number) = ${defaultBottom|default("'auto'")}
{{ if: ${version} }}
@@ -59,7 +92,34 @@ Distance between ${hostNameStr} and the right side of the container.
Distance between ${hostNameStr} and the bottom side of the container.
-`bottom` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`.
+`bottom` can be a pixel value like `20`; it can also be a percentage value relative to the container height like `'20%'`.
{{ if: !${defaultBottom} }}Adaptive by default.{{ /if }}
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
+
+{{ target: partial-preserve-aspect-hint }}
+
+{{ if: ${hintPreserveAspect} && ${componentNameInLink} }}
+> Note: If the graphic elements are unexpectedly distorted, see [preserveAspect](~${componentNameInLink}.preserveAspect).
+{{ /if }}
+
+
+
+{{ target: partial-geo-rect-layout-approaches-hint }}
+
+{{ if: ${hintGeoRectLayoutApproaches} && ${componentNameInLink} }}
+> Note: There are two rectangular layout approaches for ${componentNameInLink}. You can use either one:
+> - [${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height)
+> - [${componentNameInLink}.layoutCenter](~${componentNameInLink}.layoutCenter) / [.layoutSize](~${componentNameInLink}.layoutSize)
+{{ /if }}
diff --git a/en/option/partial/view-coord-sys.md b/en/option/partial/view-coord-sys.md
index 9bb61ee0..0f2ad29f 100644
--- a/en/option/partial/view-coord-sys.md
+++ b/en/option/partial/view-coord-sys.md
@@ -115,3 +115,46 @@ When [roaming](~${componentNameInLink}.roam), the values in [center](~${componen
{{ use: partial-roam-desc() }}
When roaming, the values in [center](~${componentNameInLink}.center) and [zoom](~${componentNameInLink}.zoom) will be modified correspondingly.
+
+
+
+{{ target: partial-preserve-aspect }}
+
+#${prefix} preserveAspect(boolean|string) = ${preserveAspectDefault|default(false)}
+
+<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.
+
+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).
+
+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.
+
+{{ if: (${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map') }}
+Notice: When using [layoutCenter](~${componentNameInLink}.layoutCenter) and [layoutSize](~${componentNameInLink}.layoutSize), the `aspect radio` is always preserved, regardless of this `preserveAspect`.
+{{ /if }}
+
+#${prefix} preserveAspectAlign(string) = 'center'
+
+<ExampleUIControlEnum options="left,right,center" default="center" />
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Options: `'left'` | `'right'` | `'center'`.
+
+See [preserveAspect](~${componentNameInLink}.preserveAspect).
+
+#${prefix} preserveAspectVerticalAlign(string) = 'middle'
+
+<ExampleUIControlEnum options="top,bottom,middle" default="middle" />
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Options: `'top'` | `'bottom'` | `'middle'`.
+
+See [preserveAspect](~${componentNameInLink}.preserveAspect).
diff --git a/en/option/series/graph.md b/en/option/series/graph.md
index 49c1877a..430233f8 100644
--- a/en/option/series/graph.md
+++ b/en/option/series/graph.md
@@ -582,7 +582,15 @@ Alias of [links](~series-graph.links)
defaultLeft = "'center'",
defaultTop = "'middle'",
defaultWidth = 'auto',
- defaultHeight = 'auto'
+ defaultHeight = 'auto',
+ hintPreserveAspect = true,
+ componentNameInLink = 'series-graph'
+) }}
+
+{{ use: partial-preserve-aspect(
+ prefix = '#',
+ componentNameReadable = 'graph series',
+ componentNameInLink = 'series-graph'
) }}
{{ use: partial-silent(
diff --git a/zh/option/component/geo-common.md b/zh/option/component/geo-common.md
index bc4e92e8..0770313f 100644
--- a/zh/option/component/geo-common.md
+++ b/zh/option/component/geo-common.md
@@ -3,10 +3,12 @@
{{ if: ${inMap} }}
{{ var: componentNameInLink = 'series-map' }}
+{{ var: componentNameReadable = '地图系列' }}
{{ var: componentMainType = 'series' }}
{{ var: componentSubType = 'map' }}
{{ else }}
{{ var: componentNameInLink = 'geo' }}
+{{ var: componentNameReadable = 'geo 组件' }}
{{ var: componentMainType = 'geo' }}
{{ var: componentSubType = null }}
{{ /if }}
@@ -293,15 +295,17 @@ boundingCoords: [
) }}
{{ /if }}
-{{ use: partial-rect-layout(
- prefix = ${prefix}
+{{ use: partial-rect-layout-width-height(
+ prefix = ${prefix},
+ hostName = ${componentNameReadable},
+ hintPreserveAspect = true,
+ hintGeoRectLayoutApproaches = true,
+ componentNameInLink = ${componentNameInLink}
) }}
#${prefix} layoutCenter(Array) = null
-`layoutCenter` 和 `layoutSize` 提供了除了 `left/right/top/bottom/width/height` 之外的布局手段。
-
-在使用 `left/right/top/bottom/width/height` 的时候，可能很难在保持地图高宽比的情况下把地图放在某个盒形区域的正中间，并且保证不超出盒形的范围。此时可以通过 `layoutCenter` 属性定义地图中心在屏幕中的位置，`layoutSize` 定义地图的大小。如下示例
+`layoutCenter` 和 `layoutSize` 用于定义 ${componentNameReadable} 所拥有的矩形区域，其中`layoutCenter` 定义了区域中心在容器中的位置，`layoutSize` 定义了区域的大小。如下示例：
```ts
layoutCenter: ['30%', '30%'],
@@ -311,9 +315,26 @@ layoutSize: 100
设置这两个值后 `left/right/top/bottom/width/height` 无效。
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = true,
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
#${prefix} layoutSize(number|string)
-地图的大小，见 `layoutCenter`。支持相对于屏幕宽高的百分比或者绝对的像素大小。
+地图的大小，见 [layoutCenter](${componentNameInLink}.layoutCenter)。支持相对于容器宽高的百分比或者绝对的像素大小。
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = true,
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-preserve-aspect(
+ prefix = ${prefix},
+ componentNameReadable = ${componentNameReadable},
+ componentNameInLink = ${componentNameInLink}
+) }}
diff --git a/zh/option/partial/rect-layout-width-height.md b/zh/option/partial/rect-layout-width-height.md
index 1594075f..392485b4 100644
--- a/zh/option/partial/rect-layout-width-height.md
+++ b/zh/option/partial/rect-layout-width-height.md
@@ -15,7 +15,10 @@
defaultLeft = ${defaultLeft},
defaultTop = ${defaultTop},
defaultRight = ${defaultRight},
- defaultBottom = ${defaultBottom}
+ defaultBottom = ${defaultBottom},
+ hintPreserveAspect = ${hintPreserveAspect},
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
) }}
#${prefix|default("#")} width(string|number) = ${defaultWidth|default("'auto'")}
@@ -28,6 +31,14 @@
${hostNameStr}的宽度。{{ if: !${defaultWidth} }}默认自适应。{{ /if }}
+`width` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器宽度的百分比。
+
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
#${prefix|default("#")} height(string|number) = ${defaultHeight|default("'auto'")}
<ExampleUIControlPercent default="50%"/>
@@ -38,3 +49,10 @@ ${hostNameStr}的宽度。{{ if: !${defaultWidth} }}默认自适应。{{ /if }}
${hostNameStr}的高度。{{ if: !${defaultHeight} }}默认自适应。{{ /if }}
+`height` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器高度的百分比。
+
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
diff --git a/zh/option/partial/rect-layout.md b/zh/option/partial/rect-layout.md
index 987473d1..f73f85b0 100644
--- a/zh/option/partial/rect-layout.md
+++ b/zh/option/partial/rect-layout.md
@@ -25,10 +25,21 @@
${hostNameStr}离容器左侧的距离。
-`left` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器高宽的百分比，也可以是 `'left'`, `'center'`, `'right'`。
+`left` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器宽度的百分比，也可以是 `'left'`, `'center'`, `'right'`。
如果 `left` 的值为 `'left'`, `'center'`, `'right'`，组件会根据相应的位置自动对齐。
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
#${prefix|default("#")} top(string|number) = ${defaultTop|default("'auto'")}
<ExampleUIControlPercent default="0%"/>
@@ -39,10 +50,21 @@ ${hostNameStr}离容器左侧的距离。
${hostNameStr}离容器上侧的距离。
-`top` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器高宽的百分比，也可以是 `'top'`, `'middle'`, `'bottom'`。
+`top` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器高度的百分比，也可以是 `'top'`, `'middle'`, `'bottom'`。
如果 `top` 的值为 `'top'`, `'middle'`, `'bottom'`，组件会根据相应的位置自动对齐。
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
#${prefix|default("#")} right(string|number) = ${defaultRight|default("'auto'")}
<ExampleUIControlPercent default="0%"/>
@@ -53,10 +75,21 @@ ${hostNameStr}离容器上侧的距离。
${hostNameStr}离容器右侧的距离。
-`right` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器高宽的百分比。
+`right` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器宽度的百分比。
{{ if: !${defaultRight} }}默认自适应。{{ /if }}
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
#${prefix|default("#")} bottom(string|number) = ${defaultBottom|default("'auto'")}
<ExampleUIControlPercent default="0%"/>
@@ -67,7 +100,34 @@ ${hostNameStr}离容器右侧的距离。
${hostNameStr}离容器下侧的距离。
-bottom 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器高宽的百分比。
+bottom 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器高度的百分比。
{{ if: !${defaultBottom} }}默认自适应。{{ /if }}
+{{ use: partial-preserve-aspect-hint(
+ hintPreserveAspect = ${hintPreserveAspect},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+{{ use: partial-geo-rect-layout-approaches-hint(
+ hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
+ componentNameInLink = ${componentNameInLink}
+) }}
+
+
+
+{{ target: partial-preserve-aspect-hint }}
+
+{{ if: ${hintPreserveAspect} && ${componentNameInLink} }}
+> 注：如果发现图形被拉伸了不符合预期，参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。
+{{ /if }}
+
+
+
+{{ target: partial-geo-rect-layout-approaches-hint }}
+
+{{ if: ${hintGeoRectLayoutApproaches} && ${componentNameInLink} }}
+> 注：${componentNameInLink} 有两种盒布局方式。你可以使用任一种：
+> - [${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height)
+> - [${componentNameInLink}.layoutCenter](~${componentNameInLink}.layoutCenter) / [.layoutSize](~${componentNameInLink}.layoutSize)
+{{ /if }}
diff --git a/zh/option/partial/view-coord-sys.md b/zh/option/partial/view-coord-sys.md
index 7f8cf045..487b11e2 100644
--- a/zh/option/partial/view-coord-sys.md
+++ b/zh/option/partial/view-coord-sys.md
@@ -114,3 +114,49 @@ center: ['50%', '50%']
{{ use: partial-roam-desc() }}
当缩放和平移时，[center](~${componentNameInLink}.center) 和 [zoom](~${componentNameInLink}.zoom) 的值会被相应改变。
+
+
+
+{{ target: partial-geo-preserve-aspect }}
+
+{{ target: partial-preserve-aspect }}
+
+#${prefix} preserveAspect(boolean|string) = ${preserveAspectDefault|default(false)}
+
+<ExampleUIControlBoolean default="false" />
+
+{{ use: partial-version(version = "6.0.0") }}
+
+`aspect ratio`（宽高比）在此处指的是要渲染的内容的原始包围盒的 `width / height`。
+
+假设为 ${componentNameReadable} 分配的 `矩形区域` 是通过以下配置定义的：
+[${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height)。
+
+`preserveAspect` 的不同选项有如下效果：
+- `null` / `undefined` / `false`（默认）：不会保留宽高比，而是拉伸内容以填满 `${componentNameReadable}矩形区域`。拉伸有可能导致图形失真。
+- `'contain'` / `true`：保留宽高比。内容的包围盒被完整地包含在 `${componentNameReadable}矩形区域` 中，并尽可能放大以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。
+- `'cover'`：保留宽高比。内容的包围盒会覆盖整个 `${componentNameReadable}矩形区域`，并尽可能缩小以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。
+
+{{ if: (${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map') }}
+注意：当使用 [layoutCenter](~${componentNameInLink}.layoutCenter) 和 [layoutSize](~${componentNameInLink}.layoutSize) 时，始终会保留宽高比，无论 `preserveAspect` 配置为何值。
+{{ /if }}
+
+#${prefix} preserveAspectAlign(string) = 'center'
+
+<ExampleUIControlEnum options="left,right,center" default="center" />
+
+{{ use: partial-version(version = "6.0.0") }}
+
+可选项：`'left'` | `'right'` | `'center'`。
+
+参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。
+
+#${prefix} preserveAspectVerticalAlign(string) = 'middle'
+
+<ExampleUIControlEnum options="top,bottom,middle" default="middle" />
+
+{{ use: partial-version(version = "6.0.0") }}
+
+Options: `'top'` | `'bottom'` | `'middle'`。
+
+参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。
diff --git a/zh/option/series/graph.md b/zh/option/series/graph.md
index 460e1fb0..e5a0fa4a 100644
--- a/zh/option/series/graph.md
+++ b/zh/option/series/graph.md
@@ -619,7 +619,15 @@ links: [{
defaultLeft = "'center'",
defaultTop = "'middle'",
defaultWidth = '自适应',
- defaultHeight = '自适应'
+ defaultHeight = '自适应',
+ hintPreserveAspect = true,
+ componentNameInLink = 'series-graph'
+) }}
+
+{{ use: partial-preserve-aspect(
+ prefix = '#',
+ componentNameReadable = 'graph 系列',
+ componentNameInLink = 'series-graph'
) }}
{{ use: partial-silent(
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org