HarmonyOS Canvas 绘图实战：从静态圆到动态交互

当你在 Canvas 中使用 (ctx: CanvasRenderingContext2D) => { ... } 回调时，ctx 就是一个 CanvasRenderingContext2D 实例。

Canvas((ctx: CanvasRenderingContext2D) => {
  // 所有绘图操作都在这里执行
})

🔍 核心作用：控制画笔颜色、粗细；定义路径（path）；填充或描边；应用变换（transform）

2. 主要属性与方法

这些方法在 OpenHarmony 6.0 中已全面支持，且性能优化良好。

三、绘制一个圆：基础步骤详解

我们从最简单的任务开始：画一个红色实心圆，外加白色描边。

1. 创建 Canvas 组件

Canvas((ctx: CanvasRenderingContext2D) => {
  // 绘图逻辑
})

代码讲解：Canvas 是一个函数式组件，接收一个回调函数；回调参数 ctx 是 CanvasRenderingContext2D 实例；所有绘图操作都通过 ctx 调用。

2. 开始路径

ctx.beginPath();

代码讲解：beginPath() 表示'我要开始画一条新路径了'；每次绘制新图形前，必须调用此方法；否则会继续上一条路径，导致图形粘连。

3. 绘制圆弧

ctx.arc(100, 100, 50, 0, 2 * Math.PI);

参数说明：

• (100, 100)：圆心位于屏幕左上角 100px 处
• 50：半径为 50px
• 0 到 2 * Math.PI：表示绘制一个完整的圆（360°）
• Math.PI 是 π ≈ 3.14159，2 * Math.PI = 6.28318 ≈ 360°

4. 设置填充颜色

ctx.fillStyle = 'red';

代码讲解：fillStyle 设置路径的填充颜色；支持颜色字符串（如 'red', '#FF0000', 'rgb(255,0,0)'）；不设置时默认为黑色。

5. 填充路径

ctx.fill();

代码讲解：fill() 将当前路径内部区域用 fillStyle 指定的颜色填充；此时圆变为红色实心圆。

6. 设置描边样式

ctx.strokeStyle = 'white';
ctx.lineWidth = 2;

代码讲解：strokeStyle 设置描边颜色；lineWidth 设置描边宽度（单位：px）；默认描边宽度为 1px。

7. 描边路径

ctx.stroke();

代码讲解：stroke() 用 strokeStyle 和 lineWidth 绘制路径轮廓；此时圆外围出现白色边框。

✅ 完整代码示例

Canvas((ctx: CanvasRenderingContext2D) => {
  ctx.beginPath();
  ctx.arc(100, 100, 50, 0, 2 * Math.PI);
  ctx.fillStyle = 'red';
  ctx.fill();
  ctx.strokeStyle = 'white';
  ctx.lineWidth = 2;
  ctx.stroke();
});

💡 效果：一个位于 (100,100)、半径 50px 的红色实心圆，带有 2px 白色描边。

四、动态绘制圆环：响应式更新

静态图形虽然简单，但无法满足交互需求。我们可以通过 @State 或 @Prop 实现动态更新。

1. 使用 @State 控制圆心位置

@State x: number = 100;
@State y: number = 100;

代码讲解：@State 是 ArkTS 的响应式装饰器；当 x 或 y 变化时，UI 会自动重绘；适用于实时动画、用户交互等场景。

2. 在 Canvas 中使用动态值

Canvas((ctx: CanvasRenderingContext2D) => {
  ctx.beginPath();
  ctx.arc(this.x, this.y, 50, 0, 2 * Math.PI);
  ctx.fillStyle = 'blue';
  ctx.fill();
  ctx.strokeStyle = 'yellow';
  ctx.lineWidth = 3;
  ctx.stroke();
});

代码讲解：使用 this.x 和 this.y 替代固定值；当 x 或 y 更新时，Canvas 会重新执行回调；实现'圆随手指移动'的效果。

3. 添加触摸事件

.onTouch((event: TouchEvent) => {
  if (event.type === TouchType.Move) {
    this.x = event.touches[0].clientX;
    this.y = event.touches[0].clientY;
  }
})

代码讲解：onTouch 监听触摸事件；TouchType.Move 表示拖动；clientX/Y 是触摸点相对于视图的坐标；更新 x 和 y 触发重绘。

✅ 完整动态圆环代码

@Entry
@Component
struct CirclePage {
  @State circleX: number = 150;
  @State circleY: number = 300;

  build() {
    // 根容器：Column
    Column() {
      // 用一个 Stack 来承载圆，确保它能被正确渲染
      Stack() {
        // 直接用 Circle 组件，比 Shape 更稳定
        Circle({ width: 100, height: 100 })
          .fill(Color.Blue)
          .stroke(Color.Yellow)
          .strokeWidth(3)
          .position({ x: this.circleX, y: this.circleY })
      }
      .width('100%')
      .height('100%')
    }
    .width('100%')
    .height('100%')
    .backgroundColor(Color.White)
    .onTouch((event: TouchEvent) => {
      if (event.type === TouchType.Down || event.type === TouchType.Move) {
        // 减去圆半径，让触摸点在圆中心
        this.circleX = event.touches[0].windowX - 50;
        this.circleY = event.touches[0].windowY - 50;
      }
    })
  }
}

✅ 效果：点击并拖动屏幕，蓝色圆随手指移动。

五、进阶技巧：渐变填充与多层绘制

1. 创建线性渐变

const gradient = ctx.createLinearGradient(100, 100, 200, 200);
gradient.addColorStop(0, 'red');
gradient.addColorStop(1, 'blue');
ctx.fillStyle = gradient;

代码讲解：createLinearGradient(x1,y1,x2,y2)：定义渐变方向；addColorStop(0, 'red')：起始点为红色；addColorStop(1, 'blue')：结束点为蓝色；fillStyle = gradient：应用渐变。

2. 多层绘制：背景 + 圆

// 绘制背景矩形
ctx.fillStyle = '#f0f0f0';
ctx.fillRect(0, 0, 300, 300);

// 绘制圆
ctx.beginPath();
ctx.arc(150, 150, 50, 0, 2 * Math.PI);
ctx.fillStyle = 'red';
ctx.fill();
ctx.strokeStyle = 'black';
ctx.lineWidth = 2;
ctx.stroke();

代码讲解：fillRect(x,y,width,height)：绘制矩形；先画背景，再画圆，避免覆盖；fillRect 不需要 beginPath()，因为它不是路径。

六、性能优化建议

七、完整可运行代码（适配 API 6.0.2）

@Entry
@Component
struct CanvasDemo {
  @State x: number = 150;
  @State y: number = 300;

  build() {
    Column() {
      Stack() {
        // 灰色背景
        Row()
          .width('100%')
          .height('100%')
          .backgroundColor('#f0f0f0')
        
        // 红色圆 + 文字
        Column() {
          Text('Drag me!')
            .fontSize(16)
            .fontWeight(FontWeight.Bold)
            .fontColor(Color.Black)
          
          Circle({ width: 100, height: 100 })
            .fill(Color.Red)
            .stroke(Color.Yellow)
            // 把描边改成黄色
            .strokeWidth(3)
        }.position({ x: this.x - 50, y: this.y - 50 })
      }
      .width('100%')
      .height('100%')
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#FFFFFF')
    .onTouch((event: TouchEvent) => {
      if (event.type === TouchType.Move) {
        this.x = event.touches[0].windowX;
        this.y = event.touches[0].windowY;
      }
    })
  }
}

八、总结

本文详细介绍了 HarmonyOS 6.0.0（API 6.0.2）中 Canvas 的基础绘图 API，包括：

• Canvas 组件的使用方式；
• CanvasRenderingContext2D 的核心方法；
• 如何绘制一个圆（arc, fill, stroke）；
• 动态更新与触摸交互；
• 渐变填充与多层绘制；
• 性能优化建议。