《HarmonyOS技术精讲-Image Kit：图片编辑进阶 - 像素级读写与翻转》

实际开发中的像素编辑需求

HarmonyOS NEXT 开发中，Image Kit 的 PixelMap 提供了完整的像素级编辑能力。但很多人第一次接触 readPixelsToBuffer 和 writePixelsFromBuffer 时，会发现官方示例能运行，但实际项目里并不稳定——比如图片加载后像素数据为空、写入后图片变花等问题。

这个功能本身不复杂，但真正麻烦的是 Buffer 的生命周期管理和像素格式的匹配。如果你需要做类似滤镜、翻转、缩略图生成这类像素级操作，Image Kit 的 PixelMap 是绕不开的。

这篇内容解决什么问题

PixelMap 的像素级操作主要解决以下场景：

场景	使用 API	说明
读取像素数据	readPixelsToBuffer	将 PixelMap 的像素数组拷贝到 Buffer
写入像素数据	writePixelsFromBuffer	将修改后的 Buffer 写回 PixelMap
翻转/旋转	像素交换逻辑	手动交换像素位置实现

不适合的场景：仅修改图片元数据（如 EXIF 信息）不需要像素级操作；简单的缩放或裁剪建议用 Image Kit 提供的 scale 和 crop API，性能更好。

环境说明

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：手机

核心实现：灰度图和水平翻转

第一步：从资源文件加载图片并创建 PixelMap

// 从资源文件加载图片
import { image } from '@kit.ImageKit';

async function loadImageFromResource(context: Context, resourceName: string): Promise<image.PixelMap> {
  // 注意：资源文件需要通过 getContext().resourceManager 获取
  const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
  
  // 读取资源文件为 ArrayBuffer
  const arrayBuffer: ArrayBuffer = await resourceMgr.getRawFileContent(resourceName);
  
  // 创建 ImageSource
  const imageSource: image.ImageSource = image.createImageSource(arrayBuffer);
  
  // 解码为 PixelMap
  const pixelMap: image.PixelMap = await imageSource.createPixelMap({
    desiredPixelFormat: image.PixelMapFormat.RGBA_8888  // 统一使用 RGBA_8888 格式
  });
  
  return pixelMap;
}

这段代码的关键点在于 desiredPixelFormat 参数。如果你不指定，解码器会使用图片原始格式。但像素级操作时，统一为 RGBA_8888 能简化 Buffer 的读写逻辑——每个像素固定 4 字节（R, G, B, A 各 1 字节）。

第二步：读取像素数据到 Buffer

function readPixels(pixelMap: image.PixelMap): ArrayBuffer {
  // 计算需要的 Buffer 大小：宽 * 高 * 4 (RGBA)
  const pixelsSize: number = pixelMap.getPixelBytesNumber();
  
  // 创建 Buffer
  const buffer: ArrayBuffer = new ArrayBuffer(pixelsSize);
  
  // 读取像素数据
  pixelMap.readPixelsToBuffer(buffer);
  
  return buffer;
}

这里需要注意 getPixelBytesNumber() 返回的是实际像素数据占用的字节数，不一定等于 width * height * 4。如果你的 PixelMap 格式不是 RGBA_8888，这个值会不同。

第三步：实现灰度图转换

function convertToGrayscale(pixelMap: image.PixelMap): ArrayBuffer {
  const buffer: ArrayBuffer = readPixels(pixelMap);
  const uint8Array: Uint8Array = new Uint8Array(buffer);
  
  // 遍历每个像素（4 字节一组）
  for (let i = 0; i < uint8Array.length; i += 4) {
    const r: number = uint8Array[i];     // Red
    const g: number = uint8Array[i + 1]; // Green
    const b: number = uint8Array[i + 2]; // Blue
    // uint8Array[i + 3] 是 Alpha 通道，灰度图保留原 Alpha
    
    // 加权平均法计算灰度值 (人眼对绿色最敏感，对蓝色最不敏感)
    const gray: number = Math.round(0.299 * r + 0.587 * g + 0.114 * b);
    
    // 将 R, G, B 都设为灰度值
    uint8Array[i] = gray;
    uint8Array[i + 1] = gray;
    uint8Array[i + 2] = gray;
    // Alpha 通道保持不变
  }
  
  return buffer;
}

灰度转换的加权系数不是随便定的，它是基于人眼对不同颜色敏感度的标准系数。如果你直接用平均值 (r + g + b) / 3，转换出来的图片对比度会偏低。

第四步：实现水平翻转（手动像素交换）

function horizontalFlip(pixelMap: image.PixelMap): ArrayBuffer {
  const buffer: ArrayBuffer = readPixels(pixelMap);
  const uint8Array: Uint8Array = new Uint8Array(buffer);
  
  const width: number = pixelMap.getWidth();
  const height: number = pixelMap.getHeight();
  
  // 遍历每一行
  for (let row = 0; row < height; row++) {
    // 对称交换水平方向的像素
    for (let col = 0; col < Math.floor(width / 2); col++) {
      // 计算左右两个像素的起始索引
      const leftPixelIndex: number = (row * width + col) * 4;
      const rightPixelIndex: number = (row * width + (width - 1 - col)) * 4;
      
      // 交换左像素和右像素
      for (let channel = 0; channel < 4; channel++) {
        const temp: number = uint8Array[leftPixelIndex + channel];
        uint8Array[leftPixelIndex + channel] = uint8Array[rightPixelIndex + channel];
        uint8Array[rightPixelIndex + channel] = temp;
      }
    }
  }
  
  return buffer;
}

翻转逻辑是直接在 Buffer 上做像素交换，没有使用任何翻转 API。性能上，对于 1080P 的图片，这个操作耗时大约 10-30ms，可以直接在主线程执行。

第五步：写入修改后的 Buffer

async function applyPixels(pixelMap: image.PixelMap, buffer: ArrayBuffer): Promise<void> {
  // 将修改后的 Buffer 写回 PixelMap
  await pixelMap.writePixelsFromBuffer(buffer);
}

writePixelsFromBuffer 是异步方法，需要 await。如果你写回后马上使用 PixelMap，可能会出现数据未写入完成的问题。

完整使用示例

@Entry
@Component
struct ImageEditorDemo {
  @State pixelMap: image.PixelMap | null = null;
  @State isGrayscale: boolean = false;
  @State isFlipped: boolean = false;
  
  async aboutToAppear() {
    // 注意：aboutToAppear 中不能直接使用 getContext()
    // 需要延迟执行或通过事件触发
  }
  
  async loadAndProcessImage() {
    const context: Context = getContext(this);
    this.pixelMap = await loadImageFromResource(context, 'test.jpg');
    
    // 先显示原图
    this.isGrayscale = false;
    this.isFlipped = false;
  }
  
  async applyGrayscale() {
    if (!this.pixelMap) return;
    
    const buffer: ArrayBuffer = convertToGrayscale(this.pixelMap);
    await applyPixels(this.pixelMap, buffer);
    
    // 触发 UI 刷新
    this.isGrayscale = true;
  }
  
  async applyHorizontalFlip() {
    if (!this.pixelMap) return;
    
    const buffer: ArrayBuffer = horizontalFlip(this.pixelMap);
    await applyPixels(this.pixelMap, buffer);
    
    this.isFlipped = true;
  }
  
  build() {
    Column() {
      if (this.pixelMap) {
        Image(this.pixelMap)
          .width('100%')
          .height('50%')
      }
      
      Row() {
        Button('灰度图')
          .onClick(() => this.applyGrayscale())
        
        Blank()
        
        Button('水平翻转')
          .onClick(() => this.applyHorizontalFlip())
      }
      .padding(16)
    }
    .width('100%')
    .height('100%')
  }
}

常见问题

问题 1：读取的像素数据全部是 0

现象：调用 readPixelsToBuffer 后，Buffer 里的值全部是 0。

原因：PixelMap 在使用前没有正确创建，或者创建时没有解码完成。常见于异步加载场景，读取操作在加载完成前执行。

解决方案：确保 createPixelMap 完成后才调用读取操作。

// 错误写法：没有 await
const pixelMap = imageSource.createPixelMap();
readPixels(pixelMap);  // 此时 pixelMap 尚未初始化完成

// 正确写法
const pixelMap = await imageSource.createPixelMap();
readPixels(pixelMap);

问题 2：写入后图片花屏或颜色不对

现象：调用 writePixelsFromBuffer 后，显示的图片出现色块、条纹或整体偏色。

原因：Buffer 的大小和格式与 PixelMap 不匹配。比如创建 PixelMap 时格式是 RGB_888，但 Buffer 按 RGBA_8888 写入。

解决方案：统一使用 PixelMapFormat.RGBA_8888 创建，并且确认 getPixelBytesNumber() 返回的大小与 Buffer 的 byteLength 一致。

// 创建时指定格式
const pixelMap = await imageSource.createPixelMap({
  desiredPixelFormat: image.PixelMapFormat.RGBA_8888
});

// 读取时确认大小
const bufferSize: number = pixelMap.getPixelBytesNumber();
console.info(`PixelMap buffer size: ${bufferSize}`);

问题 3：频繁读写导致内存溢出

现象：连续多次执行像素操作后，应用内存持续增长，最终崩溃。

原因：每次调用 readPixelsToBuffer 都会创建新的 Buffer，旧的 Buffer 如果没有及时释放，会造成内存堆积。

解决方案：复用 Buffer 对象，避免频繁创建。

let cachedBuffer: ArrayBuffer | null = null;

function getOrCreateBuffer(pixelMap: image.PixelMap): ArrayBuffer {
  const requiredSize: number = pixelMap.getPixelBytesNumber();
  
  if (cachedBuffer === null || cachedBuffer.byteLength !== requiredSize) {
    cachedBuffer = new ArrayBuffer(requiredSize);
  }
  
  return cachedBuffer;
}

最佳实践

1. 不要在 build() 中执行像素操作：ArkUI 的 build() 方法是同步的，且会频繁调用。像素操作是 I/O 密集型的，放在 build() 中会导致 UI 卡顿。建议在事件回调或异步任务中执行。

2. 像素操作前先备份原始数据：如果用户需要对图片做多次编辑（如先翻转再调色），建议在操作前克隆一个 PixelMap，或者备份原始 Buffer。否则连续操作会互相覆盖。

3. 大图片考虑分块处理：对于 4K 或更大分辨率图片，单次读取整个 Buffer 可能消耗大量内存。可以使用 region 参数分块读取，但这需要更复杂的内存管理。对于大多数手机拍照的场景（1200万像素以内），一次性读取是可以接受的。

FAQ

Q：为什么真机正常，但某些模拟器上像素读写后图片花屏？
A：模拟器的 PixelMap 实现可能与真机有差异，尤其是在 RGBA 通道的顺序上。建议始终在真机上测试。如果必须在模拟器测试，确认模拟器版本不低于 API 12。

Q：为什么页面返回后像素操作的状态丢失？
A：PixelMap 不会自动持久化。如果页面返回后需要保留编辑状态，需要在 onPageHide 或 aboutToDisappear 中将 PixelMap 保存为文件，或者使用全局状态管理。

Q：可以同时对同一个 PixelMap 做多次读写吗？
A：不建议。writePixelsFromBuffer 是异步操作，连续多次调用会形成竞争条件。如果需要连续编辑，建议每次修改后重新读取 Buffer，或者使用队列机制控制执行顺序。

---

示例代码地址：项目地址