• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Circle
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @zjsxstar-->
5<!--Designer: @sunbees-->
6<!--Tester: @liuli0427-->
7<!--Adviser: @HelloCrease-->
8
9 用于绘制圆形的组件。
10
11>  **说明：**
12>
13>  该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
14
15
16## 子组件
17
18无
19
20
21## 接口
22
23Circle(value?: CircleOptions)
24
25**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
26
27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
28
29**系统能力：** SystemCapability.ArkUI.ArkUI.Full
30
31**参数：**
32
33| 参数名 | 类型 | 必填 | 说明 |
34| -------- | -------- | -------- | -------- |
35| value | [CircleOptions](#circleoptions对象说明) | 否 | 设置圆形尺寸 |
36
37## CircleOptions对象说明
38
39用于描述Circle组件绘制属性。
40
41**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
42
43**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
44
45**系统能力：** SystemCapability.ArkUI.ArkUI.Full
46
47| 名称 | 类型 | 只读 | 可选 | 说明 |
48| -------- | -------- | -------- | -------- | -------- |
49| width | [Length](ts-types.md#length) | 否 | 是 | 宽度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。 |
50| height | [Length](ts-types.md#length) | 否 | 是 | 高度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。 |
51
52## 属性
53
54除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性：
55
56### fill
57
58fill(value: ResourceColor)
59
60设置填充区域的颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，异常值按照默认值处理。与通用属性foregroundColor同时设置时，后设置的属性生效。
61
62**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
63
64**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
65
66**系统能力：** SystemCapability.ArkUI.ArkUI.Full
67
68**参数：**
69
70| 参数名 | 类型                                       | 必填 | 说明                                   |
71| ------ | ------------------------------------------ | ---- | -------------------------------------- |
72| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 填充区域颜色。<br/>默认值：Color.Black |
73
74### fillOpacity
75
76fillOpacity(value: number | string | Resource)
77
78设置填充区域透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
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  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 填充区域透明度。<br/>**说明：**<br/>number格式取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理。<br/>string格式支持number格式取值的字符串，取值范围与number格式相同。<br/>Resource格式支持系统资源或者应用资源中的字符串，取值范围和number格式相同。<br/>默认值：1 |
91
92### stroke
93
94stroke(value: ResourceColor)
95
96设置边框颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，不设置时，默认边框透明度为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  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 边框颜色。 |
109
110### strokeDashArray
111
112strokeDashArray(value: Array&lt;any&gt;)
113
114设置边框间隙，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。取值范围≥0，异常值按照默认值处理。
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  | Array&lt;any&gt; | 是   | 边框间隙。<br/>默认值：[]（空数组）<br/>默认单位：vp |
127
128### strokeDashOffset
129
130strokeDashOffset(value: number | string)
131
132设置边框绘制起点的偏移量，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。异常值按照默认值处理。
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  | number&nbsp;\|&nbsp;string | 是   | 边框绘制起点的偏移量。<br/>默认值：0<br/>默认单位：vp |
145
146### strokeLineCap
147
148strokeLineCap(value: LineCapStyle)
149
150设置边框端点绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
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  | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | 是   | 边框端点绘制样式。<br/>默认值：LineCapStyle.Butt |
163
164### strokeLineJoin
165
166strokeLineJoin(value: LineJoinStyle)
167
168设置边框拐角绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。Circle组件无法形成拐角，该属性设置无效。
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  | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | 是   | 边框拐角绘制样式。<br/>默认值：LineJoinStyle.Miter |
181
182### strokeMiterLimit
183
184strokeMiterLimit(value: number | string)
185
186设置斜接长度与边框宽度比值的极限值，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。Circle组件无法设置尖角图形，该属性设置无效。
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  | number&nbsp;\|&nbsp;string | 是   | 斜接长度与边框宽度比值的极限值。<br/>默认值：4 |
199
200### strokeOpacity
201
202strokeOpacity(value: number | string | Resource)
203
204设置边框透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性的取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理。
205
206**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
207
208**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
209
210**系统能力：** SystemCapability.ArkUI.ArkUI.Full
211
212**参数：**
213
214| 参数名 | 类型                                                         | 必填 | 说明                       |
215| ------ | ------------------------------------------------------------ | ---- | -------------------------- |
216| value  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 边框透明度。<br/>默认值：[stroke](#stroke)接口设置的透明度。 |
217
218### strokeWidth
219
220strokeWidth(value: Length)
221
222设置边框宽度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性若为string类型，暂不支持百分比，百分比按照1px处理。
223
224**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
225
226**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
227
228**系统能力：** SystemCapability.ArkUI.ArkUI.Full
229
230**参数：**
231
232| 参数名 | 类型                         | 必填 | 说明                     |
233| ------ | ---------------------------- | ---- | ------------------------ |
234| value  | [Length](ts-types.md#length) | 是   | 边框宽度，取值范围≥0。<br/>默认值：1<br/>默认单位：vp<br/>异常值按照默认值处理。 |
235
236### antiAlias
237
238antiAlias(value: boolean)
239
240设置是否开启抗锯齿效果，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
241
242**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
243
244**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
245
246**系统能力：** SystemCapability.ArkUI.ArkUI.Full
247
248**参数：**
249
250| 参数名 | 类型    | 必填 | 说明                                  |
251| ------ | ------- | ---- | ------------------------------------- |
252| value  | boolean | 是   | 是否开启抗锯齿效果。<br/>-true：开启抗锯齿。<br/>-false：关闭抗锯齿。<br/>默认值：true |
253
254## 示例
255
256### 示例1（组件属性绘制）
257
258通过fillOpacity、stroke、strokeDashArray属性可分别设置圆的透明度、边框颜色和边框间隙样式。
259
260```ts
261// xxx.ets
262@Entry
263@Component
264struct CircleExample {
265  build() {
266    Column({ space: 10 }) {
267      // 绘制一个直径为150的圆
268      Circle({ width: 150, height: 150 })
269      // 绘制一个直径为150、线条为红色虚线的圆环（宽高设置不一致时以短边为直径）
270      Circle()
271        .width(150)
272        .height(200)
273        .fillOpacity(0)
274        .strokeWidth(3)
275        .stroke(Color.Red)
276        .strokeDashArray([1, 2])
277    }.width('100%')
278  }
279}
280```
281
282![zh-cn_image_0000001219744191](figures/zh-cn_image_0000001219744191.png)
283
284### 示例2（宽和高使用不同参数类型绘制圆）
285
286width、height属性分别使用不同的长度类型绘制圆。
287
288```ts
289// xxx.ets
290@Entry
291@Component
292struct CircleTypeExample {
293  build() {
294    Column({ space: 10 }) {
295      // 绘制一个直径为50的圆
296      Circle({ width: '50', height: '50' }) // 使用string类型
297      // 绘制一个直径为100的圆
298      Circle({ width: 100, height: 100 }) // 使用number类型
299      // 绘制一个直径为150的圆
300      Circle({ width: $r('app.string.CircleWidth'), height: $r('app.string.CircleHeight') }) // 使用Resource类型，需用户自定义
301    }.width('100%')
302  }
303}
304```
305
306![circleDemo2](figures/circleDemo2.png)
307
308### 示例3（使用attributeModifier动态设置Circle组件的属性）
309
310以下示例展示了如何使用attributeModifier动态设置Circle组件的fill、fillOpacity、stroke、strokeDashArray、strokeDashOffset、strokeLineCap、strokeOpacity、strokeWidth和antiAlias属性。
311
312```ts
313// xxx.ets
314class MyCircleModifier implements AttributeModifier<CircleAttribute> {
315  applyNormalAttribute(instance: CircleAttribute): void {
316    // 填充颜色#707070，填充透明度0.5，边框颜色#2787D9，边框间隙[20]，向左偏移15，线条两端样式为半圆，边框透明度0.5，边框宽度10，抗锯齿开启
317    instance.fill("#707070")
318    instance.fillOpacity(0.5)
319    instance.stroke("#2787D9")
320    instance.strokeDashArray([20])
321    instance.strokeDashOffset("15")
322    instance.strokeLineCap(LineCapStyle.Round)
323    instance.strokeOpacity(0.5)
324    instance.strokeWidth(10)
325    instance.antiAlias(true)
326  }
327}
328
329@Entry
330@Component
331struct CircleModifierDemo {
332  @State modifier: MyCircleModifier = new MyCircleModifier()
333
334  build() {
335    Column() {
336      Circle({ width: 150, height: 150 })
337        .attributeModifier(this.modifier)
338        .offset({ x: 20, y: 20 })
339    }
340  }
341}
342```
343
344![](figures/circleModifier.png)
345