2D 绘图的"积木块"：Point、Rect、Color 这些基础类型

如果你要做任何 2D 绘制相关的功能——画图表、画图标、做自定义 UI 组件——你一定会用到一些最基础的数据类型：坐标点、矩形区域、颜色值。

HarmonyOS 把这些基础类型统一放在了 @ohos.graphics.common2D 这个模块里。它们就像乐高积木一样，单独看很简单，但组合起来能搭出各种复杂的东西。

今天我们就来认识一下这些"积木块"，看看它们在实际开发中怎么用。

导入模块

import { common2D } from '@kit.ArkGraphics2D';

所有 2D 绘图相关的基础类型都从这里导入。

common2D 基础类型总览

下面是 common2D 模块提供的基础类型及其用途：

Color：ARGB 颜色描述

Color 是最常用的类型之一，用来描述一个颜色。它用的是 ARGB 格式，也就是透明度（Alpha）、红色（Red）、绿色（Green）、蓝色（Blue）四个分量。

interface Color {
  alpha: number;  // 透明度，0~255 的整数
  red: number;    // 红色分量，0~255 的整数
  green: number;  // 绿色分量，0~255 的整数
  blue: number;   // 蓝色分量，0~255 的整数
}

每个分量都是 0~255 的整数。比如：

• 纯红色：{ alpha: 255, red: 255, green: 0, blue: 0 }
• 半透明蓝色：{ alpha: 128, red: 0, green: 0, blue: 255 }
• 完全透明：{ alpha: 0, red: 0, green: 0, blue: 0 }

在实际使用中，你经常会把 Color 传给画笔（Brush）或者画布（Canvas）来设置绘制颜色。比如你要在一个矩形区域画一个半透明的红色遮罩：

let maskColor: common2D.Color = {
  alpha: 100,
  red: 255,
  green: 0,
  blue: 0
};

然后把这个颜色设置给 Brush，再用 Canvas 画出来就行了。

Color4f：浮点数版本的颜色

从 API version 20 开始，还多了一个 Color4f 类型：

interface Color4f {
  alpha: number;  // 透明度，0.0~1.0 的浮点数
  red: number;    // 红色分量，0.0~1.0 的浮点数
  green: number;  // 绿色分量，0.0~1.0 的浮点数
  blue: number;   // 蓝色分量，0.0~1.0 的浮点数
}

跟 Color 的区别是，Color4f 用的是 0.0~1.0 的浮点数，而不是 0~255 的整数。

你可能会问：为什么要有两种颜色表示方式？简单说，整数版本更直观、更常用，适合 UI 开发；浮点数版本精度更高，适合图像处理和颜色计算。比如做颜色混合、渐变插值时，浮点数计算更方便。

举个例子，纯红色用 Color 表示是 { alpha: 255, red: 255, green: 0, blue: 0 }，用 Color4f 表示就是 { alpha: 1.0, red: 1.0, green: 0.0, blue: 0.0 }。半透明的话，Color 用 alpha: 128，Color4f 用 alpha: 0.5。

Rect：矩形区域

Rect 用来描述一个矩形区域，通过左上角和右下角两个点来定义：

interface Rect {
  left: number;   // 左上角横坐标，浮点数
  top: number;    // 左上角纵坐标，浮点数
  right: number;  // 右下角横坐标，浮点数
  bottom: number; // 右下角纵坐标，浮点数
}

注意这里用的是屏幕物理像素单位 px，不是 dp。在做自定义绘制时，坐标系的原点 (0, 0) 在左上角，x 轴向右增大，y 轴向下增大。

Rect 在实际开发中的使用场景非常多：

• 裁剪区域：告诉 Canvas 只在某个矩形区域内绘制
• 绘制矩形：画一个矩形、圆角矩形
• 碰撞检测：判断一个点是否在某个区域内
• 图片绘制区域：指定图片的绘制位置和大小

比如你要在画布上画一个 200x100 的矩形，左上角在 (50, 50)：

let rect: common2D.Rect = {
  left: 50,
  top: 50,
  right: 250,  // 50 + 200
  bottom: 150  // 50 + 100
};

这里有个小细节：right 和 bottom 是矩形区域外边界的坐标，不是矩形的宽高。所以 right = left + 宽度，bottom = top + 高度。这个跟某些 UI 框架的 Rect 定义不一样，别搞混了。

Point：二维坐标点

Point 表示一个二维平面上的坐标点：

interface Point {
  x: number;  // 横坐标，浮点数
  y: number;  // 纵坐标，浮点数
}

很简单，就是 x 和 y 两个浮点数。用在很多地方：路径绘制的起点、触摸事件的坐标、图形变换的锚点等。

比如你要从 (100, 200) 画一条线到 (300, 400)：

let startPoint: common2D.Point = { x: 100, y: 200 };
let endPoint: common2D.Point = { x: 300, y: 400 };

然后把这两个点传给 Path 的 moveTo 和 lineTo 方法就行了。

Point3d：三维坐标点

Point3d 继承自 Point，多了一个 z 轴坐标：

interface Point3d extends Point {
  z: number;  // z 轴坐标，浮点数
}

这个在 3D 场景里用得比较多，比如空间坐标、3D 变换等。在纯 2D 绘制中一般用不到。

基础类型组合应用示例

下面是使用这些基础类型绘制自定义进度条的流程：

实际场景：画一个自定义进度条

让我们把这些类型组合起来，看看在实际开发中怎么用。假设你要画一个带背景的进度条：

import { common2D } from '@kit.ArkGraphics2D';

// 进度条的背景区域
let bgRect: common2D.Rect = {
  left: 50,
  top: 300,
  right: 750,
  bottom: 340
};

// 进度条的填充区域（假设进度 60%）
let progress: number = 0.6;
let fillRect: common2D.Rect = {
  left: 50,
  top: 300,
  right: 50 + (750 - 50) * progress,  // 50 + 700 * 0.6 = 470
  bottom: 340
};

// 背景颜色：灰色
let bgColor: common2D.Color = {
  alpha: 255,
  red: 200,
  green: 200,
  blue: 200
};

// 填充颜色：蓝色
let fillColor: common2D.Color = {
  alpha: 255,
  red: 66,
  green: 135,
  blue: 245
};

你看，就是用 Rect 定义两个矩形区域，用 Color 定义两种颜色，然后交给 Canvas 去绘制。这些基础类型虽然简单，但它们是所有 2D 绘制操作的基础。

使用注意事项

1. 单位是物理像素 px：common2D 里的所有坐标和尺寸都是 px 单位，不是 dp。如果你要适配不同屏幕密度，需要自己做转换。

2. Color 的值范围是 0~255：不是 0~1。如果你习惯 CSS 的 rgba(255, 0, 0, 1.0) 写法，记得转换一下 alpha 值。

3. Rect 的 right/bottom 是边界坐标：不是宽高。right - left 才是宽度，bottom - top 才是高度。

4. Color4f 是 API 20 才有的：如果你的 APP 需要支持较老的系统版本，就用 Color。

小结

common2D 模块提供了 2D 绘图最基础的数据类型：Color（颜色）、Color4f（浮点颜色）、Rect（矩形区域）、Point（坐标点）、Point3d（三维坐标点）。它们本身很简单，但在实际开发中会被大量使用。

把这些类型搞清楚，后面学 Canvas、Path、Brush、Pen 这些绘制 API 时就会顺畅很多，因为它们的方法参数基本都是这些类型。