1# Shape
2
3绘制组件的父组件,父组件中会描述所有绘制组件均支持的通用属性。
4
51、绘制组件使用Shape作为父组件,实现类似SVG的效果。
6
72、绘制组件单独使用,用于在页面上绘制指定的图形。
8
9>  **说明:**
10>
11>  该组件从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
12
13
14## 子组件
15
16包含[Rect](ts-drawing-components-rect.md)、[Path](ts-drawing-components-path.md)、[Circle](ts-drawing-components-circle.md)、[Ellipse](ts-drawing-components-ellipse.md)、[Polyline](ts-drawing-components-polyline.md)、[Polygon](ts-drawing-components-polygon.md)、[Image](ts-basic-components-image.md)、[Text](ts-basic-components-text.md)、[Column](ts-container-column.md)、[Row](ts-container-row.md)、Shape子组件。
17
18
19## 接口
20
21Shape(value?: PixelMap)
22
23从API version 9开始,该接口支持在ArkTS卡片中使用,卡片中不支持使用PixelMap对象。
24
25**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
26
27**系统能力:** SystemCapability.ArkUI.ArkUI.Full
28
29**参数:**
30
31| 参数名 | 类型 | 必填 | 说明 |
32| -------- | -------- | -------- | -------- |
33| value | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) | 否 | 绘制目标,可将图形绘制在指定的PixelMap对象中,若未设置,则在当前绘制目标中进行绘制。 |
34
35
36## 属性
37
38除支持[通用属性](ts-universal-attributes-size.md)外,还支持以下属性:
39
40### viewPort
41
42viewPort(value: ViewportRect)
43
44设置形状的视口。
45
46**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
47
48**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
49
50**系统能力:** SystemCapability.ArkUI.ArkUI.Full
51
52**参数:**
53
54| 参数名 | 类型 | 必填 | 说明 |
55| -------- | -------- | -------- | -------- |
56| value | [ViewportRect](ts-drawing-components-shape.md#viewportrect14对象说明) | 是 | Viewport绘制属性。 |
57
58## ViewportRect<sup>14+</sup>对象说明
59用于描述Viewport绘制属性。
60
61**卡片能力:** 从API version 14开始,该接口支持在ArkTS卡片中使用。
62
63**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。
64
65**系统能力:** SystemCapability.ArkUI.ArkUI.Full
66
67| 名称 | 类型 | 必填 | 说明 |
68| -------- | -------- | -------- | -------- |
69| x | string \| number | 否 | 形状视口起始点的水平坐标。<br/>默认值:0<br/>默认单位:vp<br/>异常值按照默认值处理。 |
70| y | string \| number | 否 | 形状视口起始点的垂直坐标。<br/>默认值:0<br/>默认单位:vp<br/>异常值按照默认值处理。 |
71| width | string \| number | 否 | 形状视口的宽度。<br/>默认值:0<br/>默认单位:vp<br/>异常值按照默认值处理。 |
72| height | string \| number | 否 | 形状视口的高度。<br/>默认值:0<br/>默认单位:vp<br/>异常值按照默认值处理。 |
73
74### fill
75
76fill(value: ResourceColor)
77
78设置填充区域的颜色,异常值按照默认值处理。与通用属性foregroundColor同时设置时,后设置的属性生效。
79
80**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
81
82**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
83
84**系统能力:** SystemCapability.ArkUI.ArkUI.Full
85
86**参数:**
87
88| 参数名 | 类型                                       | 必填 | 说明                                   |
89| ------ | ------------------------------------------ | ---- | -------------------------------------- |
90| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 填充区域颜色。<br/>默认值:Color.Black |
91
92### fillOpacity
93
94fillOpacity(value: number | string | Resource)
95
96设置填充区域透明度。取值范围是[0.0, 1.0],若给定值小于0.0,则取值为0.0;若给定值大于1.0,则取值为1.0,其余异常值按1.0处理。
97
98**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
99
100**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
101
102**系统能力:** SystemCapability.ArkUI.ArkUI.Full
103
104**参数:**
105
106| 参数名 | 类型                                                         | 必填 | 说明                           |
107| ------ | ------------------------------------------------------------ | ---- | ------------------------------ |
108| value  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 填充区域透明度。<br/>默认值:1 |
109
110### stroke
111
112stroke(value: ResourceColor)
113
114设置边框颜色,不设置时,默认没有边框。异常值不会绘制边框。
115
116**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
117
118**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
119
120**系统能力:** SystemCapability.ArkUI.ArkUI.Full
121
122**参数:**
123
124| 参数名 | 类型                                       | 必填 | 说明       |
125| ------ | ------------------------------------------ | ---- | ---------- |
126| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 边框颜色。 |
127
128### strokeDashArray
129
130strokeDashArray(value: Array&lt;any&gt;)
131
132设置边框间隙。异常值按照默认值处理。
133
134**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
135
136**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
137
138**系统能力:** SystemCapability.ArkUI.ArkUI.Full
139
140**参数:**
141
142| 参数名 | 类型             | 必填 | 说明                      |
143| ------ | ---------------- | ---- | ------------------------- |
144| value  | Array&lt;any&gt; | 是   | 边框间隙。<br/>默认值:[]<br/>默认单位:vp |
145
146### strokeDashOffset
147
148strokeDashOffset(value: number | string)
149
150设置边框绘制起点的偏移量。异常值按照默认值处理。
151
152**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
153
154**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
155
156**系统能力:** SystemCapability.ArkUI.ArkUI.Full
157
158**参数:**
159
160| 参数名 | 类型                       | 必填 | 说明                                 |
161| ------ | -------------------------- | ---- | ------------------------------------ |
162| value  | number&nbsp;\|&nbsp;string | 是   | 边框绘制起点的偏移量。<br/>默认值:0<br/>默认单位:vp |
163
164### strokeLineCap
165
166strokeLineCap(value: LineCapStyle)
167
168设置边框端点绘制样式。
169
170**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
171
172**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
173
174**系统能力:** SystemCapability.ArkUI.ArkUI.Full
175
176**参数:**
177
178| 参数名 | 类型                                              | 必填 | 说明                                             |
179| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ |
180| value  | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | 是   | 边框端点绘制样式。<br/>默认值:LineCapStyle.Butt |
181
182### strokeLineJoin
183
184strokeLineJoin(value: LineJoinStyle)
185
186设置边框拐角绘制样式。
187
188**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
189
190**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
191
192**系统能力:** SystemCapability.ArkUI.ArkUI.Full
193
194**参数:**
195
196| 参数名 | 类型                                                | 必填 | 说明                                               |
197| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- |
198| value  | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | 是   | 边框拐角绘制样式。<br/>默认值:LineJoinStyle.Miter |
199
200### strokeMiterLimit
201
202strokeMiterLimit(value: number | string)
203
204设置斜接长度与边框宽度比值的极限值。斜接长度表示外边框外边交点到内边交点的距离,边框宽度即strokeWidth属性的值。该属性取值需在strokeLineJoin属性取值LineJoinStyle.Miter时生效。
205
206该属性的合法值范围应当大于等于1.0,当取值范围在[0,1)时按1.0处理,其余异常值按默认值处理。
207
208**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
209
210**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
211
212**系统能力:** SystemCapability.ArkUI.ArkUI.Full
213
214**参数:**
215
216| 参数名 | 类型                       | 必填 | 说明                                           |
217| ------ | -------------------------- | ---- | ---------------------------------------------- |
218| value  | number&nbsp;\|&nbsp;string | 是   | 斜接长度与边框宽度比值的极限值。<br/>默认值:4 |
219
220### strokeOpacity
221
222strokeOpacity(value: number | string | Resource)
223
224设置边框透明度。该属性的取值范围是[0.0, 1.0],若给定值小于0.0,则取值为0.0;若给定值大于1.0,则取值为1.0,其余异常值按1.0处理 。
225
226**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
227
228**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
229
230**系统能力:** SystemCapability.ArkUI.ArkUI.Full
231
232**参数:**
233
234| 参数名 | 类型                                                         | 必填 | 说明                       |
235| ------ | ------------------------------------------------------------ | ---- | -------------------------- |
236| value  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 边框透明度。<br/>默认值:1 |
237
238### strokeWidth
239
240strokeWidth(value: number | string)
241
242设置边框宽度。该属性若为string类型, 暂不支持百分比,百分比按照1px处理。
243
244**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
245
246**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
247
248**系统能力:** SystemCapability.ArkUI.ArkUI.Full
249
250**参数:**
251
252| 参数名 | 类型                         | 必填 | 说明                     |
253| ------ | ---------------------------- | ---- | ------------------------ |
254| value  | number&nbsp;\|&nbsp;string | 是   | 边框宽度。<br/>默认值:1<br/>默认单位:vp |
255
256### antiAlias
257
258antiAlias(value: boolean)
259
260设置是否开启抗锯齿效果。
261
262**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
263
264**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
265
266**系统能力:** SystemCapability.ArkUI.ArkUI.Full
267
268**参数:**
269
270| 参数名 | 类型    | 必填 | 说明                                  |
271| ------ | ------- | ---- | ------------------------------------- |
272| value  | boolean | 是   | 是否开启抗锯齿效果。<br/>默认值:true |
273
274### mesh<sup>8+</sup>
275
276mesh(value: Array&lt;number&gt;, column: number, row: number)
277
278设置mesh效果。
279
280**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。
281
282**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
283
284**系统能力:** SystemCapability.ArkUI.ArkUI.Full
285
286**参数:**
287
288| 参数名 | 类型                | 必填 | 说明                                                         |
289| ------ | ------------------- | ---- | ------------------------------------------------------------ |
290| value  | Array&lt;number&gt; | 是   | 长度(column + 1)* (row + 1)* 2的数组,它记录了扭曲后的位图各个顶点位置。 |
291| column | number              | 是   | mesh矩阵列数。                                               |
292| row    | number              | 是   | mesh矩阵行数。                                               |
293
294## 示例
295
296Shape绘制矩形、椭圆、直线路径。
297
298```ts
299// xxx.ets
300@Entry
301@Component
302struct ShapeExample {
303  build() {
304    Column({ space: 10 }) {
305      Text('basic').fontSize(11).fontColor(0xCCCCCC).width(320)
306      // 在Shape的(-2, -2)点绘制一个 300 * 50 带边框的矩形,颜色0x317AF7,边框颜色黑色,边框宽度4,边框间隙20,向左偏移10,线条两端样式为半圆,拐角样式圆角,抗锯齿(默认开启)
307      // 在Shape的(-2, 58)点绘制一个 300 * 50 带边框的椭圆,颜色0x317AF7,边框颜色黑色,边框宽度4,边框间隙20,向左偏移10,线条两端样式为半圆,拐角样式圆角,抗锯齿(默认开启)
308      // 在Shape的(-2, 118)点绘制一个 300 * 10 直线路径,颜色0x317AF7,边框颜色黑色,宽度4,间隙20,向左偏移10,线条两端样式为半圆,拐角样式圆角,抗锯齿(默认开启)
309      Shape() {
310        Rect().width(300).height(50)
311        Ellipse().width(300).height(50).offset({ x: 0, y: 60 })
312        Path().width(300).height(10).commands('M0 0 L900 0').offset({ x: 0, y: 120 })
313      }
314      .width(350)
315      .height(140)
316      .viewPort({ x: -2, y: -2, width: 304, height: 130 })
317      .fill(0x317AF7)
318      .stroke(Color.Black)
319      .strokeWidth(4)
320      .strokeDashArray([20])
321      .strokeDashOffset(10)
322      .strokeLineCap(LineCapStyle.Round)
323      .strokeLineJoin(LineJoinStyle.Round)
324      .antiAlias(true)
325      // 分别在Shape的(0, 0)、(-5, -5)点绘制一个 300 * 50 带边框的矩形,可以看出之所以将视口的起始位置坐标设为负值是因为绘制的起点默认为线宽的中点位置,因此要让边框完全显示则需要让视口偏移半个线宽
326      Shape() {
327        Rect().width(300).height(50)
328      }
329      .width(350)
330      .height(80)
331      .viewPort({ x: 0, y: 0, width: 320, height: 70 })
332      .fill(0x317AF7)
333      .stroke(Color.Black)
334      .strokeWidth(10)
335
336      Shape() {
337        Rect().width(300).height(50)
338      }
339      .width(350)
340      .height(80)
341      .viewPort({ x: -5, y: -5, width: 320, height: 70 })
342      .fill(0x317AF7)
343      .stroke(Color.Black)
344      .strokeWidth(10)
345
346      Text('path').fontSize(11).fontColor(0xCCCCCC).width(320)
347      // 在Shape的(0, -5)点绘制一条直线路径,颜色0xEE8443,线条宽度10,线条间隙20
348      Shape() {
349        Path().width(300).height(10).commands('M0 0 L900 0')
350      }
351      .width(350)
352      .height(20)
353      .viewPort({ x: 0, y: -5, width: 300, height: 20 })
354      .stroke(0xEE8443)
355      .strokeWidth(10)
356      .strokeDashArray([20])
357      // 在Shape的(0, -5)点绘制一条直线路径,颜色0xEE8443,线条宽度10,线条间隙20,向左偏移10
358      Shape() {
359        Path().width(300).height(10).commands('M0 0 L900 0')
360      }
361      .width(350)
362      .height(20)
363      .viewPort({ x: 0, y: -5, width: 300, height: 20 })
364      .stroke(0xEE8443)
365      .strokeWidth(10)
366      .strokeDashArray([20])
367      .strokeDashOffset(10)
368      // 在Shape的(0, -5)点绘制一条直线路径,颜色0xEE8443,线条宽度10,透明度0.5
369      Shape() {
370        Path().width(300).height(10).commands('M0 0 L900 0')
371      }
372      .width(350)
373      .height(20)
374      .viewPort({ x: 0, y: -5, width: 300, height: 20 })
375      .stroke(0xEE8443)
376      .strokeWidth(10)
377      .strokeOpacity(0.5)
378      // 在Shape的(0, -5)点绘制一条直线路径,颜色0xEE8443,线条宽度10,线条间隙20,线条两端样式为半圆
379      Shape() {
380        Path().width(300).height(10).commands('M0 0 L900 0')
381      }
382      .width(350)
383      .height(20)
384      .viewPort({ x: 0, y: -5, width: 300, height: 20 })
385      .stroke(0xEE8443)
386      .strokeWidth(10)
387      .strokeDashArray([20])
388      .strokeLineCap(LineCapStyle.Round)
389      // 在Shape的(-20, -5)点绘制一个封闭路径,颜色0x317AF7,线条宽度10,边框颜色0xEE8443,拐角样式锐角(默认值)
390      Shape() {
391        Path().width(200).height(60).commands('M0 0 L400 0 L400 150 Z')
392      }
393      .width(300)
394      .height(200)
395      .viewPort({ x: -20, y: -5, width: 310, height: 90 })
396      .fill(0x317AF7)
397      .stroke(0xEE8443)
398      .strokeWidth(10)
399      .strokeLineJoin(LineJoinStyle.Miter)
400      .strokeMiterLimit(5)
401    }.width('100%').margin({ top: 15 })
402  }
403}
404```
405
406![zh-cn_image_0000001184628104](figures/zh-cn_image_0000001184628104.png)
407