仓颉 ArkUI-CJ 图形绘制指南:Circle 圆形组件详解与实战示例
仓颉 ArkUI-CJ 图形绘制指南:Circle 圆形组件详解与实战示例
本文面向使用仓颉(Cangjie)语言进行 OpenHarmony 应用 UI 开发的开发者,围绕 Circle 组件参考文档 展开,系统讲解圆形绘制组件的创建方式、尺寸参数语义、图形绘制通用属性(填充、描边、虚线、线帽等)以及配套示例代码。读完本文后,你将能够在 ArkUI-CJ 页面中独立绘制实心圆、圆环、虚线圆环等多种圆形效果,并理解其与 Ellipse、Rect、Shape 等图形绘制组件之间的关联。
一、Circle 组件是什么
Circle 是 ArkUI-CJ 中用于绘制圆形的组件,属于图形绘制组件家族的一员。它与 Ellipse(椭圆)、Line(直线)、Path(路径)、Rect(矩形)以及 Shape(绘制父容器)共同构成了一套类似 SVG 的矢量图形绘制能力。Circle 既可以作为独立组件直接渲染在页面上,也可以作为 Shape 的子组件参与复杂图形的组合绘制。
根据 图形绘制通用属性文档,图形绘制通用属性适用于 Circle、Ellipse、Line、Path、Rect、Shape 等全部图形绘制组件,这意味着 Circle 拥有的绘制能力是整套图形绘制体系的公共能力,学会 Circle 即可举一反三。
1.1 导入模块
在仓颉源码中使用 Circle 组件前,需要导入 ArkUI 组件库:
import kit.ArkUI.*
1.2 子组件
Circle 组件不包含子组件,属于叶子绘制节点。若需要将多个图形组合绘制,应使用 Shape 作为父容器承载多个绘制组件(Shape 的子组件支持 Rect、Circle、Ellipse、Image、Text、Column、Row 及嵌套 Shape 等,详见 Shape 文档)。
二、创建 Circle 组件:init(?Length, ?Length)
2.1 构造器签名
Circle 组件的构造器签名如下:
public init(width!: ?Length = None, height!: ?Length = None)
两个参数均为命名参数(参数名后带 ! 表示命名参数),且都有默认值 None,因此可以通过 Circle()、Circle(width: 150)、Circle(width: 150, height: 150) 等多种方式创建组件。
2.2 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| width | ?Length | 否 | None | 命名参数。 宽度,取值范围 ≥ 0。初始值: 0.vp |
| height | ?Length | 否 | None | 命名参数。 高度,取值范围 ≥ 0。初始值: 0.vp |
核心语义: 该构造器用于绘制一个宽度为 width、高度为 height 的圆形。当宽高设置不一致时,以短边为直径绘制圆形;传入异常值(如负数、非数值)时,按照初始值 0.vp 处理。
2.3 Length 与 LengthUnit 类型详解
width 与 height 的参数类型是 ?Length。根据 cj-common-types.md 的定义,Length 是一个接口类型:
public interface Length {
prop value: Float64
prop unitType: LengthUnit
}
Float64、Int64、AppResource 均实现了 Length 接口,也就是说你可以在 Circle 尺寸参数中直接传入普通数值(默认按 vp 单位解释),也可以传入带单位后缀的数值,如 150.vp、300.px、50.percent 等。
LengthUnit 枚举(见 cj-common-types.md)定义了仓颉 UI 支持的 4 种像素单位,单位对照如下:
| 单位 | 含义 |
|---|---|
| Px | 屏幕物理像素单位 |
| Vp | 屏幕密度相关像素,数值不带单位时默认按 vp 处理 |
| Fp | 字体像素,随系统字体大小设置变化 |
| Percent | 百分比 |
| Lpx | 视窗逻辑像素单位,与 designWidth 配置相关(默认 720) |
更多像素单位换算(vp2px、px2vp、fp2px、lpx2px 等)可参考 像素单位文档。
三、Circle 的属性体系:通用属性 + 图形绘制通用属性
Circle 支持两类属性:
- 通用属性与通用事件:ArkUI 组件的通用属性(尺寸、位置、边框、背景、透明度、变换等)与通用事件(点击、触摸、焦点、可见区域变化等)全部支持。例如示例中的
.width(150)、.height(200)正是来自通用尺寸属性,其签名见 cj-universal-attribute-size.md。 - 图形绘制通用属性:定义在 图形绘制通用属性文档 中,本节逐一展开。
3.1 填充类属性
func fill(?ResourceColor) — 设置填充区域颜色,默认填充色为 Color.Black。若与通用属性 foregroundColor 同时设置,后设置的属性生效。ResourceColor 接口(见 cj-common-types.md)由 Color、UInt32、Int64、AppResource 共同实现,因此既可直接传 Color.Red,也可传 0x317AF7 这类整型色值。
func fillOpacity(?Float64) / func fillOpacity(?AppResource) — 设置填充区域透明度,取值范围 [0.0, 1.0]。小于 0.0 按 0.0 处理,大于 1.0 按 1.0 处理,其余异常值按 1.0 处理。1.0 代表完全不透明,0.0 代表完全透明,初始值 1.0。
巧用
fillOpacity(0.0):将填充透明度置为 0 而保留描边,即可把实心圆变成圆环/环形图形,这也是原文档示例中绘制圆环的核心手法。
3.2 描边类属性
描边(stroke)是 Circle 圆环效果的关键。默认没有边框(描边色初始值为 Color.Transparent),只有显式设置描边颜色后才可见。
| 属性 | 签名 | 说明 |
|---|---|---|
| stroke | func stroke(value: ?ResourceColor): T |
设置边框颜色,异常值不绘制边框,初始值 Color.Transparent |
| strokeWidth | func strokeWidth(value: ?Length): T |
设置边框宽度,初始值 1.vp |
| strokeOpacity | func strokeOpacity(value: ?Float64): T / (?AppResource) |
设置边框透明度,取值范围 [0.0, 1.0],初始值 1.0 |
| strokeDashArray | func strokeDashArray(value: ?Array<Length>): T |
设置边框虚线数组,如 [1, 2] 表示实线段 1、空白段 2 交替,初始值 [] |
| strokeDashOffset | func strokeDashOffset(value: ?Length): T |
设置边框绘制起点偏移量,初始值 0.vp |
| strokeLineCap | func strokeLineCap(value: ?LineCapStyle): T |
设置边框端点绘制样式,初始值 LineCapStyle.Butt |
| strokeLineJoin | func strokeLineJoin(value: ?LineJoinStyle): T |
设置边框拐角绘制样式,初始值 LineJoinStyle.Miter |
| strokeMiterLimit | func strokeMiterLimit(miterLimit: ?Float64): T |
斜接长度与边框宽度比值的极限值,仅在 LineJoinStyle.Miter 下生效,合法值应 ≥ 1.0,[0, 1) 按 1.0 处理,初始值 4.0 |
其中两个枚举类型定义于 cj-common-types.md:
- LineCapStyle(枚举定义):
Butt(两端为平行线,不额外扩展)、Round(两端延伸半圆,直径等于线宽)、Square(两端延伸半个方块,边长等于线宽)。 - LineJoinStyle(枚举定义):
Miter(尖角连接)、Round(圆角连接)、Bevel(斜角连接)。
说明:LineCapStyle 与 LineJoinStyle 主要针对开放线段与折线拐角生效。圆形本身是闭合且无拐角的图形,因此这两类属性对 Circle 的直接视觉影响有限,但 Circle 继承的这套属性体系在 Line、Path、Rect 等组件中会被高频使用。
3.3 渲染类属性
func antiAlias(?Bool) — 设置是否开启抗锯齿,初始值 true。开启后可有效改善圆形边缘在低分辨率屏幕上的锯齿感。
四、完整示例:实心圆与红色虚线圆环
原文档给出了一个可直接运行的双圆示例(源码见 cj-graphic-drawing-circle.md):
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*
@Entry
@Component
class EntryView {
func build() {
Column(space: 10) {
// 绘制一个直径为150的圆
Circle(width: 150, height: 150)
// 绘制一个直径为150、线条为红色虚线的圆环(宽高设置不一致时以短边为直径)
Circle()
.width(150)
.height(200)
.fillOpacity(0.0)
.strokeWidth(3)
.stroke(Color.Red)
.strokeDashArray([1, 2])
}.width(100.percent)
}
}
4.1 逐行解读
Circle(width: 150, height: 150):宽高一致,绘制直径为 150 的实心圆,使用默认黑色填充。Circle():不传参创建,随后用通用尺寸属性.width(150).height(200)指定宽高。由于宽高不一致(150 vs 200),按文档语义以短边 150 为直径绘制圆形。.fillOpacity(0.0):填充完全透明,圆内部不再填充颜色,仅保留描边轮廓。.strokeWidth(3):描边宽度 3vp。.stroke(Color.Red):描边颜色设为红色,轮廓显现。.strokeDashArray([1, 2]):描边按「实线 1、空白 2」的节奏绘制,形成虚线圆环。.width(100.percent):Column 父容器宽度占满父级 100%,为子图形提供布局约束。
细节点拨:原文档注释特别强调「宽高设置不一致时以短边为直径」,这正是
Circle()+.width(150).height(200)组合仍画出直径 150 圆的原因——Circle 组件本质上始终按短边取直径绘制正圆,而非像 Ellipse 那样拉伸为椭圆。
4.2 与 Ellipse 的行为对比
同为 init(?Length, ?Length) 构造器,Ellipse 组件 绘制的是「宽度为 width、高度为 height 的椭圆」,即宽高不等时表现为椭圆;而 Circle 强制为正圆、以短边为直径。二者填充、描边属性体系完全一致(Ellipse 示例同样使用 fillOpacity(0.0) + stroke(Color.Red) + strokeWidth(3) 绘制椭圆环),可作为对照参考。
五、进阶用法:Circle 结合 Shape 与属性组合
图形绘制通用属性文档中的示例展示了图形绘制组件在 Shape 容器内的组合用法,这些模式同样适用于 Circle:
Shape() {
Circle()
.width(150)
.height(150)
}
.width(200)
.height(200)
.viewPort(x: -5, y: -5, width: 170, height: 170)
.fill(0x317AF7)
.stroke(Color.Black)
.strokeWidth(4)
.strokeDashArray([20])
.strokeDashOffset(10)
.antiAlias(true)
viewPort(x, y, width, height)用于设置 Shape 的视口(见 Shape 组件属性)。参考图形绘制通用属性文档中的示例注释:绘制的起点默认位于线宽中点,若要让粗边框完整显示,视口起始坐标需偏移半个线宽(如线宽 10 时取 x: -5)。- Shape 容器上设置的 fill / stroke / strokeWidth / strokeDashArray 等图形绘制通用属性,会作用于容器内未单独设置该属性的子绘制组件;子组件上单独设置的属性优先。Circle 放入 Shape 后即可与其他图形(Rect、Ellipse、Path、Text、Image 等)组合出复合图形,实现类似 SVG 的叠加效果。
六、系统能力与版本约束
根据原文档,Circle 组件相关接口的约束如下:
- 系统能力: SystemCapability.ArkUI.ArkUI.Full(完整 ArkUI 系统能力)
- 起始版本: 22(API 版本 22 起可用)
图形绘制通用属性(fill、stroke 等)同样要求 SystemCapability.ArkUI.ArkUI.Full 且起始版本为 22,请确保目标设备与编译环境满足上述版本要求后再使用本指南中的代码。
七、小结
本文基于 Circle 组件参考文档 完整梳理了圆形绘制组件的使用要点:
- 创建方式:
Circle(width: 150, height: 150)直接指定宽高,或Circle()后配合通用尺寸属性设置;宽高不等时以短边为直径。 - 属性体系:Circle 完整支持通用属性、通用事件与 图形绘制通用属性(fill、fillOpacity、stroke、strokeWidth、strokeDashArray、strokeDashOffset、strokeLineCap、strokeLineJoin、strokeMiterLimit、strokeOpacity、antiAlias)。
- 实战技巧:
fillOpacity(0.0)+stroke*组合绘制圆环与虚线圆环;结合 Shape 与 viewPort 实现多图形组合与边框完整显示。 - 类型基础:Length/LengthUnit(vp、px、fp、percent、lpx)与 ResourceColor(Color、UInt32、Int64)等公共类型定义参见 cj-common-types.md。
这些能力与 Ellipse、Rect、Line、Path、Shape 一脉相承,掌握 Circle 之后,即可顺畅迁移到整套 ArkUI-CJ 矢量图形绘制体系中。