仓颉 ArkUI 图形绘制通用属性实战指南:fill、stroke 与 antiAlias 全解析

原创2026-10-15 18:27:181,949 阅读
文章标签:文档知识库

仓颉 ArkUI 图形绘制通用属性实战指南:fill、stroke 与 antiAlias 全解析

本文聚焦仓颉语言 ArkUI 框架中的图形绘制通用属性(Graphics Drawing Common Attributes),系统讲解其适用范围、全部 11 个属性的签名与语义、底层类型(ResourceColor、Length、AppResource 等)的设计,并结合仓库内 Shape 容器与示例代码给出可直接运行的完整方案。读完本文,你将能够为 Circle、Ellipse、Line、Path、Rect、Shape 等绘制组件精确设置填充、描边、虚线、线帽、拐角与抗锯齿效果。

适用范围与基础准备

图形绘制通用属性是一组由所有绘制组件共同继承的属性集合,目前支持以下组件,各组件文档均通过“通用属性”小节引用本组属性:

在代码中使用这些属性前,需要导入 ArkUI 模块:

import kit.ArkUI.*

所有属性均声明为 SystemCapability.ArkUI.ArkUI.Full,起始版本为 22,即要求运行环境具备完整的 ArkUI 系统能力。

填充区域相关属性

填充属性决定图形内部区域的视觉表现,包括颜色与透明度两个维度。

func fill(?ResourceColor)

public func fill(value: ?ResourceColor): T

设置填充区域的颜色。参数说明如下:

参数名 类型 必填 默认值 说明
value ?ResourceColor 是 - 填充颜色。初始值:Color.Black。

两点关键语义:

  1. 异常值回退:传入的异常颜色值按照初始值(Color.Black)处理。
  2. 与 foregroundColor 的优先级:若同时设置了通用属性 foregroundColor(前景色设置),后设置的属性生效——这决定了链式调用中书写的顺序直接决定最终渲染结果。

func fillOpacity(?Float64)

public func fillOpacity(value: ?Float64): T

设置填充区域透明度,取值范围 [0.0, 1.0],取值规则如下:

  • 给定值小于 0.0 → 按 0.0 处理;
  • 给定值大于 1.0 → 按 1.0 处理;
  • 其余异常值 → 按 1.0 处理;
  • 1.0 代表完全不透明,0.0 代表完全透明。
参数名 类型 必填 默认值 说明
value ?Float64 是 - 填充透明度。初始值:1.0。

func fillOpacity(?AppResource)

public func fillOpacity(value: ?AppResource): T

与 Float64 重载版本语义一致,但透明度来源于资源对象,便于通过资源文件统一管理。取值规则为:[0, 1] 之外小于 0 按 0 处理、大于 1 按 1 处理,其余异常值按 1 处理。

参数名 类型 必填 默认值 说明
value ?AppResource 是 - 填充透明度。初始值:1.0。

AppResource 是资源引用类型,从源码声明可见其同时实现了 Length & ResourceColor & ResourceStr 三个接口,因此同一个资源对象既可作为颜色(fill/stroke),也可作为长度(strokeWidth)或透明度(fillOpacity/strokeOpacity)传入,体现了 ArkUI 类型设计的统一性:

public class AppResource <: Length & ResourceColor & ResourceStr {
    public var bundleName: String
    public var moduleName: String
    public var id: UInt32
    public var params:?Array<Any>
    public var resType:?Int32
    public init(
        bundleName: String,
        moduleName: String,
        id: UInt32,
        params!: ?Array<Any> = None,
        resType!: ?Int32 = None
    )
}

边框描边相关属性

描边属性控制图形轮廓的表现,涵盖颜色、宽度、透明度、虚线、线帽与拐角等维度。默认情况下图形没有边框。

func stroke(?ResourceColor)

public func stroke(value: ?ResourceColor): T

设置边框颜色。默认没有边框;异常值不会绘制边框。

参数名 类型 必填 默认值 说明
value ?ResourceColor 是 - 边框颜色。初始值:Color.Transparent。

关于 ResourceColor 类型,从其接口定义可以看到它定义了统一的 toUInt32() 转换方法,Color、UInt32、Int64、AppResource 均实现了该接口:

public interface ResourceColor {
    func toUInt32(): UInt32
}

因此示例代码中出现的 Color.Black、0x317AF7、0xEE8443 等写法均可直接作为 stroke 与 fill 的参数。

func strokeWidth(?Length)

public func strokeWidth(value: ?Length): T

设置边框宽度。

参数名 类型 必填 默认值 说明
value ?Length 是 - 边框宽度。初始值:1.vp。

func strokeOpacity(?Float64)

public func strokeOpacity(value: ?Float64): T

设置边框透明度,取值规则与 fillOpacity(?Float64) 完全一致:[0.0, 1.0] 区间裁剪,其余异常值按 1.0 处理。初始值:1.0。

func strokeOpacity(?AppResource)

public func strokeOpacity(value: ?AppResource): T

通过资源对象设置边框透明度的重载版本。初始值:1.0。

func strokeDashArray(?Array)

public func strokeDashArray(value: ?Array<Length>): T

设置边框间隙,即边框虚线的“画线-留白”周期数组。数组中的每个元素依次表示实线段的长度与空白段的长度。

参数名 类型 必填 默认值 说明
value ?Array<Length> 是 - 边框虚线数组。初始值:[]。

例如 strokeDashArray([20]) 表示画 20 长度线段、空 20 长度,循环往复;strokeDashArray([20, 10]) 则实现 20/10 的非对称虚线周期。

func strokeDashOffset(?Length)

public func strokeDashOffset(value: ?Length): T

设置边框绘制起点的偏移量,即在虚线周期中“跳过”的起始长度,常用于实现流动虚线动画或调整虚线相位。异常值按初始值处理。

参数名 类型 必填 默认值 说明
value ?Length 是 - 边框虚线偏移量。初始值:0.vp。

func strokeLineCap(?LineCapStyle)

public func strokeLineCap(value: ?LineCapStyle): T

设置边框端点(线帽)的绘制样式。可选值定义于 LineCapStyle 枚举:

public enum LineCapStyle <: Equatable<LineCapStyle> {
    | Butt
    | Round
    | Square
    | ...
}
枚举值 功能说明
Butt 线条两端为平行线,不额外扩展(初始值)
Round 在线条两端延伸半个圆,直径等于线宽
Square 在线条两端延伸半个方形,边长等于线宽

注意:仓库文档中 Square 的“功能”描述文字与 Round 相同(均写作“延伸半个圆”),但语义上 Square 为方形端帽;从枚举命名与通用 SVG 规范可以推断其呈现为方形扩展。实际开发时可按需选用。

func strokeLineJoin(?LineJoinStyle)

public func strokeLineJoin(value: ?LineJoinStyle): T

设置边框拐角(路径段连接点)的绘制样式。可选值定义于 LineJoinStyle 枚举:

public enum LineJoinStyle <: Equatable<LineJoinStyle> {
    | Miter
    | Round
    | Bevel
    | ...
}
枚举值 功能说明
Miter 使用尖角连接路径段(初始值)
Round 使用圆角连接路径段
Bevel 使用斜角连接路径段

func strokeMiterLimit(?Float64)

public func strokeMiterLimit(miterLimit: ?Float64): T

设置斜接长度与边框宽度比值的极限值。斜接长度指外边框外边交点到内边交点的距离,边框宽度即 strokeWidth 属性的值。该属性仅在 strokeLineJoin 取值为 LineJoinStyle.Miter 时生效。

合法值范围应大于等于 1.0:当取值范围在 [0, 1) 时按 1.0 处理,其余异常值按初始值处理。

参数名 类型 必填 默认值 说明
miterLimit ?Float64 是 - 斜接长度与边框宽度比值的极限值。初始值:4.0。

简单理解:当两条描边线段以很尖锐的角度相交时,斜接长度可能远超线宽;miterLimit 用于限制这种尖角的最大尖锐程度,超过阈值后引擎会自动退化为斜角(Bevel)连接,避免视觉上出现过长的针尖。

渲染质量属性

func antiAlias(?Bool)

public func antiAlias(value: ?Bool): T

设置是否开启抗锯齿。开启后边缘会通过平滑过渡消除“锯齿”感,适合圆形、斜线等非水平垂直图形;对于大尺寸纯色图形,可根据性能需求权衡是否关闭。

参数名 类型 必填 默认值 说明
value ?Bool 是 - 是否开启抗锯齿。初始值:true。

关键类型速查

多个属性的参数类型指向 cj-common-types.md 中定义的通用接口,理解它们才能正确传参:

类型 定义要点 可实现/可传入的取值
ResourceColor func toUInt32(): UInt32 Color、UInt32(如 0x317AF7)、Int64、AppResource
Length prop value: Float64、prop unitType: LengthUnit Float64、Int64、AppResource 均实现该接口
AppResource 资源引用类,含 bundleName/moduleName/id 等字段 同时可作为颜色、长度、字符串、透明度

Length 接口从源码看包含 value 与 unitType 两个只读属性,单位由 LengthUnit 枚举 描述。仓颉提供 4 种像素单位,以 vp 为基准,参见像素单位文档:

  • px:屏幕物理像素单位;
  • vp:屏幕密度相关像素,不带单位时默认 vp;
  • fp:字体像素,随系统字体大小设置变化;
  • lpx:视窗逻辑像素单位,与 designWidth 配置相关(默认 720)。

综合示例:一次掌握全部通用属性

以下示例完整来自 cj-graphic-drawing-common.md,演示了在 Shape 容器内组合使用填充、描边、虚线、线帽、拐角与抗锯齿属性,并与 Shape 文档示例相互印证:

package ohos_app_cangjie_entry
import ohos.base.*
import ohos.arkui.component.*
import ohos.arkui.state_management.*
import ohos.arkui.state_macro_manage.*

@Entry
@Component
class EntryView {
    func build() {
        Column(space: 10) {
            Text("basic")
                .fontSize(11)
                .fontColor(0xCCCCCC)
                .width(320)
            Shape() {
                Rect()
                    .width(300)
                    .height(50)
                Ellipse()
                    .width(300)
                    .height(50)
                    .offset(x: 0, y: 60)
                Path()
                    .width(300)
                    .height(10)
                    .commands("M0 0 L900 0")
                    .offset(x: 0, y: 120)
            }
            .width(350)
            .height(140)
            .viewPort(x: -2, y: -2, width: 304, height: 130)
            .fill(0x317AF7)
            .stroke(Color.Black)
            .strokeWidth(4)
            .strokeDashArray([20])
            .strokeDashOffset(10)
            .strokeLineCap(LineCapStyle.Round)
            .strokeLineJoin(LineJoinStyle.Round)
            .antiAlias(true)
            // 分别在Shape的(0, 0)、(-5, -5)点绘制一个 300 * 50 带边框的矩形,可以看出之所以将视口的起始位置坐标设为负值是因为绘制的起点默认为线宽的中点位置,因此要让边框完全显示则需要让视口偏移半个线宽
            Shape() {
                Rect()
                    .width(300)
                    .height(50)
            }
            .width(350)
            .height(80)
            .viewPort(x: 0, y: 0, width: 320, height: 70)
            .fill(0x317AF7)
            .stroke(Color.Black)
            .strokeWidth(10)

            Shape() {
                Rect()
                    .width(300)
                    .height(50)
            }
            .width(350)
            .height(80)
            .viewPort(x: -5, y: -5, width: 320, height: 70)
            .fill(0x317AF7)
            .stroke(Color.Black)
            .strokeWidth(10)

            Text("path")
                .fontSize(11)
                .fontColor(0xCCCCCC)
                .width(320)
            // 在Shape的(0, -5)点绘制一条直线路径,颜色0xEE8443,线条宽度10,线条间隙20
            Shape() {
                Path()
                    .width(300)
                    .height(10)
                    .commands("M0 0 L900 0")
            }
            .width(350)
            .height(20)
            .viewPort(x: 0, y: -5, width: 300, height: 20)
            .stroke(0xEE8443)
            .strokeWidth(10)
            .strokeDashArray([20])
            // 在Shape的(0, -5)点绘制一条直线路径,颜色0xEE8443,线条宽度10,线条间隙20,向左偏移10
            Shape() {
                Path()
                    .width(300)
                    .height(10)
                    .commands("M0 0 L900 0")
            }
            .width(350)
            .height(20)
            .viewPort(x: 0, y: -5, width: 300, height: 20)
            .stroke(0xEE8443)
            .strokeWidth(10)
            .strokeDashArray([20])
            .strokeDashOffset(10)
            // 在Shape的(0, -5)点绘制一条直线路径,颜色0xEE8443,线条宽度10,透明度0.5
            Shape() {
                Path()
                    .width(300)
                    .height(10)
                    .commands("M0 0 L900 0")
            }
            .width(350)
            .height(20)
            .viewPort(x: 0, y: -5, width: 300, height: 20)
            .stroke(0xEE8443)
            .strokeWidth(10)
            .strokeOpacity(0.5)
            // 在Shape的(0, -5)点绘制一条直线路径,颜色0xEE8443,线条宽度10,线条间隙20,线条两端样式为半圆
            Shape() {
                Path()
                    .width(300)
                    .height(10)
                    .commands("M0 0 L900 0")
            }
            .width(350)
            .height(20)
            .viewPort(x: 0, y: -5, width: 300, height: 20)
            .stroke(0xEE8443)
            .strokeWidth(10)
            .strokeDashArray([20])
            .strokeLineCap(LineCapStyle.Round)
            // 在Shape的(-20, -5)点绘制一个封闭路径,颜色0x317AF7,线条宽度10,边框颜色0xEE8443,拐角样式锐角(初始值)
            Shape() {
                Path()
                    .width(200)
                    .height(60)
                    .commands("M0 0 L400 0 L400 150 Z")
            }
            .width(300)
            .height(200)
            .viewPort(x: -20, y: -5, width: 310, height: 90)
            .fill(0x317AF7)
            .stroke(0xEE8443)
            .strokeWidth(10)
            .strokeLineJoin(LineJoinStyle.Miter)
            .strokeMiterLimit(5.0)
        }.width(100.percent).margin(top: 15)
    }
}

实战要点与边界行为

结合示例代码与属性语义,有以下实践要点值得注意:

  1. 视口与半线宽问题:示例注释明确指出,绘制起点默认为线宽的中点位置,因此带边框图形若要完整显示,需让视口偏移半个线宽。对比示例中两个矩形:viewPort(x: 0, y: 0) 时 10 线宽的边框会被裁剪一半,而 viewPort(x: -5, y: -5) 时边框完整可见。这是使用 strokeWidth 时最容易踩中的坑。

  2. fill 与 stroke 可组合使用:填充与描边相互独立,可同时设置(如封闭路径示例中 fill(0x317AF7) 配合 stroke(0xEE8443)),实现“蓝色填充 + 橙色描边”的经典图形效果。

  3. strokeMiterLimit 的生效前提:只有 strokeLineJoin(LineJoinStyle.Miter) 时 strokeMiterLimit 才起作用;改用 Round/Bevel 后该值不再影响渲染。

  4. Path 命令与描边属性配合:Path 组件的 commands 遵循 SVG 路径描述规范(M/L/H/V/C/S/Q/T/A/Z),示例中的 M0 0 L900 0 与 M0 0 L400 0 L400 150 Z 分别构造直线与闭合三角形路径,是验证线帽、拐角属性的理想载体。

  5. 透明度双通道:填充与描边各自拥有独立的透明度属性(fillOpacity/strokeOpacity),且均提供 Float64 与 AppResource 两种重载,便于静态写死或资源化配置。

总结

图形绘制通用属性为仓颉 ArkUI 的六类绘制组件提供了统一的视觉定制能力:fill/fillOpacity 控制填充,stroke/strokeWidth/strokeOpacity/strokeDashArray/strokeDashOffset/strokeLineCap/strokeLineJoin/strokeMiterLimit 控制描边,antiAlias 控制渲染质量。掌握这些属性及其异常值回退规则、类型体系与视口偏移技巧,即可在 Shape 容器中构建出精确、可复用的自定义图形界面。

登录后查看全文
CangjieCorpus