• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.arkui.shape (形状)
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @CCFFWW-->
5<!--Designer: @yangfan229-->
6<!--Tester: @lxl007-->
7<!--Adviser: @HelloCrease-->
8
9在 clipShape 和 maskShape 接口中可以传入对应的形状。
10
11
12> **说明：**
13>
14> 从API version 12开始支持。后续版本的新增形状，采用上角标单独标记形状的起始版本。
15>
16> 示例效果请以真机运行为准，当前DevEco Studio预览器不支持。
17
18## 导入模块
19
20```ts
21import { CircleShape, EllipseShape, PathShape, RectShape } from "@kit.ArkUI";
22```
23
24## CircleShape
25
26用于 clipShape 和 maskShape 接口的圆形形状。
27
28继承自[BaseShape](#baseshape)。
29
30**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
31
32**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
33
34**系统能力：** SystemCapability.ArkUI.ArkUI.Full
35
36### constructor
37
38constructor(options?: ShapeSize)
39
40创建CircleShape对象。
41
42**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
43
44**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
45
46**系统能力：** SystemCapability.ArkUI.ArkUI.Full
47
48**参数：**
49
50| 参数名         | 类型                                               | 必填 | 说明                                         |
51| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
52| options | [ShapeSize](#shapesize) | 否 | 形状的大小。 |
53
54## EllipseShape
55
56用于 clipShape 和 maskShape 接口的椭圆形状。
57
58继承自[BaseShape](#baseshape)。
59
60**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
61
62**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
63
64**系统能力：** SystemCapability.ArkUI.ArkUI.Full
65
66### constructor
67
68constructor(options?: ShapeSize)
69
70创建EllipseShape对象。
71
72**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
73
74**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
75
76**系统能力：** SystemCapability.ArkUI.ArkUI.Full
77
78**参数：**
79
80| 参数名         | 类型                                               | 必填 | 说明                                         |
81| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
82| options | [ShapeSize](#shapesize) | 否 | 形状的大小。 |
83
84## PathShape
85
86用于 clipShape 和 maskShape 接口的路径。
87
88继承自[CommonShapeMethod](#commonshapemethod)。
89
90**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
91
92**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
93
94**系统能力：** SystemCapability.ArkUI.ArkUI.Full
95
96### constructor
97
98constructor(options?: PathShapeOptions)
99
100创建PathShape对象。
101
102**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
103
104**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
105
106**系统能力：**  SystemCapability.ArkUI.ArkUI.Full
107
108**参数：**
109
110| 参数名         | 类型                                               | 必填 | 说明                                         |
111| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
112| options | [PathShapeOptions](#pathshapeoptions) | 否 | 路径参数。 |
113
114### commands
115
116commands(commands: string): PathShape
117
118设置路径的绘制指令。
119
120**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
121
122**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
123
124**系统能力：** SystemCapability.ArkUI.ArkUI.Full
125
126**参数：**
127
128| 参数名         | 类型                                               | 必填 | 说明                                         |
129| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
130| commands | string | 是 | 路径的绘制指令。 |
131
132**返回值：**
133
134| 类型   | 说明                     |
135| ------ | ------------------------ |
136| PathShape | 返回PathShape对象。 |
137
138## RectShape
139
140用于 clipShape 和 maskShape 接口的矩形形状。
141
142继承自[BaseShape](#baseshape)。
143
144**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
145
146**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
147
148**系统能力：** SystemCapability.ArkUI.ArkUI.Full
149
150### constructor
151
152constructor(options?: RectShapeOptions | RoundRectShapeOptions)
153
154创建RectShape对象。
155
156**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
157
158**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
159
160**系统能力：** SystemCapability.ArkUI.ArkUI.Full
161
162**参数：**
163
164| 参数名         | 类型                                               | 必填 | 说明                                         |
165| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
166| options | [RectShapeOptions](#rectshapeoptions) &nbsp;\|&nbsp; [RoundRectShapeOptions](#roundrectshapeoptions) | 否 | 矩形形状参数。 |
167
168### radiusWidth
169
170radiusWidth(rWidth: number | string): RectShape
171
172设置矩形形状圆角半径的宽度。
173
174**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
175
176**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
177
178**系统能力：** SystemCapability.ArkUI.ArkUI.Full
179
180**参数：**
181
182| 参数名         | 类型                                               | 必填 | 说明                                         |
183| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
184| rWidth | number &nbsp;\|&nbsp; string | 是 | 矩形形状圆角半径的宽度。<br/> 类型为number时取值范围是[0, +∞)，string时是[Length](arkui-ts/ts-types.md#length)。 |
185
186**返回值：**
187
188| 类型   | 说明                     |
189| ------ | ------------------------ |
190| RectShape | 返回RectShape对象。 |
191
192### radiusHeight
193
194radiusHeight(rHeight: number | string): RectShape
195
196设置矩形形状圆角半径的高度。
197
198**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
199
200**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
201
202**系统能力：** SystemCapability.ArkUI.ArkUI.Full
203
204**参数：**
205
206| 参数名         | 类型                                               | 必填 | 说明                                         |
207| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
208| rHeight | number &nbsp;\|&nbsp; string | 是 | 矩形形状圆角半径的高度。 <br/> 类型为number时取值范围是[0, +∞)，string时是[Length](arkui-ts/ts-types.md#length)。 |
209
210**返回值：**
211
212| 类型   | 说明                     |
213| ------ | ------------------------ |
214| RectShape | 返回RectShape对象。 |
215
216### radius
217
218radius(radius: number | string | Array<number &nbsp;\|&nbsp; string>): RectShape
219
220设置矩形形状的圆角半径。
221
222**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
223
224**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
225
226**系统能力：** SystemCapability.ArkUI.ArkUI.Full
227
228**参数：**
229
230| 参数名         | 类型                                               | 必填 | 说明                                         |
231| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
232| radius | number &nbsp;\|&nbsp; string &nbsp;\|&nbsp; Array<number &nbsp;\|&nbsp; string> | 是 | 矩形形状的圆角半径。仅接受数组的前四个元素，分别为矩形左上，右上，左下，右下的圆角半径。<br/> 类型为number时取值范围是[0, +∞)，string时是[Length](arkui-ts/ts-types.md#length)。 |
233
234**返回值：**
235
236| 类型   | 说明                     |
237| ------ | ------------------------ |
238| RectShape | 返回RectShape对象。 |
239
240
241## ShapeSize
242
243形状的尺寸参数。
244
245**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
246
247**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
248
249**系统能力：** SystemCapability.ArkUI.ArkUI.Full
250
251| 名称         | 类型                                               | 只读                                             | 可选                                             | 说明                                         |
252| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
253| width | number &nbsp;\|&nbsp; string | 否 | 是 | 形状的宽度。<br/> 类型为number时取值范围是[0, +∞)，string时是[Length](arkui-ts/ts-types.md#length)。 |<br/>单位：vp |
254| height | number &nbsp;\|&nbsp; string | 否 | 是 | 形状的高度。 <br/> 类型为number时取值范围是[0, +∞)，string时是[Length](arkui-ts/ts-types.md#length)。 |<br/>单位：vp|
255
256## PathShapeOptions
257
258PathShape 的构造函数参数。
259
260**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
261
262**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
263
264**系统能力：** SystemCapability.ArkUI.ArkUI.Full
265
266| 名称         | 类型                                               | 只读                                             | 可选                                             | 说明                                         |
267| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
268| commands | string | 否 | 是 | 绘制路径的指令。更多说明请参考commands支持的[绘制命令](./arkui-ts/ts-drawing-components-path.md#commands)。 |
269
270## RectShapeOptions
271
272RectShape 的构造函数参数。
273
274继承自[ShapeSize](#shapesize)。
275
276**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
277
278**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
279
280**系统能力：** SystemCapability.ArkUI.ArkUI.Full
281
282| 名称         | 类型                                               | 只读                                             | 可选                                             | 说明                                         |
283| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
284| radius | number &nbsp;\|&nbsp; string &nbsp;\|&nbsp; Array<number &nbsp;\|&nbsp; string> | 否 | 是 | 矩形形状的圆角半径。<br/> 类型为number时取值范围是[0, +∞)，string时是[Length](arkui-ts/ts-types.md#length)。 |
285
286## RoundRectShapeOptions
287
288RectShape 带有半径的构造函数参数。
289
290继承自[ShapeSize](#shapesize)。
291
292**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
293
294**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
295
296**系统能力：** SystemCapability.ArkUI.ArkUI.Full
297
298| 名称         | 类型                                               | 只读                                             | 可选                                             | 说明                                         |
299| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
300| radiusWidth | number &nbsp;\|&nbsp; string | 否 | 是 | 矩形形状圆角半径的宽度。<br/> 类型为number时取值范围是[0, +∞)，string时是[Length](arkui-ts/ts-types.md#length)。 |
301| radiusHeight | number &nbsp;\|&nbsp; string | 否 | 是 | 矩形形状圆角半径的高度。<br/> 类型为number时取值范围是[0, +∞)，string时是[Length](arkui-ts/ts-types.md#length)。 |
302
303## BaseShape
304
305继承自[CommonShapeMethod](#commonshapemethod)。
306
307**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
308
309**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
310
311**系统能力：** SystemCapability.ArkUI.ArkUI.Full
312
313### width
314
315width(width: Length): T
316
317设置形状的宽度。
318
319**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
320
321**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
322
323**系统能力：** SystemCapability.ArkUI.ArkUI.Full
324
325**参数：**
326
327| 参数名         | 类型                                               | 必填 | 说明                                         |
328| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
329| width | [Length](arkui-ts/ts-types.md#length) | 是 | 形状的宽度。 |
330
331**返回值：**
332
333| 类型   | 说明                     |
334| ------ | ------------------------ |
335| T | 返回当前对象。 |
336
337### height
338
339height(height: Length): T
340
341设置形状的高度。
342
343**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
344
345**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
346
347**系统能力：** SystemCapability.ArkUI.ArkUI.Full
348
349**参数：**
350
351| 参数名         | 类型                                               | 必填 | 说明                                         |
352| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
353| height | [Length](arkui-ts/ts-types.md#length) | 是 | 形状的高度。 |
354
355**返回值：**
356
357| 类型   | 说明                     |
358| ------ | ------------------------ |
359| T | 返回当前对象。 |
360
361### size
362
363size(size: SizeOptions): T
364
365设置形状的大小。
366
367**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
368
369**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
370
371**系统能力：** SystemCapability.ArkUI.ArkUI.Full
372
373**参数：**
374
375| 参数名         | 类型                                               | 必填 | 说明                                         |
376| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
377| size | [SizeOptions](arkui-ts/ts-types.md#sizeoptions) | 是 | 形状的大小。 |
378
379**返回值：**
380
381| 类型   | 说明                     |
382| ------ | ------------------------ |
383| T | 返回当前对象。 |
384
385## CommonShapeMethod
386
387常见的形状方法。
388
389**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
390
391**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
392
393**系统能力：** SystemCapability.ArkUI.ArkUI.Full
394
395### offset
396
397offset(offset: Position): T
398
399设置相对于组件布局位置的坐标偏移。
400
401**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
402
403**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
404
405**系统能力：** SystemCapability.ArkUI.ArkUI.Full
406
407**参数：**
408
409| 参数名         | 类型                                               | 必填 | 说明                                         |
410| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
411| offset | [Position](arkui-ts/ts-types.md#position) | 是 | 相对于组件布局位置的坐标偏移。 |
412
413**返回值：**
414
415| 类型   | 说明                     |
416| ------ | ------------------------ |
417| T | 返回当前对象。 |
418
419
420### fill
421
422fill(color: ResourceColor): T
423
424设置形状的填充区域的透明度，黑色表示完全透明，白色表示完全不透明。
425
426**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
427
428**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
429
430**系统能力：** SystemCapability.ArkUI.ArkUI.Full
431
432**参数：**
433
434| 参数名         | 类型                                               | 必填 | 说明                                         |
435| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
436| color | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 是 | 形状的填充区域的透明度，黑色表示完全透明，白色表示完全不透明。 |
437
438**返回值：**
439
440| 类型   | 说明                     |
441| ------ | ------------------------ |
442| T | 返回当前对象。 |
443
444
445### position
446
447position(position: Position): T
448
449设置形状的位置。
450
451**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
452
453**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
454
455**系统能力：** SystemCapability.ArkUI.ArkUI.Full
456
457**参数：**
458
459| 参数名         | 类型                                               | 必填 | 说明                                         |
460| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
461| position | [Position](arkui-ts/ts-types.md#position) | 是 | 设置形状的位置。 |
462
463**返回值：**
464
465| 类型   | 说明                     |
466| ------ | ------------------------ |
467| T | 返回当前对象。 |
468
469## **示例**
470
471```ts
472import { CircleShape, EllipseShape, PathShape, RectShape } from "@kit.ArkUI";
473
474@Entry
475@Component
476struct ShapeExample {
477  build() {
478    Column({ space: 15 }) {
479      Text('CircleShape, position').fontSize(20).width('75%').fontColor('#DCDCDC')
480      Image($r('app.media.startIcon'))
481        .clipShape(new CircleShape({ width: '280px', height: '280px' }).position({ x: '20px', y: '20px' }))
482        .width('500px').height('280px')
483
484      Text('EllipseShape, offset').fontSize(20).width('75%').fontColor('#DCDCDC')
485      Image($r('app.media.startIcon'))
486        .clipShape(new EllipseShape({ width: '350px', height: '280px' }).offset({ x: '10px', y: '10px' }))
487        .width('500px').height('280px')
488
489      Text('PathShape, fill').fontSize(20).width('75%').fontColor('#DCDCDC')
490      Image($r('app.media.startIcon'))
491        .maskShape(new PathShape().commands('M100 0 L200 240 L0 240 Z').fill(Color.Red))
492        .width('500px').height('280px')
493
494      Text('RectShape, width, height, fill').fontSize(20).width('75%').fontColor('#DCDCDC')
495      Image($r('app.media.startIcon'))
496        .maskShape(new RectShape().width('350px').height('280px').fill(Color.Red))
497        .width('500px').height('280px')
498    }
499    .width('100%')
500    .margin({ top: 15 })
501  }
502}
503```