Skip to content

Commit 19fdd60

Browse files
100pah100pah
committed
Add doc for preserveAspect.
1 parent 71dec30 commit 19fdd60

10 files changed

Lines changed: 326 additions & 24 deletions

File tree

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

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@
33

44
{{ if: ${inMap} }}
55
{{ var: componentNameInLink = 'series-map' }}
6+
{{ var: componentNameReadable = 'map series' }}
67
{{ var: componentMainType = 'series' }}
78
{{ var: componentSubType = 'map' }}
89
{{ else }}
910
{{ var: componentNameInLink = 'geo' }}
11+
{{ var: componentNameReadable = 'geo component' }}
1012
{{ var: componentMainType = 'geo' }}
1113
{{ var: componentSubType = null }}
1214
{{ /if }}
@@ -297,15 +299,17 @@ Map area style in blurred state.
297299
) }}
298300
{{ /if }}
299301

300-
{{ use: partial-rect-layout(
301-
prefix = ${prefix}
302+
{{ use: partial-rect-layout-width-height(
303+
prefix = ${prefix},
304+
hostName = ${componentNameReadable},
305+
hintPreserveAspect = true,
306+
hintGeoRectLayoutApproaches = true,
307+
componentNameInLink = ${componentNameInLink}
302308
) }}
303309

304310
#${prefix} layoutCenter(Array) = null
305311

306-
`layoutCenter` and `layoutSize` provides layout strategy other than `left/right/top/bottom/width/height`.
307-
308-
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:
312+
`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:
309313

310314
```ts
311315
layoutCenter: ['30%', '30%'],
@@ -317,10 +321,26 @@ layoutSize: 100
317321

318322
After setting these two values, `left/right/top/bottom/width/height` becomes invalid.
319323

324+
{{ use: partial-geo-rect-layout-approaches-hint(
325+
hintGeoRectLayoutApproaches = true,
326+
componentNameInLink = ${componentNameInLink}
327+
) }}
328+
329+
320330
#${prefix} layoutSize(number|string)
321331

322-
Size of map, see `layoutCenter` for more information. Percentage relative to screen width, and absolute pixel values are supported.
332+
Size of map, see [layoutCenter](${componentNameInLink}.layoutCenter) for more information. Percentage relative to container width/height, and absolute pixel values are supported.
323333

334+
{{ use: partial-geo-rect-layout-approaches-hint(
335+
hintGeoRectLayoutApproaches = true,
336+
componentNameInLink = ${componentNameInLink}
337+
) }}
338+
339+
{{ use: partial-preserve-aspect(
340+
prefix = ${prefix},
341+
componentNameReadable = ${componentNameReadable},
342+
componentNameInLink = ${componentNameInLink}
343+
) }}
324344

325345

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

‎en/option/partial/rect-layout-width-height.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@
1515
defaultLeft = ${defaultLeft},
1616
defaultTop = ${defaultTop},
1717
defaultRight = ${defaultRight},
18-
defaultBottom = ${defaultBottom}
18+
defaultBottom = ${defaultBottom},
19+
hintPreserveAspect = ${hintPreserveAspect},
20+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
21+
componentNameInLink = ${componentNameInLink}
1922
) }}
2023

2124
#${prefix|default("#")} width(string|number) = ${defaultWidth|default("'auto'")}
@@ -26,6 +29,14 @@
2629

2730
Width of ${hostNameStr}. {{ if: !${defaultWidth} }}Adaptive by default.{{ /if }}
2831

32+
`width` can be a pixel value like `20`; it can also be a percentage value relative to the container width like `'20%'`.
33+
34+
{{ use: partial-preserve-aspect-hint(
35+
hintPreserveAspect = ${hintPreserveAspect},
36+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
37+
componentNameInLink = ${componentNameInLink}
38+
) }}
39+
2940
#${prefix|default("#")} height(string|number) = ${defaultHeight|default("'auto'")}
3041

3142
{{ if: ${version} }}
@@ -34,3 +45,10 @@ Width of ${hostNameStr}. {{ if: !${defaultWidth} }}Adaptive by default.{{ /if }}
3445

3546
Height of ${hostNameStr}. {{ if: !${defaultHeight} }}Adaptive by default.{{ /if }}
3647

48+
`height` can be a pixel value like `20`; it can also be a percentage value relative to the container height like `'20%'`.
49+
50+
{{ use: partial-preserve-aspect-hint(
51+
hintPreserveAspect = ${hintPreserveAspect},
52+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
53+
componentNameInLink = ${componentNameInLink}
54+
) }}

‎en/option/partial/rect-layout.md‎

Lines changed: 64 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,21 @@
2323

2424
Distance between ${hostNameStr} and the left side of the container.
2525

26-
`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'`.
26+
`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'`.
2727

2828
If the `left` value is set to be `'left'`, `'center'`, or `'right'`, then the component will be aligned automatically based on position.
2929

30+
{{ use: partial-preserve-aspect-hint(
31+
hintPreserveAspect = ${hintPreserveAspect},
32+
componentNameInLink = ${componentNameInLink}
33+
) }}
34+
35+
{{ use: partial-geo-rect-layout-approaches-hint(
36+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
37+
componentNameInLink = ${componentNameInLink}
38+
) }}
39+
40+
3041
#${prefix|default("#")} top(string|number) = ${defaultTop|default("'auto'")}
3142

3243
{{ if: ${version} }}
@@ -35,10 +46,21 @@ If the `left` value is set to be `'left'`, `'center'`, or `'right'`, then the co
3546

3647
Distance between ${hostNameStr} and the top side of the container.
3748

38-
`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'`.
49+
`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'`.
3950

4051
If the `top` value is set to be `'top'`, `'middle'`, or `'bottom'`, then the component will be aligned automatically based on position.
4152

53+
{{ use: partial-preserve-aspect-hint(
54+
hintPreserveAspect = ${hintPreserveAspect},
55+
componentNameInLink = ${componentNameInLink}
56+
) }}
57+
58+
{{ use: partial-geo-rect-layout-approaches-hint(
59+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
60+
componentNameInLink = ${componentNameInLink}
61+
) }}
62+
63+
4264
#${prefix|default("#")} right(string|number) = ${defaultRight|default("'auto'")}
4365

4466
{{ if: ${version} }}
@@ -47,10 +69,21 @@ If the `top` value is set to be `'top'`, `'middle'`, or `'bottom'`, then the com
4769

4870
Distance between ${hostNameStr} and the right side of the container.
4971

50-
`right` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`.
72+
`right` can be a pixel value like `20`; it can also be a percentage value relative to the container width like `'20%'`.
5173

5274
{{ if: !${defaultRight} }}Adaptive by default.{{ /if }}
5375

76+
{{ use: partial-preserve-aspect-hint(
77+
hintPreserveAspect = ${hintPreserveAspect},
78+
componentNameInLink = ${componentNameInLink}
79+
) }}
80+
81+
{{ use: partial-geo-rect-layout-approaches-hint(
82+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
83+
componentNameInLink = ${componentNameInLink}
84+
) }}
85+
86+
5487
#${prefix|default("#")} bottom(string|number) = ${defaultBottom|default("'auto'")}
5588

5689
{{ if: ${version} }}
@@ -59,7 +92,34 @@ Distance between ${hostNameStr} and the right side of the container.
5992

6093
Distance between ${hostNameStr} and the bottom side of the container.
6194

62-
`bottom` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`.
95+
`bottom` can be a pixel value like `20`; it can also be a percentage value relative to the container height like `'20%'`.
6396

6497
{{ if: !${defaultBottom} }}Adaptive by default.{{ /if }}
6598

99+
{{ use: partial-preserve-aspect-hint(
100+
hintPreserveAspect = ${hintPreserveAspect},
101+
componentNameInLink = ${componentNameInLink}
102+
) }}
103+
104+
{{ use: partial-geo-rect-layout-approaches-hint(
105+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
106+
componentNameInLink = ${componentNameInLink}
107+
) }}
108+
109+
110+
111+
{{ target: partial-preserve-aspect-hint }}
112+
113+
{{ if: ${hintPreserveAspect} && ${componentNameInLink} }}
114+
> Note: If the graphic elements are unexpectedly distorted, see [preserveAspect](~${componentNameInLink}.preserveAspect).
115+
{{ /if }}
116+
117+
118+
119+
{{ target: partial-geo-rect-layout-approaches-hint }}
120+
121+
{{ if: ${hintGeoRectLayoutApproaches} && ${componentNameInLink} }}
122+
> Note: There are two rectangular layout approaches for ${componentNameInLink}. You can use either one:
123+
> - [${componentNameInLink}.left](~${componentNameInLink}.left) / [.right](~${componentNameInLink}.right) / [.top](~${componentNameInLink}.top) / [.bottom](~${componentNameInLink}.bottom) / [.width](~${componentNameInLink}.width) / [.height](~${componentNameInLink}.height)
124+
> - [${componentNameInLink}.layoutCenter](~${componentNameInLink}.layoutCenter) / [.layoutSize](~${componentNameInLink}.layoutSize)
125+
{{ /if }}

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,3 +115,46 @@ When [roaming](~${componentNameInLink}.roam), the values in [center](~${componen
115115
{{ use: partial-roam-desc() }}
116116

117117
When roaming, the values in [center](~${componentNameInLink}.center) and [zoom](~${componentNameInLink}.zoom) will be modified correspondingly.
118+
119+
120+
121+
{{ target: partial-preserve-aspect }}
122+
123+
#${prefix} preserveAspect(boolean|string) = ${preserveAspectDefault|default(false)}
124+
125+
<ExampleUIControlBoolean default="false" />
126+
127+
{{ use: partial-version(version = "6.0.0") }}
128+
129+
`aspect ratio` here refers to `width / height` of the original bounding rect of the content to be rendered.
130+
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).
132+
133+
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.
137+
138+
{{ if: (${componentNameInLink} === 'geo' || ${componentNameInLink} === 'series-map') }}
139+
Notice: When using [layoutCenter](~${componentNameInLink}.layoutCenter) and [layoutSize](~${componentNameInLink}.layoutSize), the `aspect radio` is always preserved, regardless of this `preserveAspect`.
140+
{{ /if }}
141+
142+
#${prefix} preserveAspectAlign(string) = 'center'
143+
144+
<ExampleUIControlEnum options="left,right,center" default="center" />
145+
146+
{{ use: partial-version(version = "6.0.0") }}
147+
148+
Options: `'left'` | `'right'` | `'center'`.
149+
150+
See [preserveAspect](~${componentNameInLink}.preserveAspect).
151+
152+
#${prefix} preserveAspectVerticalAlign(string) = 'middle'
153+
154+
<ExampleUIControlEnum options="top,bottom,middle" default="middle" />
155+
156+
{{ use: partial-version(version = "6.0.0") }}
157+
158+
Options: `'top'` | `'bottom'` | `'middle'`.
159+
160+
See [preserveAspect](~${componentNameInLink}.preserveAspect).

‎en/option/series/graph.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -582,7 +582,15 @@ Alias of [links](~series-graph.links)
582582
defaultLeft = "'center'",
583583
defaultTop = "'middle'",
584584
defaultWidth = 'auto',
585-
defaultHeight = 'auto'
585+
defaultHeight = 'auto',
586+
hintPreserveAspect = true,
587+
componentNameInLink = 'series-graph'
588+
) }}
589+
590+
{{ use: partial-preserve-aspect(
591+
prefix = '#',
592+
componentNameReadable = 'graph series',
593+
componentNameInLink = 'series-graph'
586594
) }}
587595

588596
{{ use: partial-silent(

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

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@
33

44
{{ if: ${inMap} }}
55
{{ var: componentNameInLink = 'series-map' }}
6+
{{ var: componentNameReadable = '地图系列' }}
67
{{ var: componentMainType = 'series' }}
78
{{ var: componentSubType = 'map' }}
89
{{ else }}
910
{{ var: componentNameInLink = 'geo' }}
11+
{{ var: componentNameReadable = 'geo 组件' }}
1012
{{ var: componentMainType = 'geo' }}
1113
{{ var: componentSubType = null }}
1214
{{ /if }}
@@ -293,15 +295,17 @@ boundingCoords: [
293295
) }}
294296
{{ /if }}
295297

296-
{{ use: partial-rect-layout(
297-
prefix = ${prefix}
298+
{{ use: partial-rect-layout-width-height(
299+
prefix = ${prefix},
300+
hostName = ${componentNameReadable},
301+
hintPreserveAspect = true,
302+
hintGeoRectLayoutApproaches = true,
303+
componentNameInLink = ${componentNameInLink}
298304
) }}
299305

300306
#${prefix} layoutCenter(Array) = null
301307

302-
`layoutCenter` 和 `layoutSize` 提供了除了 `left/right/top/bottom/width/height` 之外的布局手段。
303-
304-
在使用 `left/right/top/bottom/width/height` 的时候，可能很难在保持地图高宽比的情况下把地图放在某个盒形区域的正中间，并且保证不超出盒形的范围。此时可以通过 `layoutCenter` 属性定义地图中心在屏幕中的位置，`layoutSize` 定义地图的大小。如下示例
308+
`layoutCenter` 和 `layoutSize` 用于定义 ${componentNameReadable} 所拥有的矩形区域，其中`layoutCenter` 定义了区域中心在容器中的位置，`layoutSize` 定义了区域的大小。如下示例：
305309

306310
```ts
307311
layoutCenter: ['30%', '30%'],
@@ -311,9 +315,26 @@ layoutSize: 100
311315

312316
设置这两个值后 `left/right/top/bottom/width/height` 无效。
313317

318+
{{ use: partial-geo-rect-layout-approaches-hint(
319+
hintGeoRectLayoutApproaches = true,
320+
componentNameInLink = ${componentNameInLink}
321+
) }}
322+
323+
314324
#${prefix} layoutSize(number|string)
315325

316-
地图的大小，见 `layoutCenter`。支持相对于屏幕宽高的百分比或者绝对的像素大小。
326+
地图的大小，见 [layoutCenter](${componentNameInLink}.layoutCenter)。支持相对于容器宽高的百分比或者绝对的像素大小。
327+
328+
{{ use: partial-geo-rect-layout-approaches-hint(
329+
hintGeoRectLayoutApproaches = true,
330+
componentNameInLink = ${componentNameInLink}
331+
) }}
332+
333+
{{ use: partial-preserve-aspect(
334+
prefix = ${prefix},
335+
componentNameReadable = ${componentNameReadable},
336+
componentNameInLink = ${componentNameInLink}
337+
) }}
317338

318339

319340

‎zh/option/partial/rect-layout-width-height.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@
1515
defaultLeft = ${defaultLeft},
1616
defaultTop = ${defaultTop},
1717
defaultRight = ${defaultRight},
18-
defaultBottom = ${defaultBottom}
18+
defaultBottom = ${defaultBottom},
19+
hintPreserveAspect = ${hintPreserveAspect},
20+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
21+
componentNameInLink = ${componentNameInLink}
1922
) }}
2023

2124
#${prefix|default("#")} width(string|number) = ${defaultWidth|default("'auto'")}
@@ -28,6 +31,14 @@
2831

2932
${hostNameStr}的宽度。{{ if: !${defaultWidth} }}默认自适应。{{ /if }}
3033

34+
`width` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器宽度的百分比。
35+
36+
{{ use: partial-preserve-aspect-hint(
37+
hintPreserveAspect = ${hintPreserveAspect},
38+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
39+
componentNameInLink = ${componentNameInLink}
40+
) }}
41+
3142
#${prefix|default("#")} height(string|number) = ${defaultHeight|default("'auto'")}
3243

3344
<ExampleUIControlPercent default="50%"/>
@@ -38,3 +49,10 @@ ${hostNameStr}的宽度。{{ if: !${defaultWidth} }}默认自适应。{{ /if }}
3849

3950
${hostNameStr}的高度。{{ if: !${defaultHeight} }}默认自适应。{{ /if }}
4051

52+
`height` 的值可以是像 `20` 这样的具体像素值，可以是像 `'20%'` 这样相对于容器高度的百分比。
53+
54+
{{ use: partial-preserve-aspect-hint(
55+
hintPreserveAspect = ${hintPreserveAspect},
56+
hintGeoRectLayoutApproaches = ${hintGeoRectLayoutApproaches},
57+
componentNameInLink = ${componentNameInLink}
58+
) }}

0 commit comments

Comments
 (0)