#跟着若城学鸿蒙# UI组件篇-Polygon 及其属性

 

前言

在现代应用开发中，图形绘制是一个不可或缺的功能。无论是数据可视化、游戏开发还是用户界面的美化，图形绘制都扮演着至关重要的角色。ArkUI 作为华为推出的 UI 框架，提供了丰富的图形绘制组件，其中 Polygon 组件因其强大的功能和灵活性，成为开发者绘制多边形的首选工具。本文将详细介绍 ArkUI 中的 Polygon 组件，包括其基本概念、属性、使用方法以及实际应用场景。

Polygon 组件的基本概念

Polygon 组件是 ArkUI 中用于绘制多边形的 UI 组件。多边形是由多个顶点连接而成的闭合图形，常见的有多边形、五边形、六边形等。Polygon 组件不仅支持绘制基本的多边形，还提供了丰富的属性设置，使得开发者可以灵活地调整多边形的样式和行为。

支持的 API 版本

Polygon 组件从 API Version 7 开始支持，并在后续版本中不断扩展其功能。从 API Version 9 开始，该组件支持在 ArkTS 卡片中使用，并从 API Version 11 开始支持在原子化服务中使用。

Polygon 组件的子组件

Polygon 组件本身不包含任何子组件，但它可以与其他 ArkUI 组件结合使用，以实现更复杂的 UI 效果。例如，可以将 Polygon 组件与 Text 组件结合，用于在多边形内部显示文本信息。

Polygon 组件的接口

Polygon 组件的接口定义如下：

Polygon(value?: { width?: string | number, height?: string | number }) 

参数说明

• value: 一个可选的对象，用于设置多边形的宽度和高度。
  • width: 多边形的宽度，可以是字符串或数字类型。默认值为 0，单位为 vp。异常值按照默认值处理。
  • height: 多边形的高度，可以是字符串或数字类型。默认值为 0，单位为 vp。异常值按照默认值处理。

Polygon 组件的属性

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

points

points 属性用于设置多边形的顶点坐标列表。该属性是绘制多边形的关键，必须提供有效的顶点坐标才能正确绘制多边形。

• 参数说明：

  • value: 一个 Array<Point> 类型的数组，表示多边形的顶点坐标列表。默认值为 []，单位为 vp。异常值按照默认值处理。

• 示例代码：

  @Entry
  @Component
  struct PolygonExample {
    build() {
      Column({ space: 10 }) {
        // 在 100 * 100 的矩形框中绘制一个三角形，起点(0, 0)，经过(50, 100)，终点(100, 0)
        Polygon({ width: 100, height: 100 }).points([[0, 0], [50, 100], [100, 0]]).fill(Color.Green)
        // 在 100 * 100 的矩形框中绘制一个四边形，起点(0, 0)，经过(0, 100)和(100, 100)，终点(100, 0)
        Polygon()
          .width(100)
          .height(100)
          .points([[0, 0], [0, 100], [100, 100], [100, 0]])
          .fillOpacity(0)
          .strokeWidth(5)
          .stroke(Color.Blue)
        // 在 100 * 100 的矩形框中绘制一个五边形，起点(50, 0)，依次经过(0, 50)、(20, 100)和(80, 100)，终点(100, 50)
        Polygon()
          .width(100)
          .height(100)
          .points([[50, 0], [0, 50], [20, 100], [80, 100], [100, 50]])
          .fill(Color.Red)
          .fillOpacity(0.6)
      }.width('100%').margin({ top: 10 })
    }
  }

fill

fill 属性用于设置填充区域的颜色。该属性与通用的 foregroundColor 属性同时设置时，后设置的属性生效。

• 参数说明：

  • value: 一个 ResourceColor 类型的颜色值。默认值为 Color.Black。

• 示例代码：

  Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .fill(Color.Green) 

fillOpacity

fillOpacity 属性用于设置填充区域的透明度。取值范围是 [0.0, 1.0]，若给定值小于 0.0，则取值为 0.0；若给定值大于 1.0，则取值为 1.0，其余异常值按 1.0 处理。

• 参数说明：

  • value: 一个 number、string 或 Resource 类型的透明度值。默认值为 1。

• 示例代码：

  @Entry
  @Component
  struct PolygonExample {
    build() {
      Column({ space: 10 }) {
        Polygon() .width(100) .height(100) .points([[0, 0], [0, 100], [100, 100], [100, 0]]) .fillOpacity(0.5)
      }.width('100%').margin({ top: 10 })
    }
  }

stroke

stroke 属性用于设置边框颜色。不设置时，默认没有边框。异常值不会绘制边框。

• 参数说明：

  • value: 一个 ResourceColor 类型的颜色值。

• 示例代码：

  @Entry
  @Component
  struct PolygonExample {
    build() {
      Column({ space: 10 }) {
        Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .stroke(Color.Blue)
      }.width('100%').margin({ top: 10 })
    }
  }

strokeDashArray

strokeDashArray 属性用于设置边框间隙。取值范围 ≥0，异常值按照默认值处理。

• 参数说明：

  • value: 一个 Array<any> 类型的数组，表示边框间隙。默认值为 []，单位为 vp。

• 示例代码：

  @Entry
  @Component
  struct PolygonExample {
    build() {
      Column({ space: 10 }) {
        Polygon() .width(100) .height(100) .points([[0, 0], [0, 100], [100, 100], [100, 0]]) .strokeDashArray([10, 5])
      }.width('100%').margin({ top: 10 })
    }
  }

strokeDashOffset

strokeDashOffset 属性用于设置边框绘制起点的偏移量。异常值按照默认值处理。

• 参数说明：

  • value: 一个 number 或 string 类型的偏移量值。默认值为 0，单位为 vp。

• 示例代码：

  Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .strokeDashOffset(3) 

strokeLineCap

strokeLineCap 属性用于设置边框端点绘制样式。

• 参数说明：

  • value: 一个 LineCapStyle 类型的样式值。默认值为 LineCapStyle.Butt。

• 示例代码：

  Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .strokeLineCap(LineCapStyle.Round) 

strokeLineJoin

strokeLineJoin 属性用于设置边框拐角绘制样式。

• 参数说明：

  • value: 一个 LineJoinStyle 类型的样式值。默认值为 LineJoinStyle.Miter。

• 示例代码：

  Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .strokeLineJoin(LineJoinStyle.Round) 

strokeMiterLimit

strokeMiterLimit 属性用于设置斜接长度与边框宽度比值的极限值。斜接长度表示外边框外边交点到内边交点的距离，边框宽度即 strokeWidth 属性的值。该属性取值需在 strokeLineJoin 属性取值 LineJoinStyle.Miter 时生效。

• 参数说明：

  • value: 一个 number 或 string 类型的极限值。默认值为 4。

• 示例代码：

  Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .strokeMiterLimit(5) 

strokeOpacity

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

• 参数说明：

  • value: 一个 number、string 或 Resource 类型的透明度值。默认值为 1。

• 示例代码：

  Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .strokeOpacity(0.5) 

strokeWidth

strokeWidth 属性用于设置边框宽度。该属性若为 string 类型，暂不支持百分比，百分比按照 1px 处理。

• 参数说明：

  • value: 一个 Length 类型的宽度值。默认值为 1，单位为 vp。异常值按照默认值处理。

• 示例代码：

  Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .strokeWidth(2) 

antiAlias

antiAlias 属性用于设置是否开启抗锯齿效果。

• 参数说明：

  • value: 一个 boolean 类型的布尔值。默认值为 true。

• 示例代码：

  Polygon() .width(100) .height(100) .points([[0, 0], [50, 100], [100, 0]]) .antiAlias(false) 

Point 类型

Point 类型用于表示多边形的顶点坐标。每个 Point 包含两个数值，分别表示 x 轴和 y 轴的坐标。

• 参数说明：

  • Point: [number, number]，第一个参数为 x 轴坐标，第二个参数为 y 轴坐标（相对坐标）。

• 示例代码：

  const point: Point = [50, 100]; 

示例代码

以下是一个完整的示例代码，展示了如何使用 Polygon 组件绘制一个三角形、一个四边形和一个五边形，并设置各自的填充颜色、透明度和边框样式。

@Entry
@Component
struct PolygonExample {
  build() {
    Column({
      space: 10
    }) {
      // 在 100 * 100 的矩形框中绘制一个三角形，起点(0, 0)，经过(50, 100)，终点(100, 0)
      Polygon({ width: 100, height: 100 }).points([[0, 0], [50, 100], [100, 0]]).fill(Color.Green)
      // 在 100 * 100 的矩形框中绘制一个四边形，起点(0, 0)，经过(0, 100)和(100, 100)，终点(100, 0)
      Polygon()
        .width(100)
        .height(100)
        .points([[0, 0], [0, 100], [100, 100], [100, 0]])
        .fillOpacity(0)
        .strokeWidth(5)
        .stroke(Color.Blue)
      // 在 100 * 100 的矩形框中绘制一个五边形，起点(50, 0)，依次经过(0, 50)、(20, 100)和(80, 100)，终点(100, 50)
      Polygon()
        .width(100)
        .height(100)
        .points([[50, 0], [0, 50], [20, 100], [80, 100], [100, 50]])
        .fill(Color.Red)
        .fillOpacity(0.6)
    }.width('100%').margin({ top: 10 })
  }
}

总结

Polygon 组件是 ArkUI 中一个功能强大且灵活的图形绘制组件，支持多种属性设置，使得开发者可以轻松绘制各种复杂的多边形图形。通过合理使用 points、fill、stroke 等属性，开发者可以实现丰富的视觉效果，满足不同场景下的需求。无论是数据可视化、游戏开发还是用户界面的美化，Polygon 组件都能发挥重要作用。希望本文的介绍能够帮助开发者更好地理解和使用 Polygon 组件，提升应用的用户体验和视觉效果。

----

以上