OpenHarmony图形图像如何支持自定义绘制

OpenHarmony 自定义绘制的实现路径

• 使用 ArkUI Canvas 组件 获取绘图上下文，在 onReady 回调后进行绘制。常用上下文为 CanvasRenderingContext2D（2D 绘制），也可通过 getContext(‘webgl’) 使用 WebGL（当前能力在完善中）。坐标系以画布左上角为原点，向右为 x、向下为 y。为提升复杂场景性能，可使用 OffscreenCanvas 进行离屏渲染，再一次性绘制到主画布。Canvas 组件自 API Version 8 起支持，事件 onReady 自 API Version 9 起在 ArkTS 卡片中可用。

快速上手示例 ArkTS 声明式

• 在组件内创建 RenderingContextSettings 与 CanvasRenderingContext2D，在 Canvas 的 onReady 回调中执行绘制命令（如矩形、文本、图片等）。示例：

@Entry
@Component
struct CanvasExample {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private ctx: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.ctx)
        .width('100%')
        .height('100%')
        .backgroundColor('#F5DC62')
        .onReady(() => {
          // 绘制填充矩形
          this.ctx.fillStyle = '#000'
          this.ctx.fillRect(50, 50, 200, 150)

          // 绘制描边矩形
          this.ctx.strokeStyle = '#f00'
          this.ctx.lineWidth = 4
          this.ctx.strokeRect(50, 50, 200, 150)
        })
    }
    .width('100%')
    .height('100%')
  }
}

• 要点：所有绘制 API 必须在 onReady 之后调用；通过 RenderingContextSettings(true) 可开启抗锯齿。

离屏绘制与性能优化

• 适用场景：复杂路径、频繁重绘、需要缓存合成结果的图层。思路是先在离屏画布绘制，再一次性拷贝到主画布显示。
• 关键步骤与 API：
  1. 创建离屏画布：new OffscreenCanvas(width, height)
  2. 获取离屏上下文并在其上绘制
  3. 主画布通过 transferFromImageBitmap(offCanvas.transferToImageBitmap()) 显示离屏内容
• 示例：

@Entry
@Component
struct OffscreenExample {
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private ctx: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private offCanvas: OffscreenCanvas = new OffscreenCanvas(600, 600)

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Canvas(this.ctx)
        .width('100%')
        .height('100%')
        .backgroundColor('#F5DC62')
        .onReady(() => {
          const offCtx = this.offCanvas.getContext('2d', this.settings)
          offCtx.fillStyle = '#00f'
          offCtx.fillRect(50, 50, 200, 150)

          const imageBitmap = this.offCanvas.transferToImageBitmap()
          this.ctx.transferFromImageBitmap(imageBitmap)
        })
    }
    .width('100%')
    .height('100%')
  }
}

• 说明：离屏渲染能显著减少主线程反复清屏与重绘的开销，适合做图层合成、复杂路径缓存等。

进阶绘制能力

• 路径与复杂图形：使用 Path2D 描述路径，通过 addPath 合并路径，再用 stroke/fill 绘制；适合复用路径与组合复杂形状。
• 渐变与样式：通过 CanvasGradient.createLinearGradient / createRadialGradient 创建渐变，使用 addColorStop 设置色标，赋值给 fillStyle/strokeStyle 实现渐变填充或描边。
• 图片绘制：使用 drawImage 系列 API 将图片绘制到画布；自 API 12 起提供更灵活的 drawImageRect / drawImageRectWithSrc，可指定源矩形与目标矩形及采样选项，便于实现缩放、裁剪与九宫格等效果。
• 高阶 2D 图形库：使用 @kit.ArkGraphics2D 提供的 drawing.Pen / drawing.Brush / drawing.Path / drawing.RoundRect 等类进行更细粒度的画笔、画刷、路径与圆角矩形绘制，适合需要更强图形控制与复杂矢量绘制的场景。

实践建议

• 在 onReady 回调内完成所有绘制与状态设置，避免在布局未完成时访问画布尺寸或上下文。
• 合理选择抗锯齿（如 RenderingContextSettings(true)）、合成与变换（如 scale/shadow），并在复杂场景优先采用 OffscreenCanvas 做缓存与分层。
• 图片解码与绘制尽量复用 PixelMap / ImageBitmap，并在高分辨率设备上注意坐标与尺寸的比例缩放，避免模糊或锯齿。