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