OpenHarmony RN应用PixelFormat转换实战：从RGBA到NV12的完整指南

1. 为什么会在一款RN应用里动PixelFormat

1.1 你手里的是"图片"，不是"像素"

先讲个很典型的现场。拿着一个OpenHarmony设备做React Native开发，从相册选了一张照片，要传到一个人脸识别SDK里。SDK要求输入RGBA字节流，你在JS里把uri传给接口，结果对方返回一个"format not supported"，或者图片显示出来整体发绿、颜色错乱。常见的直觉是"图片格式转一下不就行了"，但你在ArkTS/JS里翻了一圈，发现根本没有现成的convertPixelFormat()这种万能接口。问题就卡在：你手里的是一个被封装好的PixelMap对象，而不是一堆可以直接理解的内存字节。

很多做RN开发的同事一开始不理解，为什么图片这种"基础能力"，在OpenHarmony上会变成必须仔细处理的环节。原因其实不复杂：**OpenHarmony的媒体框架处理的是PixelMap，RN组件要显示的是Image，而底层编码器、摄像头、显示控制器各自约定的是PixelFormat。**这三层之间不会自动替你转换，一旦某个环节的格式约定不匹配，轻则花屏，重则整个链路直接报错。

1.2 RN框架挡在中间，但不能不碰格式

React Native for OpenHarmony（RNOH）把原生能力封装成了JS接口，这是好事，因为它屏蔽了大量底层差异。但也带来了一个问题：当你要把图片字节流交给某个原生算法库、硬件编码器或者第三方SDK时，RN框架并不知道你对端要的是什么PixelFormat，它只会把PixelMap原样交给你。所以你必须在某个节点主动去做一次格式协商和转换。

举个更直白的例子：你用RN写的App要调用一个C++实现的图像处理模块，这个模块只接受NV12或者NV21的YUV数据，而RN Image组件从相册读出来的照片，默认解出来多半是RGBA_8888。这时候你没有别的路可走，只能做一次从RGBA到NV12的转换。转换前必须搞清楚RGBA_8888的内存排列、NV12的Y平面和UV平面的位置、宽高对齐规则，这些东西任何一个点弄错，结果都是一帧不能用的数据。

1.3 哪些项目尤其逃不掉

如果你只是把网络图片显示在页面上，那PixelFormat基本不用操心，RNOH内部已经处理好了。但如果你的项目踩中下面任一条，我建议你把这篇文章读完：

• 调用人脸识别、OCR、图像质量检测等三方算法SDK，且SDK要求裸数据输入；
• 做视频流处理或低延迟拍照，需要把相机预览帧直接喂给编码器；
• 要在ArkTS/JS层做图像裁剪、缩放、水印，还要保证输出数据能被原生模块直接使用；
• 在RK3568、RK3588这类开发板上做硬件编解码，需要判断输出帧格式到底是NV12还是NV21，是TILE还是LINEAR。

这些问题在纯RN项目里可能一辈子遇不到，但一旦遇到，网上资料零零散散，尤其RNOH相关的几乎没有。所以我把这一路的经验整理成文，后面每一节都对应一个真实会踩的坑。

2. PixelFormat是个什么黑盒：从RGBA到YUV的编码差异

2.1 主流格式与内存排布

先说最基础的。PixelFormat描述的是每个像素在内存里怎么存储，它比"图片格式是jpg还是png"低一个层次。jpg/png是容器格式，解码之后才会得到PixelFormat层面的数据。OpenHarmony里常见的PixelMap格式包括：RGBA_8888、BGRA_8888、RGB_565、NV12、NV21，部分地方还会出现ARGB_8888和灰度格式。

这几种格式的内存排布是理解所有问题的地基：

一个容易忽略的点：RGB_565虽然省内存，但缺失Alpha通道，而且绿色通道占6位导致颜色精度不均匀，图像里如果有渐变色或肤色，RGBA转RGB_565之后会出现肉眼可见的色带。所以只要不是屏幕或硬件强制要求，我一般不建议把图像转成RGB_565保存。

2.2 YUV家族：NV12/NV21为什么这么常见

很多做RN的人第一次接触YUV会非常不习惯，因为它的思路和RGB完全不一样。RGB是直接用三原色表示颜色，而YUV把亮度（Y）和色度（UV）分开。这样做的好处是：人眼对亮度敏感、对色度不敏感，所以可以降低色度的采样率来压缩数据量，这就是所谓YUV420的由来。

NV12和NV21都属于YUV420的存储变种。它们把一帧图像分成两个平面：

• 第一个平面：Y数据，大小为width * height，每个像素一个字节；
• 第二个平面：UV数据，大小为width * height / 2，每两个像素共享一组U和V。

区别只在于UV交错排列的顺序，NV12是U、V、U、V……，NV21是V、U、V、U……。这个顺序一旦搞反，图像不会变灰，而是会出现严重的颜色失真，典型表现是整个画面像被上了色偏滤镜，红色和蓝色互换。摄像头和硬件编码器对NV12/NV21有各自的偏好，所以做相机采集和视频编码时，我们要先明确设备到底输出哪种格式。

2.3 对齐和色彩范围：两个容易翻车的小细节

第一个细节是行对齐（stride）。很多初接触裸数据的开发者默认地把"宽640"理解成"每行640字节"，这在RGBA_8888下是对的，因为每像素4字节，一行就是2560字节。但有些硬件在分配内存时，会对每行做16字节、32字节或64字节的对齐，导致实际每行字节数大于理论值。如果你按"宽*高"去计算数据长度，最后取到的数据尾部会串行，画面出现斜向错位。

第二个细节是YUV的色彩范围。YUV里Y的值不一定是0到255，常见有两种范围：

• Full range：Y、U、V全部使用0到255；
• Limited range（视频范围）：Y使用16到235，U和V使用16到240。

摄像头输出的NV12通常是limited range，而OpenHarmony的显示和图像算法内部多数按full range处理。转换RGB到YUV时不考虑这个差异，会导致画面整体发灰、对比度偏低。这也是"为什么我转换完颜色看起来不对"的隐性元凶之一。

3. RN for OpenHarmony里读取PixelMap的三种路线

3.1 路线一：ImageSource + PixelMap

这是最常用的一条路，适用于处理相册图片、应用内静态图片资源。核心API集中在@ohos.multimedia.image里，流程是：

1. 用文件描述符或字节数组创建ImageSource；
2. 通过createPixelMap得到PixelMap；
3. 用readPixelsToBuffer把像素数据读到ArrayBuffer里。

代码框架大致是这样：

typescript复制import image from '@ohos.multimedia.image';
import fs from '@ohos.file.fs';

async function loadPixelMap(uri: string): Promise<image.PixelMap> {
  const file = await fs.open(uri, fs.OpenMode.READ_ONLY);
  const imageSource = image.createImageSource(file.fd);
  const options: image.InitializationOptions = {
    desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
    desiredSize: { width: 640, height: 480 }
  };
  const pixelMap = await imageSource.createPixelMap(options);
  fs.close(file);
  return pixelMap;
}

注意desiredPixelFormat这个参数。如果你明确后续要对数据进行YUV转换，最好一开始就让它输出RGBA_8888，因为RGBA在JS里最容易做手工处理。假如一开始选了NV12，PixelMap会直接把YUV数据交给你，乍看省了一步，但实际上这个YUV的存储排布、对齐方式完全由底层决定，反而不如从RGBA开始可控。

拿到PixelMap之后，读取像素数据：

typescript复制const imageInfo = await pixelMap.getImageInfo();
const bytesPerPixel = pixelMap.getBytesNumberPerRow() / imageInfo.size.width;
const buffer = new ArrayBuffer(pixelMap.getPixelBytesNumber());
await pixelMap.readPixelsToBuffer(buffer);
const bytes = new Uint8Array(buffer);

这里的getBytesNumberPerRow()很重要，它返回的是实际每行字节数，不一定是width * bytesPerPixel。手动处理像素时，必须用这个值来定位每行数据。

3.2 路线二：Camera Kit回调里的buffer

相机预览是另一个高频场景。调用相机时，ImageReceiver会持续回调图像数据，这时的格式通常由创建ImageReceiver时的参数决定：

typescript复制import image from '@ohos.multimedia.image';
import camera from '@ohos.multimedia.camera';

const receiver = image.createImageReceiver({
  width: 1920,
  height: 1080,
  capCount: 4,
  desiredPixelFormat: image.PixelMapFormat.NV12
});

这里的desiredPixelFormat直接告诉相机管线输出NV12还是NV21，或者RGBA。RK3568开发板上的摄像头ISP默认输出一般是NV12，但有的摄像头传感器驱动或者定制系统会输出NV21。很多开发者在此踩坑：明明上层指定了NV12，收到的数据还是偏色。这时候不需要急着改转换代码，先确认系统相机服务是否透传了你的格式要求。

相机回调拿到的是image.Image对象，不是PixelMap，需要额外获取：

typescript复制const img = await receiver.readNextImage();
const buffer = await img.getComponent(image.ComponentType.YUV_Y);
// 或者读取UV分量 img.getComponent(image.ComponentType.YUV_U)

做实时预览时，不要在JS里逐像素转换，后面第5节会专门说性能问题。相机管线里最合理的做法是：设置接收端格式与编码器/算法库输入格式一致，让底层硬件完成转换，而不是在内存层面绕一圈。

3.3 路线三：硬件编码器/视频帧的format协商

RNOH应用如果要处理视频文件，一般会通过@ohos.multimedia.media的AVImageGenerator或AVPlayer提取视频帧。这些接口返回的PixelMap格式同样由desiredPixelFormat控制，但它背后是硬件解码器在起作用。硬件解码器输出的格式往往不是你能随便指定的，比如RK3588的H.264解码器通常输出NV12，有些固件还支持输出RGBA_8888，但需要额外配置。

这里我想强调一个容易忽略的点：解码器输出的YUV数据可能存在"宽高对齐"之外，还有"缓冲区块分布"的问题。 部分硬件解码器输出的NV12不是连续存储的，Y平面是一块内存，UV平面可能是另一块独立的内存区域，甚至可能是块间有间隔的tiled布局。如果你从PixelMap里读出来的buffer大小和理论值不一致，别急着改公式，先用厂商工具确认存储布局是不是linear（线性）格式。

4. 实操：在RN端把RGBA_8888转成NV12再交出去

4.1 第一步：取图和PixelMap

先声明：如果只是要做一次静态转换，不追求实时，直接在ArkTS/TS里写转换逻辑是可行的。下面这个例子的前提是，你已经通过原生桥接或者RNOH提供的模块拿到了一个RGBA_8888的ArrayBuffer，并知道它的宽高。

为了说清完整链路，我假设从系统相册选图：

typescript复制import { picker, PhotoViewPickerOptions } from '@kit.FilePickerKit';

async function pickImageAndConvert() {
  const photoPicker = new picker.PhotoViewPicker();
  const result = await photoPicker.select({
    MIMEType: picker.PhotoViewMIMETypes.IMAGE_TYPE,
    maxSelectNumber: 1
  });
  const uri = result.photoUris[0];
  // 接下来用第3.1节的方法loadPixelMap(uri)
}

选图这一步在RN原生端做会更容易。RNCameraRoll或者自定义模块把uri传给OpenHarmony原生方法，原生返回像素字节流。这样RN的JS线程只负责接收Uint8Array和宽高参数，不需要跟文件系统打交道。

4.2 第二步：ByteBuffer里的数据到底长什么样

假设你已经拿到了RGBA_8888的buffer，width=640，height=480，buffer总大小应该是640 * 480 * 4 = 1228800字节。内存里第0到第3字节分别是第0个像素的R、G、B、A，第4到第7字节是第1个像素的R、G、B、A，以此类推。

这里有个特别容易踩的坑：ImageSource在创建PixelMap时，虽然指定了RGBA_8888，但PixelMap的行字节数仍然可能带对齐。 前面提到过用getBytesNumberPerRow()获取真实行字节数。如果返回的是2560（即640*4），说明无对齐；如果返回的是2576或者别的大于2560的数，说明有填充字节。手动转换时如果忽略填充字节，只按width*4跳行，后面每一行都会错位。正确的做法是每处理完一行，把指针跳转到bytesPerRow，而不是width*4。

给出一个确定每行起始位置的代码，后续转换都依赖这个：

typescript复制const bytesPerRow = pixelMap.getBytesNumberPerRow();
const width = imageInfo.size.width;
const height = imageInfo.size.height;
const bytesPerPixel = 4; // RGBA_8888
const src = new Uint8Array(buffer);

for (let y = 0; y < height; y++) {
  const rowStart = y * bytesPerRow;
  for (let x = 0; x < width; x++) {
    const idx = rowStart + x * bytesPerPixel;
    const r = src[idx];
    const g = src[idx + 1];
    const b = src[idx + 2];
    // 处理这个像素
  }
}

4.3 第三步：手动实现RGB到YUV转换

转换公式网上到处都有，但很多文章只给了一套公式，没有说明适用范围。下面这套是BT.601 limited range的标准做法，适合摄像头/视频编码场景，也是大多数OpenHarmony硬件编码器采用的转换基准：

code复制Y = (66 * R + 129 * G + 25 * B + 128) / 256 + 16
U = (-38 * R - 74 * G + 112 * B + 128) / 256 + 128
V = (112 * R - 94 * G - 18 * B + 128) / 256 + 128

如果整套算法库或者编码器按full range处理，用下面这组：

code复制Y = (77 * R + 150 * G + 29 * B + 128) / 256
U = (-44 * R - 87 * G + 131 * B + 128) / 256 + 128
V = (131 * R - 110 * G - 21 * B + 128) / 256 + 128

代码实现如下，注意结果需要做clamp，把值控制在[0, 255]内：

typescript复制function rgbaToNv12(
  src: Uint8Array,
  dest: Uint8Array,
  width: number,
  height: number,
  srcBytesPerRow: number
): void {
  const yPlaneSize = width * height;
  // NV12: Y平面 | UV交错平面(U先)
  let yIndex = 0;
  let uvIndex = yPlaneSize;

  for (let y = 0; y < height; y += 2) {
    for (let x = 0; x < width; x += 2) {
      // 每个2x2块采样一组UV
      let rSum = 0, gSum = 0, bSum = 0;
      for (let dy = 0; dy < 2; dy++) {
        for (let dx = 0; dx < 2; dx++) {
          const py = y + dy;
          const px = x + dx;
          if (py >= height || px >= width) continue;
          const srcIdx = py * srcBytesPerRow + px * 4;
          const r = src[srcIdx];
          const g = src[srcIdx + 1];
          const b = src[srcIdx + 2];
          // 写Y
          const yy = ((66 * r + 129 * g + 25 * b + 128) >> 8) + 16;
          dest[yIndex++] = yy < 0 ? 0 : (yy > 255 ? 255 : yy);
          rSum += r; gSum += g; bSum += b;
        }
      }
      // 2x2平均后计算U、V
      const avgr = rSum >> 2;
      const avgg = gSum >> 2;
      const avgb = bSum >> 2;
      const u = ((-38 * avgr - 74 * avgg + 112 * avgb + 128) >> 8) + 128;
      const v = ((112 * avgr - 94 * avgg - 18 * avgb + 128) >> 8) + 128;
      dest[uvIndex++] = u < 0 ? 0 : (u > 255 ? 255 : u);
      dest[uvIndex++] = v < 0 ? 0 : (v > 255 ? 255 : v);
    }
  }
}

这段代码是教学向的，性能和正确性够用，但非常慢。如果读者要做实时转换，建议只看思路，不要照搬到生产环境。

一个小细节：2x2采样时，如果图像宽高是奇数，边缘像素会参与平均，可能产生彩边。建议在进入转换前，把宽高统一压到偶数，这是视频处理里都默认遵守的约定。

4.4 第四步：通过原生模块把结果交给解码器/算法库

数据转换完成后，下一步是把Uint8Array塞回给原生模块。在RNOH里，可以通过TurboModule或者自定义原生模块，导出一个方法：

typescript复制// 假设原生模块叫 PixelFormatModule
import { TurboModule, TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  feedData(buffer: Uint8Array, width: number, height: number): Promise<number>;
}

export default TurboModuleRegistry.get<Spec>('PixelFormatModule');

调用时注意，RN和原生之间传递大块ArrayBuffer时会有内存拷贝。如果数据量是1080p甚至4K，每次拷贝的耗时不可忽略。优化空间在于：如果你的算法库最终也是在设备本地执行，可以考虑用OpenHarmony的共享内存容器，或者直接让原生模块完成"读取PixelMap -> 转换 -> 喂给算法库"整条链路，JS只负责调度。

这句话可能有点得罪做RN的同学，但我是认真说的：在RNOH上做图像处理，最好的JS代码就是只负责拿uri和传结果。 中间凡是涉及大字节流的高频操作，都尽量放进原生侧。RN的作用是快速搭建业务逻辑，而不是跟ByteBuffer较劲。

5. RK3568/RK3588开发板的格式适配与设备树选择

5.1 为什么设备树会决定PixelFormat

搜索OpenHarmony开发板资料时，"rk3568有许多设备树到底咋选"是个高频问题。这跟PixelFormat看起来八竿子打不着，实际上关系非常大。

设备树（DTB）里定义了摄像头接口类型、ISP通道配置、显示接口、编码器状态等。不同的配置会直接影响硬件层能够输出的像素格式。比如同一块板子，A设备树配置了MIPI CSI摄像头，ISP输出NV12；B设备树配置了USB摄像头，走V4L2驱动，输出可能是YUYV或者MJPEG，这时你通过Camera Kit拿到的数据格式就完全不同。

同理，RK3588有更复杂的视频通路，一个视频源可以同时送往显示、编码、AI处理三个模块，每个模块对PixelFormat的要求都不一样。显示那边可能要求ARGB8888，编码器吃NV12，NPU侧可能格式又不一样。如果设备树里这些通路没有配好，上层应用无论怎么设desiredPixelFormat，底层也可能不执行转换，或者转换结果不对。

5.2 常见开发板踩坑：选错dts后出现的现象

我在RK3568上遇到过三种典型现象，都是设备树和PixelFormat相关的：

第一种，相机预览正常，但保存的图片是花的。排查后发现是设备树里ISP输出配置成了NV21，而上层相机示例默认按NV12处理，UV顺序反了。看起来是代码问题，根源在设备树。

第二种，视频编码后文件能播放，但颜色发灰、发暗。上层的VideoEncoder明明配好了NV12输入，但硬件编码器实际期望的是limited range的NV12，输入数据却是full range，导致对比度异常。

第三种，同一个RN应用在两个厂家的RK3588板子上表现不一样，一边正常，一边花屏。进去一看，一边的BSP把显示缓冲默认配成了BGRA_8888，另一边是RGBA_8888。RNOH层拿到的PixelMap也是跟着显示缓冲走的，于是同样的代码在不同板子上跑出不同颜色顺序。

这些现象的共同特征是：问题不在应用层，而在系统适配层。 所以在开发前，不要急着写转换函数，先花半天时间确认开发板的BSP、设备树、相机固件这些"底层约定"。

5.3 快速定位格式问题的一套排查命令

在OpenHarmony开发板上，遇到疑似PixelFormat问题时，我建议按下面顺序排查：

1. 先看系统相机能力支持哪些格式：

bash复制hdc shell "cat /sys/class/video4linux/video*/format"

如果设备有V4L2驱动，这个目录下能看到支持的格式列表，比如NV12、NV21、YUYV。

2. 查看当前设备树实际生效的dts：

bash复制hdc shell "cat /proc/device-tree/model"

这一步能看到板卡model，能帮助你判断烧录的镜像是否匹配所选设备树。

3. 看媒体服务日志里有没有格式协商失败：

bash复制hdc shell "hilog | grep PixelFormat"

媒体框架在创建编码器、解码器、相机会话时，会记录输入输出格式，如果格式协商不通过，日志里一般有明确错误码。

4. 用系统的采集工具抓一帧原始数据，直接看文件大小和存储排布：

bash复制hdc shell "snapshot_display -f /data/local/tmp/preview.yuv"

抓下来的裸数据用PC上的YUV播放器打开，如果画面偏色，就说明上游数据格式和下游解析格式不一致。这是最直观的判断方式。

我曾经在排查一个RN应用相机预览花屏问题时，所有应用层代码都查了一遍，最后发现就是板子上烧的镜像用了不匹配的设备树。换回正确dts之后，问题直接消失，连一行代码都没改。所以各位如果遇到看似无解的格式问题，务必把"系统适配"四个字放在心上。

6. 性能边界与架构建议

6.1 JS层转换到底多慢：一次实测

我在一台RK3568开发板上，用RNOH跑过一段纯TS的RGBA转NV12代码，数据量是640x480。设备CPU算力在开发板里算中等水平，结果如下：

注意，这个数据还只是静态图片，没有算上内存拷贝和GC开销。如果做成相机实时预览，每秒30帧意味着每帧必须在33ms内完成，显然JS层做不到。

为什么这么慢？原因不只是JS本身比C++慢，更在于R部分，你其实在做width*height次数组读操作和算术运算。对640x480的图就是30万次循环，每一帧做一个简单操作，消耗自然上去了。

6.2 什么情况下必须下沉到C++/原生

如果你面对的是下面任一种场景，我建议直接把转换逻辑放到原生侧：

• 相机预览、视频编码、实时美颜、实时滤镜这类每帧都要处理的任务；
• 单帧数据超过1MB，且转换后再传给SDK的场景；
• 涉及硬件编码器时，需要直接把内存缓冲交给编码器，减少一次拷贝。

OpenHarmony提供了Native Image API和C++接口，允许你在原生侧操作PixelMap buffer。最理想的架构是：C++侧完成"从PixelMap读数据 -> 转格式 -> 塞给自研算法或硬件编码器 -> 返回结果"全流程，RN只负责在JS里发起请求、拿结果。

另外，如果要在ArkTS侧做性能优化，尽量用ArrayBuffer而不是普通数组，避免逐元素访问开销。但即便这样，ArKTS的JIT优化程度也有限，别对纯TS的大循环抱太大期望。

6.3 一个更省事的方案：让系统帮你转

说了这么多手动转换，最后必须提一个更省事的方案：尽量让创建PixelMap或ImageReceiver的阶段就指定目标格式。

比如你明确知道算法库要NV12，就不要先用RGBA_8888创建PixelMap，再手动转成NV12。直接在createPixelMap的InitializationOptions里写desiredPixelFormat: image.PixelMapFormat.NV12。如果底层支持，它会直接返回NV12数据，你连转换代码都省了。同样，创建ImageReceiver时也直接指定最终需要的格式。

但要注意一个边界：不是所有源图格式都能被成功指定为目标格式。系统底层会根据源解码器和目标格式做一次能力判断，如果不支持，可能会抛错或者仍然输出默认格式。所以我的建议是：先设desired格式，拿到结果后通过getImageInfo()确认实际格式；如果不满足，再做手动转换作为兜底。

这个思路比上来就写转换公式要优先得多，因为系统自带的转换是经过优化和硬件加速的，往往比你手动实现快几倍。

最后再分享一点个人体会

做OpenHarmony + RN开发，最忌讳的是把Android/iOS的经验直接搬过来。在Android上，Bitmap的格式已经帮你处理好了大部分事，在OpenHarmony上，PixelMap虽然也做了很多封装，但一旦你的数据要走出RN这个"安全区"，比如交给算法SDK、硬件编码器、三方C++库，你就必须直面裸格式。这个转换的门槛不算高，但坑位密集：NV12和NV21的顺序、行对齐、色彩范围、设备树差异，每一个都真实决定着一帧画面是好的还是花的。

我在这个方向上吃过不少亏，最后沉淀出来的工作方法就三点：先确认底层能力，再尽量让系统统一格式，最后才考虑手动转换。RN负责把业务逻辑做流畅，像素级的事情交给合适的那一层去处理。希望这篇东西能让你少走一点我走过的弯路，如果后面你们团队在接入具体算法库或硬件编解码时遇到奇怪的格式问题，不妨回到这篇文章，先对着那张格式对比表一格格检查，多半能找到线索。