Skip to content

Commit 9328d92

Browse files
100pah100pah
committed
Add doc geo.clip and roamTrigger.
1 parent 5c870a4 commit 9328d92

12 files changed

Lines changed: 141 additions & 21 deletions

File tree

‎en/option/component/axis-common.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -654,6 +654,8 @@ The content displayed at the end of the text after truncation.
654654
{{ if: ${componentType} === 'xAxis' || ${componentType} === 'yAxis' }}
655655
#${prefix} nameMoveOverlap(boolean) = true
656656

657+
<ExampleUIControlBoolean default="true"/>
658+
657659
{{ use: partial-version(version = "6.0.0") }}
658660

659661
Whether to move axis name to avoid overlap with axis labels.

‎en/option/component/geo-common.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,8 @@ Note: `stream` is not required in the `projection`.
167167
{{ use: partial-view-coord-sys-common(
168168
prefix = ${prefix},
169169
componentMainType = ${componentMainType},
170-
componentSubType = ${componentSubType}
170+
componentSubType = ${componentSubType},
171+
supportClip = true
171172
) }}
172173

173174

@@ -342,6 +343,20 @@ Size of map, see [layoutCenter](${componentNameInLink}.layoutCenter) for more in
342343
componentNameInLink = ${componentNameInLink}
343344
) }}
344345

346+
#${prefix} clip(boolean) = false
347+
348+
{{ use: partial-version(version = "6.0.0") }}
349+
350+
{{ use: partial-view-coord-sys-allocated-rect-desc(
351+
componentNameReadable = ${componentNameReadable},
352+
componentNameInLink = ${componentNameInLink},
353+
isGeoOrMap = true
354+
) }}
355+
356+
`clip` specifies whether to hide the outside part of the map with respect to the allocated rect.
357+
358+
**See example:** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
359+
345360

346361
{{ target: partial-geo-common-state }}
347362

‎en/option/partial/coord-sys.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -276,7 +276,7 @@ When `geoIndex` or `geoId` is specified, [series-map.map](~series-map.map) other
276276
## geoId(number) = undefined
277277

278278
{{ if: ${version} }}
279-
{{ use: partial-version(version = ${version}) }}
279+
{{ use: partial-version(version = ${version|minVersion('6.0.0')}) }}
280280
{{ /if }}
281281

282282
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`.

‎en/option/partial/view-coord-sys.md‎

Lines changed: 47 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -116,27 +116,58 @@ When [roaming](~${componentNameInLink}.roam), the values in [center](~${componen
116116

117117
When roaming, the values in [center](~${componentNameInLink}.center) and [zoom](~${componentNameInLink}.zoom) will be modified correspondingly.
118118

119+
#${prefix} roamTrigger(string) = ${roamTriggerDefault|default("'selfRect'")}
119120

121+
{{ use: partial-version(version = "6.0.0") }}
122+
123+
[Roaming](~${componentNameInLink}.roam) can be triggered by mouse dragging or mouse wheel.
124+
125+
Options:
126+
- `'selfRect'`:
127+
128+
The roaming can only be triggered on the bounding rect of the graphic elements.
129+
130+
- `'global'`:
131+
132+
{{ 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 }}
133+
134+
{{ if: ${isGeoOrMap} }}
135+
**See example:** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
136+
{{ /if }}
120137

121138
{{ target: partial-preserve-aspect }}
122139

123140
#${prefix} preserveAspect(boolean|string) = ${preserveAspectDefault|default(false)}
124141

142+
{{ if: ${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map' }}
143+
{{ var: isGeoOrMap = true }}
144+
{{ /if }}
145+
125146
<ExampleUIControlBoolean default="false" />
126147

127148
{{ use: partial-version(version = "6.0.0") }}
128149

129-
`aspect ratio` here refers to `width / height` of the original bounding rect of the content to be rendered.
150+
`aspect ratio` here refers to `width / height`.
130151

131-
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).
152+
"preserve aspect" refers whether to preserve the `aspect ratio` of the original bounding rect of the content to be rendered.
153+
154+
{{ use: partial-view-coord-sys-allocated-rect-desc(
155+
componentNameReadable = ${componentNameReadable},
156+
componentNameInLink = ${componentNameInLink},
157+
isGeoOrMap = ${isGeoOrMap}
158+
) }}
159+
160+
But the `aspect ratio` of this rectangle may not match that of the content's original bounding rect, which may cause distortion.
132161

133162
Options of `preserveAspect`:
134-
- `null`/`undefined`/`false` (default): `aspect ratio` will not be preserved, but stretched to fill the `${componentNameReadable} rectangular area`, which may cause distortion.
135-
- `'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.
136-
- `'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.
163+
- `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.
164+
- `'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.
165+
- `'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.
137166

138-
{{ if: (${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map') }}
167+
{{ if: ${isGeoOrMap} }}
139168
Notice: When using [layoutCenter](~${componentNameInLink}.layoutCenter) and [layoutSize](~${componentNameInLink}.layoutSize), the `aspect radio` is always preserved, regardless of this `preserveAspect`.
169+
170+
**See example:** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
140171
{{ /if }}
141172

142173
#${prefix} preserveAspectAlign(string) = 'center'
@@ -149,6 +180,8 @@ Options: `'left'` | `'right'` | `'center'`.
149180

150181
See [preserveAspect](~${componentNameInLink}.preserveAspect).
151182

183+
See example [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
184+
152185
#${prefix} preserveAspectVerticalAlign(string) = 'middle'
153186

154187
<ExampleUIControlEnum options="top,bottom,middle" default="middle" />
@@ -158,3 +191,11 @@ See [preserveAspect](~${componentNameInLink}.preserveAspect).
158191
Options: `'top'` | `'bottom'` | `'middle'`.
159192

160193
See [preserveAspect](~${componentNameInLink}.preserveAspect).
194+
195+
See example [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
196+
197+
198+
199+
{{ target: partial-view-coord-sys-allocated-rect-desc }}
200+
201+
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 }}.

‎en/option/series/sankey.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,8 @@ The drag-and-drop interaction of the node, which is enabled by default. After op
9595
{{ use: partial-view-coord-sys-common(
9696
prefix = '#',
9797
componentMainType = 'series',
98-
componentSubType = 'sankey'
98+
componentSubType = 'sankey',
99+
roamTriggerDefault = "'global'",
99100
) }}
100101

101102

‎en/option/series/tree.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,8 @@ The tree diagram is mainly used to visualize the tree data structure, which is a
4848
{{ use: partial-view-coord-sys-common(
4949
prefix = '#',
5050
componentMainType = 'series',
51-
componentSubType = 'tree'
51+
componentSubType = 'tree',
52+
roamTriggerDefault = "'global'"
5253
) }}
5354

5455

‎zh/option/component/axis-common.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -650,6 +650,8 @@ splitLine: {
650650
{{ if: ${componentType} === 'xAxis' || ${componentType} === 'yAxis' }}
651651
#${prefix} nameMoveOverlap(boolean) = true
652652

653+
<ExampleUIControlBoolean default="true"/>
654+
653655
{{ use: partial-version(version = "6.0.0") }}
654656

655657
当 axis name 和 axis label 重叠时，是否自动移动 axis name 来避免重叠。

‎zh/option/component/geo-common.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,8 @@ series: {
165165
{{ use: partial-view-coord-sys-common(
166166
prefix = ${prefix},
167167
componentMainType = ${componentMainType},
168-
componentSubType = ${componentSubType}
168+
componentSubType = ${componentSubType},
169+
supportClip = true
169170
) }}
170171

171172

@@ -336,6 +337,19 @@ layoutSize: 100
336337
componentNameInLink = ${componentNameInLink}
337338
) }}
338339

340+
#${prefix} clip(boolean) = false
341+
342+
{{ use: partial-version(version = "6.0.0") }}
343+
344+
{{ use: partial-view-coord-sys-allocated-rect-desc(
345+
componentNameReadable = ${componentNameReadable},
346+
componentNameInLink = ${componentNameInLink},
347+
isGeoOrMap = true
348+
) }}
349+
350+
当地图超出这个分配的矩形区域时，`clip` 决定了是否剪裁超出部分。
351+
352+
**参见示例：** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
339353

340354

341355
{{ target: partial-geo-common-state }}

‎zh/option/partial/coord-sys.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,7 @@
279279
## geoId(number) = undefined
280280

281281
{{ if: ${version} }}
282-
{{ use: partial-version(version = ${version}) }}
282+
{{ use: partial-version(version = ${version|minVersion('6.0.0')}) }}
283283
{{ /if }}
284284

285285
布局时所基于的 [地理坐标系](~geo) 的 id。当一个 ECharts 实例中存在多个地理坐标系时，用其指定所使用的坐标系。

‎zh/option/partial/view-coord-sys.md‎

Lines changed: 49 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,24 @@ center: ['50%', '50%']
115115

116116
当缩放和平移时，[center](~${componentNameInLink}.center) 和 [zoom](~${componentNameInLink}.zoom) 的值会被相应改变。
117117

118+
#${prefix} roamTrigger(string) = ${roamTriggerDefault|default("'selfRect'")}
119+
120+
{{ use: partial-version(version = "6.0.0") }}
121+
122+
[缩放和平移（roam）](~${componentNameInLink}.roam) 可被鼠标触发。
123+
124+
Options:
125+
- `'selfRect'`:
126+
127+
缩放和平移的触发点只能是图形元素形成的包围盒中。
128+
129+
- `'global'`:
130+
131+
{{ if: ${supportClip} }}如果 `clip: true`，缩放和平移的触发点是剪裁矩形中的任何地方；否则，触发点是画布中的任何地方。{{ else }}缩放和平移的触发点是画布中的任何地方。{{ /if }}
132+
133+
{{ if: ${isGeoOrMap} }}
134+
参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
135+
{{ /if }}
118136

119137

120138
{{ target: partial-geo-preserve-aspect }}
@@ -123,22 +141,35 @@ center: ['50%', '50%']
123141

124142
#${prefix} preserveAspect(boolean|string) = ${preserveAspectDefault|default(false)}
125143

144+
{{ if: ${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map' }}
145+
{{ var: isGeoOrMap = true }}
146+
{{ /if }}
147+
126148
<ExampleUIControlBoolean default="false" />
127149

128150
{{ use: partial-version(version = "6.0.0") }}
129151

130-
`aspect ratio`（宽高比）在此处指的是要渲染的内容的原始包围盒的 `width / height`。
152+
`aspect ratio` 指 `width / height`。
153+
154+
"preserve aspect" 指是否要保持被渲染的内容的原始包围盒的 `aspect ratio`。
155+
156+
{{ use: partial-view-coord-sys-allocated-rect-desc(
157+
componentNameReadable = ${componentNameReadable},
158+
componentNameInLink = ${componentNameInLink},
159+
isGeoOrMap = ${isGeoOrMap}
160+
) }}
131161

132-
假设为 ${componentNameReadable} 分配的 `矩形区域` 是通过以下配置定义的：
133-
[${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height)。
162+
但是这个矩形的 `aspect ratio` 不一定和内容的原始 `aspect ratio` 一致，从而可能导致内容被拉伸而失真。
134163

135164
`preserveAspect` 的不同选项有如下效果：
136-
- `null` / `undefined` / `false`（默认）：不会保留宽高比，而是拉伸内容以填满 `${componentNameReadable}矩形区域`。拉伸有可能导致图形失真。
137-
- `'contain'` / `true`：保留宽高比。内容的包围盒被完整地包含在 `${componentNameReadable}矩形区域` 中，并尽可能放大以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。
138-
- `'cover'`：保留宽高比。内容的包围盒会覆盖整个 `${componentNameReadable}矩形区域`，并尽可能缩小以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。
165+
- `null` / `undefined` / `false`（默认）：不会保持内容的原始 `aspect ratio`，而是拉伸内容以填满 `${componentNameReadable}矩形区域`。拉伸有可能导致图形失真。
166+
- `'contain'` / `true`：保持内容的 `aspect ratio`。内容的包围盒被完整地包含在 `${componentNameReadable}矩形区域` 中，并尽可能放大以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。
167+
- `'cover'`：保持内容的原始 `aspect ratio`。内容的包围盒会覆盖整个 `${componentNameReadable}矩形区域`，并尽可能缩小以触达边界。此时可使用 [preserveAspectAlign](~${componentNameInLink}.preserveAspectAlign) 和 [preserveAspectVerticalAlign](~${componentNameInLink}.preserveAspectVerticalAlign) 调整位置。
139168

140-
{{ if: (${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map') }}
169+
{{ if: ${isGeoOrMap} }}
141170
注意：当使用 [layoutCenter](~${componentNameInLink}.layoutCenter) 和 [layoutSize](~${componentNameInLink}.layoutSize) 时，始终会保留宽高比，无论 `preserveAspect` 配置为何值。
171+
172+
**参见示例：** [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
142173
{{ /if }}
143174

144175
#${prefix} preserveAspectAlign(string) = 'center'
@@ -151,6 +182,8 @@ center: ['50%', '50%']
151182

152183
参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。
153184

185+
参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
186+
154187
#${prefix} preserveAspectVerticalAlign(string) = 'middle'
155188

156189
<ExampleUIControlEnum options="top,bottom,middle" default="middle" />
@@ -160,3 +193,12 @@ center: ['50%', '50%']
160193
Options: `'top'` | `'bottom'` | `'middle'`。
161194

162195
参见 [preserveAspect](~${componentNameInLink}.preserveAspect)。
196+
197+
参见示例 [geo roam indicator](${galleryEditorPath}doc-example/geo-roam-indicator&edit=1&reset=1).
198+
199+
200+
201+
{{ target: partial-view-coord-sys-allocated-rect-desc }}
202+
203+
为 ${componentNameReadable} 分配的 `矩形区域` 是通过以下配置决定的：
204+
[${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 }}。

0 commit comments

Comments
 (0)