• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Ellipse
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
22Ellipse(options?: EllipseOptions)
23
24**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
25
26**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
27
28**系统能力：** SystemCapability.ArkUI.ArkUI.Full
29
30**参数:**
31
32| 参数名 | 类型 | 必填 | 说明 |
33| -------- | -------- | -------- | -------- |
34| options | [EllipseOptions](ts-drawing-components-ellipse.md#ellipseoptions18对象说明) | 否 | 椭圆绘制尺寸 |
35
36## EllipseOptions<sup>18+</sup>对象说明
37
38用于描述Ellipse组件绘制属性。
39
40> **说明：**
41>
42> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。
43
44**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。
45
46**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
47
48**系统能力：** SystemCapability.ArkUI.ArkUI.Full
49
50| 名称 | 类型 | 只读 | 可选 | 说明 |
51| -------- | -------- | -------- | -------- | -------- |
52| width<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 宽度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>从API version 20开始，支持Resource类型。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 |
53| height<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 高度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>从API version 20开始，支持Resource类型。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 |
54
55## 属性
56
57除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性：
58
59### fill
60
61fill(value: ResourceColor)
62
63设置填充区域的颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，异常值按照默认值处理。与通用属性foregroundColor同时设置时，后设置的属性生效。
64
65**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
66
67**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
68
69**系统能力：** SystemCapability.ArkUI.ArkUI.Full
70
71**参数：**
72
73| 参数名 | 类型                                       | 必填 | 说明                                   |
74| ------ | ------------------------------------------ | ---- | -------------------------------------- |
75| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 填充区域颜色。<br/>默认值：Color.Black |
76
77### fillOpacity
78
79fillOpacity(value: number | string | Resource)
80
81设置填充区域透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
82
83**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
84
85**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
86
87**系统能力：** SystemCapability.ArkUI.ArkUI.Full
88
89**参数：**
90
91| 参数名 | 类型                                                         | 必填 | 说明                           |
92| ------ | ------------------------------------------------------------ | ---- | ------------------------------ |
93| 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 |
94
95### stroke
96
97stroke(value: ResourceColor)
98
99设置边框颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，不设置时，默认边框透明度为0，即没有边框。异常值不会绘制边框。
100
101**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
102
103**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
104
105**系统能力：** SystemCapability.ArkUI.ArkUI.Full
106
107**参数：**
108
109| 参数名 | 类型                                       | 必填 | 说明       |
110| ------ | ------------------------------------------ | ---- | ---------- |
111| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 边框颜色。 |
112
113### strokeDashArray
114
115strokeDashArray(value: Array&lt;any&gt;)
116
117设置边框间隙，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。取值范围应为≥0，异常值按照默认值处理。
118
119**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
120
121**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
122
123**系统能力：** SystemCapability.ArkUI.ArkUI.Full
124
125**参数：**
126
127| 参数名 | 类型             | 必填 | 说明                      |
128| ------ | ---------------- | ---- | ------------------------- |
129| value  | Array&lt;any&gt; | 是   | 边框间隙。<br/>默认值：[]（空数组）<br/>默认单位：vp |
130
131### strokeDashOffset
132
133strokeDashOffset(value: number | string)
134
135设置边框绘制起点的偏移量，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。异常值按照默认值处理。
136
137**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
138
139**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
140
141**系统能力：** SystemCapability.ArkUI.ArkUI.Full
142
143**参数：**
144
145| 参数名 | 类型                       | 必填 | 说明                                 |
146| ------ | -------------------------- | ---- | ------------------------------------ |
147| value  | number&nbsp;\|&nbsp;string | 是   | 边框绘制起点的偏移量。<br/>默认值：0<br/>默认单位：vp |
148
149### strokeLineCap
150
151strokeLineCap(value: LineCapStyle)
152
153设置边框端点绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
154
155**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
156
157**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
158
159**系统能力：** SystemCapability.ArkUI.ArkUI.Full
160
161**参数：**
162
163| 参数名 | 类型                                              | 必填 | 说明                                             |
164| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ |
165| value  | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | 是   | 边框端点绘制样式。<br/>默认值：LineCapStyle.Butt |
166
167### strokeLineJoin
168
169strokeLineJoin(value: LineJoinStyle)
170
171设置边框拐角绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。Ellipse组件无法形成拐角，该属性设置无效。
172
173**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
174
175**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
176
177**系统能力：** SystemCapability.ArkUI.ArkUI.Full
178
179**参数：**
180
181| 参数名 | 类型                                                | 必填 | 说明                                               |
182| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- |
183| value  | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | 是   | 边框拐角绘制样式。<br/>默认值：LineJoinStyle.Miter |
184
185### strokeMiterLimit
186
187strokeMiterLimit(value: number | string)
188
189设置斜接长度与边框宽度比值的极限值，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。Ellipse组件不支持设置尖角图形，该属性设置无效。
190
191**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
192
193**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
194
195**系统能力：** SystemCapability.ArkUI.ArkUI.Full
196
197**参数：**
198
199| 参数名 | 类型                       | 必填 | 说明                                           |
200| ------ | -------------------------- | ---- | ---------------------------------------------- |
201| value  | number&nbsp;\|&nbsp;string | 是   | 斜接长度与边框宽度比值的极限值。<br/>默认值：4 |
202
203### strokeOpacity
204
205strokeOpacity(value: number | string | Resource)
206
207设置边框透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性的取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理 。
208
209**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
210
211**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
212
213**系统能力：** SystemCapability.ArkUI.ArkUI.Full
214
215**参数：**
216
217| 参数名 | 类型                                                         | 必填 | 说明                       |
218| ------ | ------------------------------------------------------------ | ---- | -------------------------- |
219| value  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 边框透明度。<br/>默认值：[stroke](#stroke)接口设置的透明度。 |
220
221### strokeWidth
222
223strokeWidth(value: Length)
224
225设置边框宽度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性若为string类型, 暂不支持百分比，百分比按照1px处理。
226
227**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
228
229**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
230
231**系统能力：** SystemCapability.ArkUI.ArkUI.Full
232
233**参数：**
234
235| 参数名 | 类型                         | 必填 | 说明                     |
236| ------ | ---------------------------- | ---- | ------------------------ |
237| value  | [Length](ts-types.md#length) | 是   | 边框宽度，取值范围≥0。<br/>默认值：1<br/>默认单位：vp<br/>异常值按照默认值处理。 |
238
239### antiAlias
240
241antiAlias(value: boolean)
242
243设置是否开启抗锯齿效果，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
244
245**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
246
247**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
248
249**系统能力：** SystemCapability.ArkUI.ArkUI.Full
250
251**参数：**
252
253| 参数名 | 类型    | 必填 | 说明                                  |
254| ------ | ------- | ---- | ------------------------------------- |
255| value  | boolean | 是   | 是否开启抗锯齿效果。<br/>true：开启抗锯齿；false：关闭抗锯齿。<br/>默认值：true |
256
257## 示例
258
259### 示例1（组件属性绘制）
260
261通过fillOpacity、stroke属性分别绘制椭圆的透明度、边框颜色。
262
263```ts
264// xxx.ets
265@Entry
266@Component
267struct EllipseExample {
268  build() {
269    Column({ space: 10 }) {
270      // 绘制一个 150 * 80 的椭圆
271      Ellipse({ width: 150, height: 80 })
272      // 绘制一个 150 * 100 、线条为蓝色的椭圆环
273      Ellipse()
274        .width(150)
275        .height(100)
276        .fillOpacity(0)
277        .stroke(Color.Blue)
278        .strokeWidth(3)
279    }.width('100%')
280  }
281}
282```
283
284![zh-cn_image_0000001174104394](figures/zh-cn_image_0000001174104394.png)
285
286### 示例2（宽和高使用不同参数类型绘制椭圆）
287
288width、height属性分别使用不同的长度类型绘制椭圆。
289
290```ts
291// xxx.ets
292@Entry
293@Component
294struct EllipseTypeExample {
295  build() {
296    Column({ space: 10 }) {
297      // 绘制一个 150 * 80 的椭圆
298      Ellipse({ width: '150', height: '80' }) // 使用string类型
299      // 绘制一个 80 * 150 的椭圆
300      Ellipse({ width: 80, height: 150 }) // 使用number类型
301      // 绘制一个 150 * 150 的椭圆
302      Ellipse({ width: $r('app.string.EllipseWidth'), height: $r('app.string.EllipseHeight') }) // 使用Resource类型，需用户自定义
303    }.width('100%')
304  }
305}
306```
307
308![ellipseDemo2](figures/ellipseDemo2.png)
309
310### 示例3（使用attributeModifier动态设置Ellipse组件的属性）
311
312以下示例展示了如何使用attributeModifier动态设置Ellipse组件的fill、fillOpacity、stroke、strokeDashArray、strokeDashOffset、strokeLineCap、strokeOpacity、strokeWidth和antiAlias属性。
313
314```ts
315// xxx.ets
316class MyEllipseModifier implements AttributeModifier<EllipseAttribute> {
317  applyNormalAttribute(instance: EllipseAttribute): void {
318    // 填充颜色#707070，填充透明度0.5，边框颜色#2787D9，边框间隙[20]，向左偏移15，线条两端样式为半圆，边框透明度0.5，边框宽度10，抗锯齿开启
319    instance.fill("#707070")
320    instance.fillOpacity(0.5)
321    instance.stroke("#2787D9")
322    instance.strokeDashArray([20])
323    instance.strokeDashOffset("15")
324    instance.strokeLineCap(LineCapStyle.Round)
325    instance.strokeOpacity(0.5)
326    instance.strokeWidth(10)
327    instance.antiAlias(true)
328  }
329}
330
331@Entry
332@Component
333struct EllipseModifierDemo {
334  @State modifier: MyEllipseModifier = new MyEllipseModifier()
335
336  build() {
337    Column() {
338      Ellipse({ width: 150, height: 80 })
339        .attributeModifier(this.modifier)
340        .offset({ x: 20, y: 20 })
341    }
342  }
343}
344```
345
346![](figures/ellipseModifier.png)
347