ArkUI 中的图形绘制 Path 组件详解

在 ArkUI 框架中，Path 组件是一个强大且灵活的工具，用于绘制自定义形状。它支持 SVG 路径描述规范，允许开发者通过设置各种属性（如宽度、高度、填充颜色、边框颜色等）来自定义形状的外观。本文将详细介绍 Path 组件的功能、使用方法及其在不同场景中的应用。

Path 组件概述

Path 组件从 API Version 7 开始支持，适用于 ArkTS 卡片和原子化服务。它提供了一种基于路径的绘图方式，允许开发者通过一系列命令来绘制复杂的形状。Path 组件的核心在于其 commands 属性，该属性接受一个符合 SVG 路径描述规范的字符串，用于定义路径的具体形状。

Path 组件的子组件

Path 组件没有子组件，它是一个独立的绘图单元，可以直接在 Canvas 或其他容器组件中使用。

Path 组件的接口

Path 组件的接口定义如下：

Path(value?: { width?: number | string; height?: number | string; commands?: string }) 

• value: 一个可选的对象，包含以下属性：
  • width: 路径所在矩形的宽度，取值范围≥0。值为异常值或缺省时按照自身内容需要的宽度处理。默认单位：vp。
  • height: 路径所在矩形的高度，取值范围≥0。值为异常值或缺省时按照自身内容需要的高度处理。默认单位：vp。
  • commands: 路径绘制的命令字符串。默认值："异常值按照默认值处理"。

Path 组件的属性

除了支持通用属性外，Path 组件还支持以下特定属性：

commands

commands(value: string): 设置符合 SVG 路径描述规范的命令字符串，单位为 px。像素单位转换方法请参考像素单位转换。

• 卡片能力：从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
• 原子化服务 API：从 API version 11 开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

fill

fill(value: ResourceColor): 设置填充颜色，不设置时，默认没有填充颜色。

• 卡片能力：从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
• 原子化服务 API：从 API version 11 开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

stroke

stroke(value: ResourceColor): 设置边框颜色，不设置时，默认没有边框线条。异常值不会绘制边框线条。

• 卡片能力：从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
• 原子化服务 API：从 API version 11 开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

strokeOpacity

strokeOpacity(value: number | string | Resource): 设置边框透明度。该属性的取值范围是 [0.0, 1.0]，若给定值小于 0.0，则取值为 0.0；若给定值大于 1.0，则取值为 1.0，其余异常值按 1.0 处理。

• 卡片能力：从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
• 原子化服务 API：从 API version 11 开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

strokeLineJoin

strokeLineJoin(value: LineJoinStyle): 设置边框拐角绘制样式。默认值：LineJoinStyle.Miter。

• 卡片能力：从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
• 原子化服务 API：从 API version 11 开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

strokeLineCap

strokeLineCap(value: LineCapStyle): 设置边框端点绘制样式。默认值：LineCapStyle.Butt。

• 卡片能力：从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
• 原子化服务 API：从 API version 11 开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

strokeMiterLimit

strokeMiterLimit(value: number | string): 设置斜接长度与边框宽度比值的极限值。默认值：4。

• 卡片能力：从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
• 原子化服务 API：从 API version 11 开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

strokeWidth

strokeWidth(value: number | string): 设置边框宽度。默认值：1。

• 卡片能力：从 API version 9 开始，该接口支持在 ArkTS 卡片中使用。
• 原子化服务 API：从 API version 11 开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

Path 组件的使用方法

基本用法

以下是一个简单的示例，展示如何使用 Path 组件绘制一个三角形：

@Entry
@Component
struct TriangleExample {
  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Path()
        .width(100)
        .height(100)
        .commands('M50 0 L100 100 L0 100 Z')
        .fill('#E87361')
        .strokeWidth(0)
    }.width('100%').height('100%')
  }
} 

在这个示例中，我们创建了一个 Path 组件，并设置了其宽度、高度和命令字符串。命令字符串 'M50 0 L100 100 L0 100 Z' 定义了一个三角形的路径，起点为 (50, 0)，经过 (100, 100) 和 (0, 100)，最后闭合路径回到起点。

 

复杂路径示例

以下示例展示了如何使用更复杂的路径命令绘制一个五角星：

@Entry
@Component
struct StarExample {
  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Path()
        .width(200)
        .height(200)
        .commands('M100 0 L120 70 L200 70 L150 120 L160 200 L100 150 L40 200 L50 120 L0 70 L80 70 Z')
        .fill('#FFD700')
        .strokeWidth(2)
        .stroke('#000000')
    }.width('100%').height('100%')
  }
} 

在这个示例中，命令字符串 'M100 0 L120 70 L200 70 L150 120 L160 200 L100 150 L40 200 L50 120 L0 70 L80 70 Z' 定义了一个五角星的路径。通过调整控制点和端点的坐标，可以绘制出各种复杂的形状。

 

 

使用 Arc 命令绘制弧形

Arc 命令用于绘制椭圆弧。以下示例展示了如何使用 Arc 命令绘制一个半圆：

@Entry
@Component
struct SemiCircleExample {
  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Path()
        .width(200)
        .height(100)
        .commands('M100 0 A100 50 0 1 1 300 50 A100 50 0 1 1 100 0')
        .fill('#ADD8E6')
        .strokeWidth(2)
        .stroke('#000000')
    }.width('100%').height('100%')
  }
} 

在这个示例中，命令字符串 'M100 0 A100 50 0 1 1 300 50 A100 50 0 1 1 100 0' 定义了一个半圆的路径。A 命令的参数依次为：rx（椭圆的水平半径）、ry（椭圆的垂直半径）、x-axis-rotation（椭圆的旋转角度）、large-arc-flag（是否绘制大弧）、sweep-flag（绘制方向）和终点坐标。

 

 

总结

Path 组件是 ArkUI 框架中一个强大的绘图工具，支持通过 SVG 路径描述规范绘制各种复杂的自定义形状。通过设置不同的属性，如宽度、高度、填充颜色、边框颜色等，开发者可以实现丰富的图形效果。结合动画效果和其他组件的使用，Path 组件可以进一步提升应用的视觉表现力和用户体验。

本文详细介绍了 Path 组件的基本用法、属性设置、动画效果及其与其他组件的结合使用。希望通过这些内容，开发者能够更好地理解和应用 Path 组件，实现更加丰富和多样化的图形绘制需求。

----

以上