HarmonyOS开发中的PixelMap操作：PixelMap创建、像素读写、批量操作、PixelMap与Canvas、性能优化

核心要点：PixelMap是HarmonyOS图像处理的「原子单位」——所有图像操作最终都要回到像素级别。本文从PixelMap的创建方式讲起，深入像素级读写与批量操作，再结合Canvas实现自定义绘制，最后给出性能优化的实战建议，让你真正掌控每一个像素。

一、背景与动机

你有没有想过，手机屏幕上那张精美的照片，本质上是什么？是一堆数字。每一个像素点，由RGBA四个通道的值组成，存储在内存里，最终被GPU渲染到屏幕上。

PixelMap就是HarmonyOS对这些像素数据的封装。它不仅仅是一个「图片容器」，更是一个可以精确操控每一个像素的「画布」。你可以读取任意位置的像素值、修改颜色、批量处理、与Canvas交互绘制——这些能力，是做滤镜、水印、图像识别等高级功能的基础。

但PixelMap操作也有坑。内存占用大、操作慢、线程模型复杂……不搞清楚这些，分分钟踩雷。今天咱们就把PixelMap从头到尾掰扯清楚。

二、核心原理

2.1 PixelMap的数据模型

PixelMap内部存储的是一个二维像素数组，每个像素由若干通道组成：

2.2 PixelMap创建与生命周期

flowchart TD
    classDef primary fill:#4FC3F7,stroke:#0288D1,color:#000
    classDef warning fill:#FFB74D,stroke:#F57C00,color:#000
    classDef error fill:#EF5350,stroke:#C62828,color:#fff
    classDef info fill:#81C784,stroke:#388E3C,color:#000
    classDef purple fill:#CE93D8,stroke:#7B1FA2,color:#000

    A[创建PixelMap] --> B{数据来源}
    B --> C[ImageSource.createPixelMap]:::primary
    B --> D[image.createPixelMap]:::info
    B --> E[从Canvas获取]:::purple

    C --> C1[从文件/网络解码]:::primary
    D --> D1[从Buffer/颜色创建]:::info
    E --> E1[Canvas渲染结果]:::purple

    C1 --> F[使用PixelMap]
    D1 --> F
    E1 --> F

    F --> G[像素读写操作]
    F --> H[与Canvas交互]
    F --> I[图像变换]

    G --> J[release释放资源]:::error
    H --> J
    I --> J

2.3 像素读写的底层机制

PixelMap的readPixel和writePixel操作，本质上是直接读写内存中的像素缓冲区。但这里有个关键点：PixelMap的数据可能存在于GPU内存中，读写时需要做CPU-GPU之间的数据同步，这就是为什么像素操作有时候会「慢」。

批量操作（readPixels/writePixels）则是一次性读写整块区域，减少了同步次数，效率更高。

三、代码实战

3.1 PixelMap的多种创建方式

import { image } from '@kit.ImageKit';
import { fileIo as fs } from '@kit.CoreFileKit';
import { resourceManager } from '@kit.LocalizationKit';

/**
 * PixelMap创建工具类
 * 封装了从不同数据源创建PixelMap的方法
 */
export class PixelMapCreator {

  /**
   * 方式一：从本地资源文件创建PixelMap
   * 适用于应用内置的图片资源
   */
  static async createFromResource(resourceMgr: resourceManager.ResourceManager, resId: number): Promise<image.PixelMap> {
    // 读取资源文件的ArrayBuffer
    const fileData = await resourceMgr.getMediaContent(resId);
    const imageSource = image.createImageSource(fileData.buffer);

    // 创建PixelMap，指定解码参数
    const pixelMap = await imageSource.createPixelMap({
      editable: true,  // 允许编辑（像素读写需要）
      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
    });

    // 释放ImageSource
    imageSource.release();
    console.info('[PixelMapCreator] 从资源创建PixelMap成功');
    return pixelMap;
  }

  /**
   * 方式二：从沙箱文件创建PixelMap
   * 适用于用户下载或缓存的图片
   */
  static async createFromFile(filePath: string): Promise<image.PixelMap> {
    // 打开文件并读取数据
    const file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
    const stat = fs.statSync(filePath);
    const buffer = new ArrayBuffer(stat.size);
    fs.readSync(file.fd, buffer);
    fs.closeSync(file);

    const imageSource = image.createImageSource(buffer);
    const pixelMap = await imageSource.createPixelMap({
      editable: true,
      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
    });

    imageSource.release();
    console.info('[PixelMapCreator] 从文件创建PixelMap成功');
    return pixelMap;
  }

  /**
   * 方式三：从纯色创建指定尺寸的PixelMap
   * 适用于创建纯色背景、占位图等
   */
  static async createFromColor(width: number, height: number, color: number): Promise<image.PixelMap> {
    // 创建初始化选项
    const options: image.PixelMapInitializationOptions = {
      editable: true,
      pixelFormat: image.PixelMapFormat.RGBA_8888,
      size: { width: width, height: height }
    };

    const pixelMap = await image.createPixelMap(color, options);
    console.info(`[PixelMapCreator] 从颜色创建PixelMap成功: ${width}x${height}`);
    return pixelMap;
  }

  /**
   * 方式四：从ArrayBuffer创建PixelMap
   * 适用于网络下载的二进制数据
   */
  static async createFromBuffer(buffer: ArrayBuffer): Promise<image.PixelMap> {
    const imageSource = image.createImageSource(buffer);
    const pixelMap = await imageSource.createPixelMap({
      editable: true,
      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
    });

    imageSource.release();
    console.info('[PixelMapCreator] 从Buffer创建PixelMap成功');
    return pixelMap;
  }
}

3.2 像素级读写操作

import { image } from '@kit.ImageKit';

/**
 * 像素级操作工具类
 * 封装单像素读写、区域读写、批量操作
 */
export class PixelOperator {

  /**
   * 读取单个像素的RGBA值
   * @param pixelMap 目标PixelMap
   * @param x 横坐标
   * @param y 纵坐标
   * @returns RGBA颜色值（0xRRGGBBAA格式）
   */
  static readSinglePixel(pixelMap: image.PixelMap, x: number, y: number): number {
    const color = new ArrayBuffer(4);
    pixelMap.readPixel({ x: x, y: y }, color);

    // 解析RGBA分量
    const dataView = new DataView(color);
    const r = dataView.getUint8(0);
    const g = dataView.getUint8(1);
    const b = dataView.getUint8(2);
    const a = dataView.getUint8(3);

    console.info(`[PixelOperator] 像素(${x},${y}): R=${r}, G=${g}, B=${b}, A=${a}`);
    return (r << 24) | (g << 16) | (b << 8) | a;
  }

  /**
   * 写入单个像素的RGBA值
   * @param pixelMap 目标PixelMap
   * @param x 横坐标
   * @param y 纵坐标
   * @param r 红色分量 (0-255)
   * @param g 绿色分量 (0-255)
   * @param b 蓝色分量 (0-255)
   * @param a 透明度 (0-255)
   */
  static writeSinglePixel(pixelMap: image.PixelMap, x: number, y: number, r: number, g: number, b: number, a: number): void {
    const color = new ArrayBuffer(4);
    const dataView = new DataView(color);
    dataView.setUint8(0, r);
    dataView.setUint8(1, g);
    dataView.setUint8(2, b);
    dataView.setUint8(3, a);

    pixelMap.writePixel({ x: x, y: y }, color);
  }

  /**
   * 批量读取指定区域的像素数据
   * 性能远优于逐像素读取
   * @param pixelMap 目标PixelMap
   * @param region 读取区域
   * @returns 像素数据ArrayBuffer
   */
  static readRegionPixels(pixelMap: image.PixelMap, region: image.Region): ArrayBuffer {
    const bytesPerPixel = 4; // RGBA_8888格式
    const bufferSize = region.size.width * region.size.height * bytesPerPixel;
    const buffer = new ArrayBuffer(bufferSize);

    pixelMap.readPixels(region, buffer);
    console.info(`[PixelOperator] 批量读取区域像素: (${region.x},${region.y}) ${region.size.width}x${region.size.height}`);
    return buffer;
  }

  /**
   * 批量写入像素数据到指定区域
   * @param pixelMap 目标PixelMap
   * @param region 写入区域
   * @param buffer 像素数据
   */
  static writeRegionPixels(pixelMap: image.PixelMap, region: image.Region, buffer: ArrayBuffer): void {
    pixelMap.writePixels(region, buffer);
    console.info(`[PixelOperator] 批量写入区域像素: (${region.x},${region.y}) ${region.size.width}x${region.size.height}`);
  }

  /**
   * 读取整个PixelMap的像素数据
   * @param pixelMap 目标PixelMap
   * @returns 完整像素数据
   */
  static readAllPixels(pixelMap: image.PixelMap): ArrayBuffer {
    const imageInfo = pixelMap.getImageInfo();
    const bytesPerPixel = 4;
    const bufferSize = imageInfo.size.width * imageInfo.size.height * bytesPerPixel;
    const buffer = new ArrayBuffer(bufferSize);

    pixelMap.readPixelsToBuffer(buffer);
    console.info(`[PixelOperator] 读取全部像素: ${imageInfo.size.width}x${imageInfo.size.height}`);
    return buffer;
  }

  /**
   * 将像素数据写回PixelMap
   * @param pixelMap 目标PixelMap
   * @param buffer 像素数据
   */
  static writeAllPixels(pixelMap: image.PixelMap, buffer: ArrayBuffer): void {
    pixelMap.writeBufferToPixels(buffer);
    console.info('[PixelOperator] 写入全部像素');
  }
}

3.3 实战：图像滤镜处理

用像素操作实现几种常见的图像滤镜——灰度化、反色、亮度调节，这是像素操作最经典的应用场景。

import { image } from '@kit.ImageKit';

/**
 * 图像滤镜处理器
 * 基于像素级操作实现常见滤镜效果
 */
export class ImageFilterProcessor {

  /**
   * 灰度化滤镜
   * 使用加权平均法：Gray = 0.299*R + 0.587*G + 0.114*B
   */
  static async applyGrayscale(pixelMap: image.PixelMap): Promise<void> {
    const imageInfo = pixelMap.getImageInfo();
    const width = imageInfo.size.width;
    const height = imageInfo.size.height;
    const bufferSize = width * height * 4;
    const buffer = new ArrayBuffer(bufferSize);

    // 批量读取所有像素
    pixelMap.readPixelsToBuffer(buffer);
    const dataView = new DataView(buffer);

    // 逐像素处理
    for (let i = 0; i < width * height; i++) {
      const offset = i * 4;
      const r = dataView.getUint8(offset);
      const g = dataView.getUint8(offset + 1);
      const b = dataView.getUint8(offset + 2);
      const a = dataView.getUint8(offset + 3);

      // 加权灰度计算
      const gray = Math.round(0.299 * r + 0.587 * g + 0.114 * b);

      dataView.setUint8(offset, gray);       // R
      dataView.setUint8(offset + 1, gray);   // G
      dataView.setUint8(offset + 2, gray);   // B
      dataView.setUint8(offset + 3, a);      // A不变
    }

    // 批量写回
    pixelMap.writeBufferToPixels(buffer);
    console.info('[FilterProcessor] 灰度化滤镜已应用');
  }

  /**
   * 反色滤镜
   * 将每个通道值取反：newVal = 255 - oldVal
   */
  static async applyInvert(pixelMap: image.PixelMap): Promise<void> {
    const imageInfo = pixelMap.getImageInfo();
    const width = imageInfo.size.width;
    const height = imageInfo.size.height;
    const bufferSize = width * height * 4;
    const buffer = new ArrayBuffer(bufferSize);

    pixelMap.readPixelsToBuffer(buffer);
    const dataView = new DataView(buffer);

    for (let i = 0; i < width * height; i++) {
      const offset = i * 4;
      dataView.setUint8(offset, 255 - dataView.getUint8(offset));       // R取反
      dataView.setUint8(offset + 1, 255 - dataView.getUint8(offset + 1)); // G取反
      dataView.setUint8(offset + 2, 255 - dataView.getUint8(offset + 2)); // B取反
      // A不变
    }

    pixelMap.writeBufferToPixels(buffer);
    console.info('[FilterProcessor] 反色滤镜已应用');
  }

  /**
   * 亮度调节滤镜
   * @param brightness 亮度偏移值 (-255 ~ 255)
   */
  static async applyBrightness(pixelMap: image.PixelMap, brightness: number): Promise<void> {
    const imageInfo = pixelMap.getImageInfo();
    const width = imageInfo.size.width;
    const height = imageInfo.size.height;
    const bufferSize = width * height * 4;
    const buffer = new ArrayBuffer(bufferSize);

    pixelMap.readPixelsToBuffer(buffer);
    const dataView = new DataView(buffer);

    for (let i = 0; i < width * height; i++) {
      const offset = i * 4;
      // 亮度调节：将每个通道加上偏移值，并限制在0-255范围
      const r = Math.max(0, Math.min(255, dataView.getUint8(offset) + brightness));
      const g = Math.max(0, Math.min(255, dataView.getUint8(offset + 1) + brightness));
      const b = Math.max(0, Math.min(255, dataView.getUint8(offset + 2) + brightness));

      dataView.setUint8(offset, r);
      dataView.setUint8(offset + 1, g);
      dataView.setUint8(offset + 2, b);
    }

    pixelMap.writeBufferToPixels(buffer);
    console.info(`[FilterProcessor] 亮度调节已应用: ${brightness}`);
  }

  /**
   * 棕褐色（怀旧）滤镜
   * 经典的复古色调效果
   */
  static async applySepia(pixelMap: image.PixelMap): Promise<void> {
    const imageInfo = pixelMap.getImageInfo();
    const width = imageInfo.size.width;
    const height = imageInfo.size.height;
    const bufferSize = width * height * 4;
    const buffer = new ArrayBuffer(bufferSize);

    pixelMap.readPixelsToBuffer(buffer);
    const dataView = new DataView(buffer);

    for (let i = 0; i < width * height; i++) {
      const offset = i * 4;
      const r = dataView.getUint8(offset);
      const g = dataView.getUint8(offset + 1);
      const b = dataView.getUint8(offset + 2);

      // 棕褐色变换矩阵
      const newR = Math.min(255, Math.round(r * 0.393 + g * 0.769 + b * 0.189));
      const newG = Math.min(255, Math.round(r * 0.349 + g * 0.686 + b * 0.168));
      const newB = Math.min(255, Math.round(r * 0.272 + g * 0.534 + b * 0.131));

      dataView.setUint8(offset, newR);
      dataView.setUint8(offset + 1, newG);
      dataView.setUint8(offset + 2, newB);
    }

    pixelMap.writeBufferToPixels(buffer);
    console.info('[FilterProcessor] 棕褐色滤镜已应用');
  }
}

3.4 PixelMap与Canvas交互

PixelMap可以作为Canvas的绘制目标，也可以从Canvas的渲染结果创建PixelMap。这为自定义绘制和图像后处理提供了强大的能力。

import { image } from '@kit.ImageKit';
import { ComponentUtils } from '@kit.ArkUI';

@Entry
@Component
struct PixelMapCanvasDemo {
  @State pixelMap: image.PixelMap | undefined = undefined;
  @State canvasPixelMap: image.PixelMap | undefined = undefined;
  private settings: RenderingContextSettings = new RenderingContextSettings(true);
  private canvasContext: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings);

  aboutToAppear(): void {
    this.initPixelMap();
  }

  /**
   * 初始化一个带渐变的PixelMap
   */
  async initPixelMap(): Promise<void> {
    // 创建一个400x400的PixelMap
    const options: image.PixelMapInitializationOptions = {
      editable: true,
      pixelFormat: image.PixelMapFormat.RGBA_8888,
      size: { width: 400, height: 400 }
    };
    this.pixelMap = await image.createPixelMap(0xFF4FC3F7, options);

    // 在PixelMap上绘制渐变
    if (this.pixelMap) {
      const info = this.pixelMap.getImageInfo();
      const buffer = new ArrayBuffer(info.size.width * info.size.height * 4);
      const dataView = new DataView(buffer);

      for (let y = 0; y < info.size.height; y++) {
        for (let x = 0; x < info.size.width; x++) {
          const offset = (y * info.size.width + x) * 4;
          // 从蓝色渐变到紫色
          const ratio = x / info.size.width;
          const r = Math.round(79 + (206 - 79) * ratio);
          const g = Math.round(195 + (147 - 195) * ratio);
          const b = Math.round(247 + (216 - 247) * ratio);
          dataView.setUint8(offset, r);
          dataView.setUint8(offset + 1, g);
          dataView.setUint8(offset + 2, b);
          dataView.setUint8(offset + 3, 255);
        }
      }

      this.pixelMap.writeBufferToPixels(buffer);
    }
  }

  /**
   * 在Canvas上绘制内容，然后获取PixelMap
   */
  drawOnCanvas(): void {
    const canvas = this.canvasContext;

    // 绘制背景
    canvas.fillStyle = '#1A1A2E';
    canvas.fillRect(0, 0, 400, 400);

    // 绘制圆形
    canvas.beginPath();
    canvas.arc(200, 200, 100, 0, Math.PI * 2);
    canvas.fillStyle = '#4FC3F7';
    canvas.fill();

    // 绘制文字
    canvas.font = '28px sans-serif';
    canvas.fillStyle = '#FFFFFF';
    canvas.textAlign = 'center';
    canvas.fillText('PixelMap + Canvas', 200, 210);

    // 从Canvas获取PixelMap
    const pixelData = canvas.getPixelMap();
    if (pixelData) {
      this.canvasPixelMap = pixelData;
      console.info('[CanvasDemo] 从Canvas获取PixelMap成功');
    }
  }

  build() {
    Scroll() {
      Column() {
        Text('PixelMap与Canvas交互')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .margin({ bottom: 16 })

        // 显示PixelMap
        Text('PixelMap直接渲染')
          .fontSize(16)
          .fontColor('#AAAAAA')
          .margin({ bottom: 8 })

        if (this.pixelMap) {
          Image(this.pixelMap)
            .width(200)
            .height(200)
            .objectFit(ImageFit.Cover)
            .borderRadius(8)
            .margin({ bottom: 16 })
        }

        // Canvas绘制
        Text('Canvas绘制区域')
          .fontSize(16)
          .fontColor('#AAAAAA')
          .margin({ bottom: 8 })

        Canvas(this.canvasContext)
          .width(200)
          .height(200)
          .backgroundColor('#1A1A2E')
          .borderRadius(8)
          .margin({ bottom: 16 })

        // Canvas转PixelMap后的显示
        if (this.canvasPixelMap) {
          Text('Canvas转PixelMap')
            .fontSize(16)
            .fontColor('#AAAAAA')
            .margin({ bottom: 8 })

          Image(this.canvasPixelMap)
            .width(200)
            .height(200)
            .objectFit(ImageFit.Cover)
            .borderRadius(8)
            .margin({ bottom: 16 })
        }

        // 操作按钮
        Row() {
          Button('Canvas绘制')
            .backgroundColor('#4FC3F7')
            .fontColor('#000000')
            .onClick(() => this.drawOnCanvas())

          Button('灰度化')
            .backgroundColor('#CE93D8')
            .fontColor('#000000')
            .onClick(async () => {
              if (this.pixelMap) {
                await ImageFilterProcessor.applyGrayscale(this.pixelMap);
              }
            })

          Button('反色')
            .backgroundColor('#FFB74D')
            .fontColor('#000000')
            .onClick(async () => {
              if (this.pixelMap) {
                await ImageFilterProcessor.applyInvert(this.pixelMap);
              }
            })
        }
        .width('100%')
        .justifyContent(FlexAlign.SpaceEvenly)
      }
      .width('100%')
      .padding(16)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#0D0D1A')
  }
}

四、踩坑与注意事项

4.1 editable必须设为true

PixelMap默认是不可编辑的（editable: false）。如果你忘了设置editable: true，所有像素写操作都会静默失败——不会报错，但就是写不进去，非常隐蔽。

建议：需要做像素操作的PixelMap，创建时务必指定editable: true。

4.2 批量操作 vs 逐像素操作的性能差距

这是新手最容易犯的性能错误。来看一组数据：

差距是数量级的。原因很简单：每次readPixel/writePixel调用都要做一次CPU-GPU同步，而批量操作只做一次。

铁律：能批量就批量，绝不逐像素读写。

4.3 PixelMap的内存占用

一张RGBA_8888格式的图片，内存占用 = 宽 × 高 × 4字节。一张1000x1000的图片就是4MB，4000x3000的照片就是48MB。如果你同时持有多个大图PixelMap，内存很容易爆。

建议：

• 不用的PixelMap及时release()
• 大图先缩放再处理：imageSource.createPixelMap({ desiredSize: { width: 800, height: 600 } })
• 使用image.PixelMapFormat.RGB_565格式可以减半内存（但丢失透明度）

4.4 PixelMap不能跨线程

和上篇文章提到的一样，PixelMap对象不能通过@Sendable或TaskPool传递到其他线程。

解决方案：在子线程处理ArrayBuffer（像素数据），处理完后传回主线程再写入PixelMap。

// 正确做法：子线程处理Buffer，主线程写PixelMap
import { taskpool } from '@kit.ArkTS';

@Concurrent
function processBufferInWorker(buffer: ArrayBuffer, width: number, height: number): ArrayBuffer {
  // 在子线程中处理像素数据
  const dataView = new DataView(buffer);
  for (let i = 0; i < width * height; i++) {
    const offset = i * 4;
    const r = dataView.getUint8(offset);
    const g = dataView.getUint8(offset + 1);
    const b = dataView.getUint8(offset + 2);
    const gray = Math.round(0.299 * r + 0.587 * g + 0.114 * b);
    dataView.setUint8(offset, gray);
    dataView.setUint8(offset + 1, gray);
    dataView.setUint8(offset + 2, gray);
  }
  return buffer;
}

4.5 writeBufferToPixels的Buffer大小必须精确

writeBufferToPixels(buffer)要求buffer的大小必须等于width * height * bytesPerPixel。大了不行，小了也不行，否则直接抛异常。

建议：写入前先调用pixelMap.getImageInfo()获取尺寸，精确计算buffer大小。

五、HarmonyOS 6适配

5.1 PixelMap API变化

5.2 性能提升

HarmonyOS 6对PixelMap的底层实现做了重大优化：

• GPU加速的像素操作：crop、flip、rotate等方法直接在GPU上执行，速度提升5-10倍
• 新增零拷贝模式：对于只读场景，PixelMap可以直接引用GPU纹理，避免CPU-GPU数据拷贝

5.3 迁移建议

// HarmonyOS 5：手动裁剪（需要像素拷贝）
// HarmonyOS 6：使用原生crop方法
pixelMap.crop({ x: 100, y: 100, size: { width: 200, height: 200 } });

// HarmonyOS 5：手动翻转
// HarmonyOS 6：使用原生flip方法
pixelMap.flip(true, false); // 水平翻转

// HarmonyOS 6：设置色彩空间
const options: image.PixelMapInitializationOptions = {
  editable: true,
  pixelFormat: image.PixelMapFormat.RGBA_8888,
  size: { width: 800, height: 600 },
  colorSpace: image.ColorSpace.DISPLAY_P3 // 支持广色域
};

六、总结

一句话总结：PixelMap操作的核心原则是「批量优先、及时释放、线程安全」——掌握这三点，像素级操作不再是性能黑洞。