apache · 100pah · Aug 6, 2025 · Aug 5, 2025 · Aug 5, 2025 · Aug 5, 2025
diff --git a/README.md b/README.md
@@ -43,7 +43,7 @@ module.exports = {
 ```
 
 
-## Tips About Writing Doc
+## Tips for Writing Doc
 
 ### "Since Version"
 "Since Version" is necessary in doc.

diff --git a/en/api/echarts.md b/en/api/echarts.md
@@ -159,49 +159,86 @@ Registers available maps. This can only be used after including [geo](option.htm
 
 Please refer to [option.geo](option.html#geo.map) for usage.
 
-**Parameters**
-+ `mapName`
+**Parameters:**
++ **@param `mapName`:**
 
     Map name, referring to `map` value set in [geo](option.html#geo) component or [map](option.html#series-map).
 
-+ `opt`
++ **@param `opt.geoJSON`:**
 
-    + `geoJSON` Optional. Data in GeoJson format. See [https://geojson.org/](https://geojson.org/) for more format information. Can be a JSON string or a parsed object. This key can also be `geoJson`.
+    Optional. Data in GeoJSON format. See [https://geojson.org/](https://geojson.org/) for more format information. Can be a JSON string or a parsed object. This key can also be `geoJson`.
 
-    + `svg` Optional. Data in SVG format. Can be a SVG string or a parsed SVG DOM object. See more info in [SVG Base Map](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20SeriesSVG%20Base%20Map). Introduced in v5.1.0
+    For example, A minimal geoJSON:
+    ```ts
+    const geoJSONSample = {
+        "type": "FeatureCollection",
+        "features": [
+            {
+                "type": "Feature",
+                "geometry": {
+                    "type": "Polygon",
+                    "coordinates": [
+                        [[200, 3000], [500, 3000], [500, 5000], [200, 5000]]
+                    ]
+                },
+                "properties": {
+                    "name": "Some Place",
+                    "cp": [220, 2100]
+                }
+            }
+        ]
+    };
+    echarts.registerMap('my_geo_sample', {geoJSON: geoJSONSample});
+    ```
+    Note:
+    + `features[i].properties.name` in GeoJSON is required by ECharts to query the corresponding region, or display the label. Property `name` is used by default, but can also be other properties, see [geo.nameProperty](option.html#geo.nameProperty).
+    + `features[i].properties.cp` is an optional property that ECharts can recoganize. It provides coordinates on which the label can be displayed. If not provided, the label will be displayed at the center of the region.
 
-    + `specialAreas` Optional. zoomed part of a specific area in the map for better visual effect. Only work for `geoJSON`.
++ **@param `opt.svg`:**
 
-**For example [USA Population Estimates](${galleryEditorPath}map-usa): **
-```ts
-echarts.registerMap('USA', usaJson, {
-    // Move Alaska to the bottom left of United States
-    Alaska: {
-        // Upper left longitude
-        left: -131,
-        // Upper left latitude
-        top: 25,
-        // Range of longitude
-        width: 15
-    },
-    // Hawaii
-    Hawaii: {
-        left: -110,
-        top: 28,
-        width: 5
-    },
-    // Puerto Rico
-    'Puerto Rico': {
-        left: -76,
-        top: 26,
-        width: 2
-    }
-});
-```
+    Optional. Data in SVG format. Can be a SVG string or a parsed SVG DOM object. See more info in [SVG Base Map](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20SeriesSVG%20Base%20Map). Introduced in `v5.1.0`.
 
-Note:
+    For example, A minimal SVG:
+    ```ts
+    const mySVG = `<?xml version="1.0" encoding="utf-8"?>
+    <svg xmlns="http://www.w3.org/2000/svg" xmlns:ooo="http://xml.openoffice.org/svg/export" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2" fill-rule="evenodd" xml:space="preserve">
+    <path name="left_rect" d="M 0,0 L 0,100 100,100 100,0 Z" fill="#765" stroke="rgb(56,93,138)" stroke-width="0" stroke-linecap="square" stroke-linejoin="miter"/>
+    </svg>`;
+    echarts.registerMap('my_geo_sample', {svg: mySVG});
+    ```
+
++ **@param `opt.specialAreas`:**
+
+    Optional. zoomed part of a specific area in the map for better visual effect. Only work for `geoJSON`.
+
+    **[An example of specialAreas](${galleryEditorPath}map-usa): **
+    ```ts
+    echarts.registerMap('USA', usaJson, {
+        // Move Alaska to the bottom left of United States
+        Alaska: {
+            // Upper left longitude
+            left: -131,
+            // Upper left latitude
+            top: 25,
+            // Range of longitude
+            width: 15
+        },
+        // Hawaii
+        Hawaii: {
+            left: -110,
+            top: 28,
+            width: 5
+        },
+        // Puerto Rico
+        'Puerto Rico': {
+            left: -76,
+            top: 26,
+            width: 2
+        }
+    });
+    ```
 
-If you only import the required components in your project, starting from v5.3.0 `registerMap` has to be used after the `MapChart` or `GeoComponent` is imported.
+Note: If you only import the required components in your project, starting from v5.3.0 `registerMap` cannot be called unless `MapChart` or `GeoComponent` is imported (ES module import).
 
 ## getMap(Function)
 ```ts

diff --git 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
@@ -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 }}
@@ -165,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
 ) }}
 
 
@@ -297,15 +300,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 +322,40 @@ 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}
+) }}
+
+#${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
@@ -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/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
@@ -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 }}