HarmonyOS 图片缩放没想象中简单——detailEnhance 四档质量深度解析
文章目录
- 先搞清楚：为什么不直接用系统缩放？
- 整体数据流
- 核心代码拆解
- 第一步：创建源 PixelMap 和目标 PixelMap
- 第二步：用 Select 控件选择档位并触发增强
- 第三步：Native 层接口声明（Index.d.ts）
- 四档质量对比
- 踩坑总结
- @StorageLink 实现跨页面状态共享
- 写在最后
用 ImageKit 处理图片缩放，第一次用的时候我以为就是个 resize，结果发现里面有个detailEnhance的参数，四个挡位差异挺大的。这篇文章就把这块说透。
先搞清楚：为什么不直接用系统缩放？
普通的scale()或者直接改 PixelMap 尺寸，底层用的是最近邻或双线性插值，放大之后会明显模糊、出锯齿。detailEnhance是走了 C++ Native 层的图像增强算法，相当于给缩放结果做了一轮超分辨率处理。
用大白话说：
- NONE：直接缩放，最快，质量最差
- LOW：轻度增强，比 NONE 稍好一点，速度也快
- MEDIUM：中等增强，日常使用最均衡的选择
- HIGH：最强增强，细节最好，耗时最长，不适合实时处理
整体数据流
核心代码拆解
第一步：创建源 PixelMap 和目标 PixelMap
import{image}from'@kit.ImageKit';importnativePixfrom'libentry.so';import{hilog}from'@kit.PerformanceAnalysisKit';getPixMap():void{try{// 从 rawfile 创建 ImageSourceletimageSource:image.ImageSource=image.createImageSource(this.getUIContext().getHostContext()?.resourceManager.getRawFdSync('ic_scaling.png'));// 同步解码为 PixelMapthis.pixelMapSrc=imageSource.createPixelMapSync();// 获取原始尺寸constimageInfo:image.ImageInfo=this.pixelMapSrc.getImageInfoSync();this.inputWidth=imageInfo.size.width;this.inputHeight=imageInfo.size.height;// 创建目标 PixelMap（放大 1.5 倍）constopts:image.InitializationOptions={editable:true,pixelFormat:image.PixelMapFormat.RGBA_8888,size:{height:imageInfo.size.height*this.zoomRatio,// zoomRatio = 1.5width:imageInfo.size.width*this.zoomRatio}};this.pixelMapDst=image.createPixelMapSync(opts);}catch(e){hilog.error(0x0000,'ImageScaling',`getPixMap error${JSON.stringify(e)}`);}}注意：目标 PixelMap 是个空白画布，真正的像素写入是由 Native 层的detailEnhance完成的。不要以为createPixelMapSync(opts)就直接缩放好了。
第二步：用 Select 控件选择档位并触发增强
@Componentexportstruct ImageScalingComponent{@Stateindex:number=0;// 对应 NONE=0, LOW=1, MEDIUM=2, HIGH=3@StatepixelMapSrc:image.PixelMap|undefined=undefined;@StatepixelMapDst:image.PixelMap|undefined=undefined;@StateinputWidth:number=0;@StateinputHeight:number=0;privatezoomRatio:number=1.5;build(){Column(){// 展示原图Image($rawfile('ic_scaling.png')).width('100%').aspectRatio(1.25)// 选择增强档位Select([{value:'NONE'},{value:'LOW'},{value:'MEDIUM'},{value:'HIGH'}]).selected(this.index).onSelect((index:number,text:string)=>{this.index=index;// 每次选择都重新创建目标 PixelMapthis.pixelMapDst=undefined;this.getPixMap();// 调用 Native 增强接口// 第五个参数 index: 0=NONE, 1=LOW, 2=MEDIUM, 3=HIGHnativePix.detailEnhance(this.pixelMapSrc,this.pixelMapDst,this.inputWidth,this.inputHeight,this.index);this.isShow=true;})// 展示增强后的结果if(this.isShow){Image(this.pixelMapDst).width('100%').aspectRatio(1.25)}}}}第三步：Native 层接口声明（Index.d.ts）
// libentry.so 对应的 TypeScript 类型声明exportconstdetailEnhance:(src:image.PixelMap|undefined,dst:image.PixelMap|undefined,width:number,height:number,quality:number// 0:NONE 1:LOW 2:MEDIUM 3:HIGH)=>void;exportconstcreatePixelMap:(height:number,width:number)=>image.PixelMap;四档质量对比
| 档位 | 对应 index | 处理速度 | 细节保留 | 适用场景 |
|---|---|---|---|---|
| NONE | 0 | 最快 | 最差，放大后模糊明显 | 缩略图预览 |
| LOW | 1 | 快 | 略好于 NONE | 列表图片 |
| MEDIUM | 2 | 中等 | 均衡，细节较好 | 日常图片展示 |
| HIGH | 3 | 慢 | 最佳，细节锐利 | 打印、精细展示 |
踩坑总结
坑1：目标 PixelMap 必须每次重新创建
每次切换档位时，pixelMapDst = undefined然后重新getPixMap()是必要的。如果复用旧的 PixelMap，上次的像素数据会残留，Native 层写入可能出现异常。
坑2：pixelFormat 必须是 RGBA_8888
创建目标 PixelMap 时pixelFormat要指定RGBA_8888，不能省略。如果用UNKNOWN或者其他格式，Native 层写入会失败并返回错误码。
坑3：宽高顺序注意
detailEnhance接口的参数是(src, dst, inputWidth, inputHeight, quality)，但createPixelMap的参数顺序是(height, width)。这两个顺序不一样，写错了图会出现拉伸变形。
坑4：SELECT 选同一项不触发 onSelect
Select 组件如果选的是当前已选项，onSelect不会触发。如果需要强制刷新，要额外加一个按钮来重新处理。
@StorageLink 实现跨页面状态共享
项目里用了一个很精妙的设计：色彩空间转换页生成 HDR 图后，元数据生成页和 HDR 层转换页才会激活。这是用@StorageLink+AppStorage做的。
// 主页（Index.ets）@StorageLink('hdrPixelMap')hdrPixelMap:image.PixelMap|undefined=undefined;// 按钮动态启用/禁用，HDR 图存在才能点Button('元数据生成').enabled(this.hdrPixelMap!==undefined)// 色彩空间转换页生成 HDR 图后if(imageInfo.isHdr){this.hdrPixelMap=this.pixelMapSrc;// AppStorage 自动同步}不需要回调，不需要事件总线，状态一改，所有绑定了@StorageLink('hdrPixelMap')的组件都会自动更新。
写在最后
图片缩放不是把尺寸改了就完事，算法档位的选择对用户体验影响很大。MEDIUM 是大多数场景的最优解，HIGH 留给需要打印或精细展示的场景。另外要记住：Native 层接口是同步调用，HIGH 档处理大图时会卡住 UI 线程，生产环境记得放到 TaskPool 里跑。