图片解码入门：从文件到PixelMap

在HarmonyOS NEXT开发里，Image Kit（图片处理服务）是处理图片的官方API，但很多人第一次接触时容易忽略一个问题：createPixelMap的默认行为并不能直接拿到可用的示例。

这个问题在真实项目中特别常见。比如你从相册选了一张图，调用createPixelMap后直接赋值给Image组件，结果发现图片变形了。这不是API的Bug，而是因为没有理解解码参数和默认采样策略。

本文就是从实战出发，完整走一遍用ImageSource解码本地图片的流程，同步和异步两种方式都讲清楚，顺便把那些容易忽略的细节也点出来。

ImageSource是什么，解决什么问题

ImageSource是Image Kit的核心类，负责从各种来源（文件、资源、网络数据流）中解码图片。它的作用不是加载图片，而是控制解码过程。

没有ImageSource之前，直接给Image组件传路径也能显示图片，但问题是：

• 无法控制分辨率
• 无法获取原始宽高
• 无法处理超大图

有了ImageSource，你可以：

1. 精确控制解码尺寸（减少内存占用）
2. 获取图片元信息（宽高、格式）
3. 支持同步/异步两种解码方式

对比直接传路径，Image Kit提供的这套API更适合需要精细控制的场景，比如相册预览、图片编辑、列表缩略图。

环境说明

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

核心实现：从文件解码到PixelMap

1. 创建ImageSource

第一步是从文件创建ImageSource。有两种方式：传文件路径或传文件描述符。

这里推荐用文件描述符，因为很多场景下拿不到路径（比如从临时文件读取）。

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

// 方式一：通过文件路径创建
function createSourceFromPath(path: string): image.ImageSource {
    const source = image.createImageSource(path);
    return source;
}

// 方式二：通过文件描述符创建（推荐）
function createSourceFromFd(fd: number): image.ImageSource {
    const source = image.createImageSource(fd);
    return source;
}

注意事项：创建ImageSource之后，不再使用时必须调用release释放资源，否则会持续占用文件句柄。

2. 设置解码参数

解码参数通过DecodingOptions配置。最常用的参数是desiredSize，它决定了输出PixelMap的尺寸。

function buildDecodingOptions(): image.DecodingOptions {
    const options: image.DecodingOptions = {
        desiredSize: { width: 200, height: 200 },
        desiredPixelFormat: image.PixelMapFormat.RGBA_8888
    };
    return options;
}

desiredSize不是最终输出尺寸，而是采样参考。比如原图是4000x3000，你设成200x200，解码时会自动缩放到接近这个尺寸。这样做的好处是节省内存，坏处是如果你需要精确宽高，需要额外处理。

desiredPixelFormat一般用RGBA_8888，兼容性好。如果对透明度没要求，用RGB_565能省一半内存。

3. 同步解码：createPixelMap同步版

同步解码会阻塞当前线程，适合在子线程或对速度要求不高时使用。

function decodeSync(source: image.ImageSource): image.PixelMap {
    const options = buildDecodingOptions();
    try {
        const pixelMap = source.createPixelMapSync(options);
        console.info('同步解码成功，宽度：' + pixelMap.getImageInfoSync().size.width);
        return pixelMap;
    } catch (error) {
        console.error('同步解码失败，错误：' + JSON.stringify(error));
        return null;
    }
}

注意：同步解码如果图片过大，会卡住UI线程。所以不能在@Entry组件的aboutToAppear里直接调，除非你确定图片很小。

4. 异步解码：createPixelMap回调版

异步解码通过回调返回PixelMap，不会阻塞调用线程。

function decodeAsync(source: image.ImageSource, callback: (pixelMap: image.PixelMap) => void): void {
    const options = buildDecodingOptions();
    source.createPixelMap(options, (error, pixelMap) => {
        if (error) {
            console.error('异步解码失败，错误：' + JSON.stringify(error));
            return;
        }
        // 这里可以拿到pixelMap了
        const info = pixelMap.getImageInfoSync();
        console.info('异步解码成功，宽：' + info.size.width + ' 高：' + info.size.height);
        callback(pixelMap);
    });
}

这个回调是异步的，所以不能在里面直接更新@State变量——除非你通过runOnUiThread切回主线程。

5. 获取图片基本属性

解码之后，通过getImageInfoSync获取宽高。

function getImageInfo(pixelMap: image.PixelMap): image.ImageInfo {
    const info = pixelMap.getImageInfoSync();
    console.info('宽度：' + info.size.width);
    console.info('高度：' + info.size.height);
    return info;
}

这个信息在计算布局、裁剪、缩放时非常有用。

6. 完整示例：从文件解码并展示

下面是一个完整的@Entry组件，演示了如何从应用资源目录的图片文件解码并显示。

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

@Entry
@Component
struct ImageDecodeDemo {
    @State pixelMap: image.PixelMap = null;
    @State imageInfo: string = '';

    build() {
        Column() {
            if (this.pixelMap) {
                Image(this.pixelMap)
                    .width(200)
                    .height(200)
                    .objectFit(ImageFit.Contain)
                    .margin(20)
                Text(`宽：${this.imageInfo}像素`)
                    .fontSize(16)
                    .fontColor('#666')
            } else {
                Text('解码中...')
                    .fontSize(16)
            }
            Button('解码图片')
                .onClick(() => this.decodeImage())
                .margin(20)
        }
        .width('100%')
        .height('100%')
        .justifyContent(FlexAlign.Center)
    }

    async decodeImage() {
        // 从应用沙箱获取文件描述符
        const context = getContext(this) as common.UIAbilityContext;
        const filePath = context.filesDir + '/test_image.jpg';
        // 这里假设文件已存在，实际可以从rawfile或网络下载

        // 创建ImageSource
        const source = image.createImageSource(filePath);
        // 设置解码参数
        const options: image.DecodingOptions = {
            desiredSize: { width: 400, height: 400 },
            desiredPixelFormat: image.PixelMapFormat.RGBA_8888
        };

        try {
            const pixelMap = await source.createPixelMap(options);
            this.pixelMap = pixelMap;
            const info = pixelMap.getImageInfoSync();
            this.imageInfo = `${info.size.width} x ${info.size.height}`;
        } catch (error) {
            console.error('解码失败：' + JSON.stringify(error));
        } finally {
            source.release();
        }
    }
}

常见问题与踩坑记录

问题1：同步解码导致页面白屏

现象：在aboutToAppear里调用同步解码，页面加载时卡顿甚至白屏。

原因：同步解码会阻塞UI线程，如果图片较大（比如相机拍的照片），解码时间可能超过100ms，导致ArkUI的渲染帧无法按时提交。

解决方案：用异步解码代替同步解码。如果需要同步解码，一定要放到子线程（通过TaskPool或Worker）。

问题2：异步回调里直接赋值导致状态不刷新

现象：在createPixelMap的回调里直接this.pixelMap = pixelMap，但页面没有更新。

原因：回调不在UI线程上执行，ArkUI的状态管理无法感知。

解决方案：使用async/await模式，或通过@State的runOnUiThread机制更新。

// 正确做法
async decodeAndUpdate(): Promise<void> {
    const pixelMap = await source.createPixelMap(options);
    // 这里已回到UI线程
    this.pixelMap = pixelMap;
}

问题3：desiredSize设了等于没设

现象：设置了desiredSize，但输出的PixelMap尺寸和原图一样大。

原因：desiredSize是参考尺寸，不是精确尺寸。如果原图是100x100，你设成200x200，解码器不会放大，而是输出原尺寸。

解决方案：如果需要精确控制输出尺寸，解码后用pixelMap.scale或手动缩放。同时检查原图尺寸是否小于desiredSize。

最佳实践

1. 优先使用异步解码：同步解码一旦卡住，整个页面就废了。异步解码配合async/await写起来并不复杂。

2. 解码后及时释放ImageSource：每个ImageSource都持有一个文件句柄，不释放会导致文件描述符泄漏。推荐用try/finally或use语法。

3. 控制desiredSize：对于列表缩略图，设成200x200就够用了。预览大图时设成屏幕宽高即可。不要设太大，否则内存暴涨。

4. 解码前检查文件是否存在：文件不存在时，createImageSource会直接抛异常，没有友好的错误提示。

Demo入口

以上代码可以直接复制到新项目的pages/Index.ets中运行。注意需要在filesDir下放一个test_image.jpg。

@Entry
@Component
struct Index {
    // 代码见上文完整示例
}

FAQ

Q：为什么decodeAsync的回调里不能直接更新页面？
A：回调不在UI线程上执行，ArkUI的@State只能在UI线程更新。用async/await会自动回到UI线程。

Q：可以同时解码多张图片吗？
A：可以，但需要注意内存。每张解码后的PixelMap都会占用独立内存，建议用缓存控制并发数量，比如只同时解码3张。

Q：解码后的PixelMap能直接存到文件吗？
A：不能直接存。需要先通过image.Packer编码成JPEG或PNG格式，再写入文件。这个后续再单独讲。

Q：ImageSource支持哪些图片格式？
A：常见的JPEG、PNG、WebP都支持。GIF只取第一帧。BMP和TIFF部分版本支持。

---

示例代码地址：项目地址