1. Shape 组件概述

Shape 组件是 ArkUI 提供的 绘制容器，它用于管理和绘制所有形状组件，如 矩形、椭圆、路径、折线等。在 Shape 组件内，其他图形（如 Rect、Ellipse、Path）会根据定义的坐标、样式、颜色等信息被渲染出来。

Shape 的作用：

• 作为父容器，包含其他图形组件；
• 支持自定义视口，可以限制绘制区域；
• 支持各种通用属性，如填充颜色、边框、透明度等；
• 可动态调整各种属性，例如：填充颜色、透明度、边框样式、抗锯齿等。

支持的图形包括：Rect、Ellipse、Circle、Polyline、Polygon、Path 等。

组件支持版本

• 从 API version 7 开始支持；
• 从 API version 9 开始支持在 ArkTS 卡片中使用；
• 从 API version 11 开始支持元服务 API。

---

2. Shape 组件的基本用法

2.1 创建一个简单的 Shape 组件

Shape 本身并不直接绘制图形，它需要包含其他图形组件。以下示例创建一个包含矩形和椭圆的 Shape。

// xxx.ets
@Entry
@Component
struct ShapeExample {
  build() {
    Column({ space: 10 }) {
      // 创建一个 Shape 容器，包含矩形和椭圆
      Shape() {
        Rect().width(300).height(50)  // 绘制矩形
        Ellipse().width(300).height(50).offset({ x: 0, y: 60 })  // 绘制椭圆
      }
      .width(350)
      .height(140)
      .viewPort({ x: 0, y: 0, width: 320, height: 130 })
      .fill(0x317AF7)  // 填充颜色
      .stroke(Color.Black)  // 边框颜色
      .strokeWidth(4)  // 边框宽度
      .strokeDashArray([20])  // 边框虚线
      .strokeDashOffset(10)  // 边框虚线偏移
      .strokeLineCap(LineCapStyle.Round)  // 边框两端圆角
      .strokeLineJoin(LineJoinStyle.Round)  // 边框拐角圆角
      .antiAlias(true)  // 开启抗锯齿
    }
  }
}

2.2 Shape 的常用属性

2.2.1 viewPort

viewPort 用来定义图形的显示区域。它可以用来控制整个绘图区域的坐标、宽度和高度。

viewPort({ x: 0, y: 0, width: 320, height: 130 })

• x：视口的水平偏移量；
• y：视口的垂直偏移量；
• width：视口的宽度；
• height：视口的高度。

2.2.2 fill & fillOpacity

用于设置形状的填充颜色和透明度。

fill(0x317AF7)  // 填充颜色
fillOpacity(0.5)  // 填充透明度，范围 [0.0, 1.0]

• fill：填充颜色；
• fillOpacity：填充透明度，默认值为 1.0。

2.2.3 stroke & strokeWidth

用于设置形状的边框颜色和宽度。

stroke(Color.Black)  // 边框颜色
strokeWidth(4)  // 边框宽度

• stroke：边框颜色；
• strokeWidth：边框宽度，默认值为 1。

2.2.4 strokeDashArray & strokeDashOffset

用于设置虚线的样式。

strokeDashArray([20])  // 边框虚线样式
strokeDashOffset(10)  // 虚线的偏移量

• strokeDashArray：定义虚线的线段长度和间隙长度；
• strokeDashOffset：设置虚线的起点偏移量。

2.2.5 strokeLineCap & strokeLineJoin

用于设置边框端点和连接处的样式。

strokeLineCap(LineCapStyle.Round)  // 边框两端样式
strokeLineJoin(LineJoinStyle.Round)  // 边框连接处样式

• strokeLineCap：设置线条端点样式（例如 Round 圆形端点）；
• strokeLineJoin：设置线条连接处的样式（例如 Round 圆角连接）。

---

3. 使用 Shape 绘制复杂图形

3.1 绘制矩形、椭圆和路径

通过将 Shape 作为容器，可以绘制矩形、椭圆、路径等不同图形：

@Entry
@Component
struct ShapeComplexExample {
  build() {
    Column({ space: 10 }) {
      // 绘制矩形、椭圆和路径
      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)  // 开启抗锯齿
    }
  }
}

3.2 使用不同参数类型绘制图形

你可以使用不同的数据类型（如数字、字符串、资源）来定义图形的属性。

@Entry
@Component
struct ShapeTypeExample {
  build() {
    Column({ space: 10 }) {
      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: "200",
        height: "200"
      })
      .fill(Color.Orange)
      .stroke(Color.Black)
      .strokeWidth(4)
      .strokeDashArray([20])
      .strokeDashOffset(10) // 使用数字类型
      .strokeLineCap(LineCapStyle.Round)
      .strokeLineJoin(LineJoinStyle.Round)
      .strokeMiterLimit(5)
      .antiAlias(true)
    }.width('100%').margin({ top: 15 })
  }
}

3.3 使用 attributeModifier 动态设置属性

attributeModifier 允许你动态更新图形的属性，使其更加灵活。

class MyShapeModifier implements AttributeModifier<ShapeAttribute> {
  applyNormalAttribute(instance: ShapeAttribute): void {
    instance.fill("#707070")
    instance.fillOpacity(0.5)
    instance.stroke("#2787D9")
    instance.strokeDashArray([20, 15])
    instance.strokeDashOffset("15")
    instance.strokeLineCap(LineCapStyle.Round)
    instance.strokeLineJoin(LineJoinStyle.Miter)
    instance.strokeMiterLimit(5)
    instance.strokeOpacity(0.5)
    instance.strokeWidth(10)
    instance.antiAlias(true)
  }
}

@Entry
@Component
struct ShapeModifierDemo {
  @State modifier: MyShapeModifier = new MyShapeModifier()

  build() {
    Column() {
      Shape() {
        Rect().width(200).height(50).offset({ x: 20, y: 20 })
        Ellipse().width(200).height(50).offset({ x: 20, y: 80 })
        Path().width(200).height(10).commands('M0 0 L900 0').offset({ x: 20, y: 160 })
      }
      .width(250).height(200)
      .attributeModifier(this.modifier)
    }
  }
}

---

4. 高级特性：图形扭曲

Shape 组件还支持 mesh 属性，它可以对图像进行 局部扭曲，实现类似于 CSS 的“网格扭曲”效果。

@Entry
@Component
struct MeshExample {
  private meshArray: Array<number> = [0, 0, 50, 0, 410, 0, 0, 180, 50, 180, 410, 180, 0, 360, 50, 360, 410, 360]

  build() {
    Column() {
      Shape()
        .mesh(this.meshArray, 2, 2)
        .width(250)
        .height(250)
        .backgroundColor(Color.Gray)
    }
  }
}