鸿蒙系统的 Image 组件支持加载网络和本地图片，但四个短板在业务复杂度上升后依次暴露：没有二级缓存控制，冷启动重复拉取网络图片；没有占位图和错误图的切换机制，列表滑动时白屏闪烁；图片变换（模糊、裁剪等）需要手动操作 PixelMap；组件销毁后请求仍在飞，复用场景旧图残留。ImageKnifePro 针对这些问题，把整个加载引擎下沉到 C++ 层，用拦截器责任链驱动缓存、加载、解码、渲染的全流程。

一、拦截器链架构——四层责任链

ImageKnifePro 的架构核心是四条拦截器责任链。Interceptor 是公共基类，定义了 Resolve 纯虚函数和 Process 链式调用逻辑，每个拦截器只做一件事，做不到就传给链上的下一个节点。

class Interceptor {
public:
    std::string name;
    virtual bool Resolve(std::shared_ptr<ImageKnifeTask> task) = 0;
    virtual void Cancel(std::shared_ptr<ImageKnifeTask> task);
    virtual bool Process(std::shared_ptr<ImageKnifeTask> task,
                 std::function<bool(std::shared_ptr<ImageKnifeTask>)> resolveCallback = nullptr);
    virtual ~Interceptor() = default;
protected:
    std::shared_ptr<Interceptor> next_ = nullptr;
};

四个子类分别对应四个阶段：MemoryCacheInterceptor 管内存缓存读写，FileCacheInterceptor 管文件缓存读写，LoadInterceptor 管网络下载和本地资源加载，DecodeInterceptor 管解码。每个子类都把 Process 标记为 final，禁止下游再覆写链式调用逻辑——自定义拦截器只需要实现 Resolve，链的驱动由框架保证。

出于类型安全的考虑，每个子类还各自提供了一个 SetNext 方法，参数类型和自身一致，防止把 LoadInterceptor 误挂到 DecodeInterceptor 的链上。

ImageKnifeLoaderInternal 持有四条链的 head 和 tail 指针（共八个），通过 AddXxxInterceptor 方法可以在链头或链尾插入自定义拦截器。默认链上的五个拦截器分别是 MemoryCacheInterceptorDefault、FileCacheInterceptorDefault、DownloadInterceptorDefault、ResourceInterceptorDefault 和 DecodeInterceptorDefault，AVIF 解码器 DecodeInterceptorAvif 会在运行时根据设备能力条件添加。

二、一次请求的完整路径

以一次网络图片首次加载为例，请求穿越四层拦截器的路径如下。

ImageKnifeLoaderInternal 是流水线的调度中枢，它按顺序调用六个阶段方法：LoadFromMemory -> LoadFromFile -> DownloadImage -> DecodeImage -> WriteCacheToFile -> WriteCacheToMemory。每个方法内部设好 cacheTask.type（READ 或 WRITE）和 cacheTask.cacheKey，然后拿对应链的 head 调 Process。

bool ImageKnifeLoaderInternal::LoadFromMemory(std::shared_ptr<ImageKnifeTaskInternal> task)
{
    task->cacheTask.type = CacheTaskType::READ;
    task->cacheTask.cacheKey = task->memoryKey;
    return memoryInterceptorHead_->Process(task);
}

第一步，LoadFromMemory 调 memoryInterceptorHead_->Process(task)。MemoryCacheInterceptorDefault 用 memoryKey 去 MemoryCache 单例查找，首次加载必然未命中，返回 false。第二步，LoadFromFile 调 fileInterceptorHead_->Process(task)。FileCacheInterceptorDefault 在磁盘上没找到缓存文件，返回 false。第三步，DownloadImage 调 loadInterceptorHead_->Process(task)。DownloadInterceptorDefault 识别到 HTTP URL，通过 RCP 发起异步请求，成功后调 Detach(task) 标记任务分离，当前工作线程释放回线程池。

RCP 异步回调到达后，ResponseCallback 提取 HTTP 响应填充 task->product.imageBuffer，然后通过 OnComplete 将 task 推回 FFRT 的 taskQueue_，进入解码阶段。第四步，DecodeImage 调 decodeInterceptorHead_->Process(task)，解码器根据文件头魔数识别格式，创建 PixelMap。第五步和第六步，依次调 WriteCacheToFile、WriteCacheToMemory 回写缓存。最终 PixelMap 随 task 返回给 UI 组件。

六个方法都被 try-catch 包裹，异常时调 task->FatalError 标记致命错误。调度中枢不关心某一层内部挂了几个拦截器，它只和 head 指针交互，链内部的传递由基类 Process 的递归调用完成。

三、组件层和加载层的配合

ImageKnifePro 的 ArkTS 侧 ImageKnifeComponent 大幅简化，build() 方法只有一行：

build() {
  ContentSlot(this.rootSlot)
}

rootSlot 是一个 NodeContent 对象。在 aboutToAppear 阶段，组件通过 nativeNode.createNativeRoot 将这个挂载点连同 imageKnifeOption 传给 C++ 层的 libimageknifepro.so。C++ 层自己通过 ArkUI 的 C API 创建 Image 节点、管理属性更新和图片送显。ArkTS 侧不再持有 @State pixelMap 这样的状态变量，也不参与渲染决策。

把渲染下沉到 Native 层的好处是：shared_ptr 和 RAII 管理 PixelMap 生命周期，不存在 ArkTS 层 emitter 事件注册遗忘导致的内存泄漏；Native Image 节点绕过了声明式状态管理的开销，属性更新直接走 C API。

生命周期管理也更直接。aboutToDisappear 调用 nativeNode.destroyNativeRoot(this.componentId)，C++ 层的 CancelRequest 方法将请求标记为 DESTROY 后，遍历所有请求类型（主图、占位图、缩略图、错误图），对每个类型调用 CancelInterceptor。这个方法通过 task->GetCurrentInterceptor() 拿到当前正在执行的拦截器指针，调用其 Cancel 虚函数。下载拦截器的 Cancel 实现可以通过 HMS_Rcp_CancelRequest() 主动取消正在进行的 HTTP 请求，粒度比 ArkTS 的 taskpool.cancel 更细。

aboutToDisappear(): void {
    nativeNode.destroyNativeRoot(this.componentId);
}

aboutToRecycle() {
    nativeNode.clearNativeRoot(this.componentId);
}

aboutToRecycle 调用 nativeNode.clearNativeRoot，只清除显示内容不销毁节点本身，为列表复用做准备。这个区分很重要——销毁代价远大于清除，列表快速滚动时复用组件的频率很高，每次都走销毁-重建成本不可接受。

ArkTS 侧还有几个扩展属性通过各自的 @Watch 回调通知 C++ 层更新：customId 用于关联预创建的组件——可以在页面布局之前通过 preCreateImageKnifeComponent 提前创建 Image 节点并开始加载图片，等组件上树时直接关联已经加载好的节点，减少首屏白屏时间。contentTransition 控制图片切换时的过渡动画。imageDraggable 控制图片是否可拖拽。watchImageKnifeOption 是最核心的回调，当外部修改 imageKnifeOption 时触发 nativeNode.updateNativeRoot，把新的参数传给 C++ 层重新发起加载。

四、Process 的链式驱动

Process 是整条责任链的心脏，所有拦截器共用同一套驱动逻辑。

bool Interceptor::Process(std::shared_ptr<ImageKnifeTask> task,
                          std::function<bool(std::shared_ptr<ImageKnifeTask>)> resolveCallback)
{
    auto taskInternal = std::dynamic_pointer_cast<ImageKnifeTaskInternal>(task);
    if (taskInternal->IsFatalErrorHappened() || request->IsDestroy()) {
        return false;
    }
    taskInternal->SetInterceptor(this);

    bool result = ExecuteResolveFunction(this, taskInternal, resolveFunction);
    if (taskInternal->IsDetached() && IsLoadInterceptor(this)) {
        return true;
    }
    if (result) {
        taskInternal->ClearInterceptorPtr();
        return true;          // 短路：当前拦截器搞定了
    } else if (next_ != nullptr) {
        return next_->Process(task);  // 传递：交给下一个
    } else {
        taskInternal->ClearInterceptorPtr();
        return false;         // 链尾：没人能处理
    }
}

前置检查先看致命错误和销毁状态，任何一个条件成立直接返回 false，不让半成品 task 继续流转。SetInterceptor(this) 把当前拦截器的裸指针记录在 task 上，这样后续的 Cancel 操作能找到正在执行的拦截器。

ExecuteResolveFunction 是一个包装函数，负责写 HiTrace 的异步追踪起止标记和日志输出。每个默认拦截器在构造函数里给自己取名（如 "Default DownloadInterceptor"），ExecuteResolveFunction 用 name 拼接缓存操作类型（Read/Write）作为 trace 名称，调试时能在 HiTrace 面板上看到请求依次走过了哪些拦截器、在每个拦截器上花了多少时间。

Detach 检测是专门为 LoadInterceptor 设计的分支。网络下载发起异步请求后调 Detach(task) 标记分离，Process 检测到 IsDetached() 后直接返回 true，不再走后续的 next_ 传递。分离后的任务由 RCP 回调线程通过 OnComplete 重新接管，整个设计让网络 I/O 不占用线程池并发位。

五、扩展点的设计

四条链都支持在头部或尾部插入自定义实现。ImageKnifeLoader 为每条链提供一个 Add 方法，Position 枚举只有 START 和 END 两个值。

void ImageKnifeLoaderInternal::AddLoadInterceptor(
    std::shared_ptr<LoadInterceptor> interceptor, Position position)
{
    if (loadInterceptorHead_ == nullptr) {
        loadInterceptorHead_ = loadInterceptorTail_ = interceptor;
        return;
    }
    if (position == Position::START) {
        interceptor->SetNext(loadInterceptorHead_);
        loadInterceptorHead_ = interceptor;
    } else {
        loadInterceptorTail_->SetNext(interceptor);
        loadInterceptorTail_ = interceptor;
    }
}

格式支持的增减就是这个机制的实际案例。DecodeInterceptorAvif 是 AVIF 格式的专用解码器，只在设备支持 libavif 时才挂到解码链尾部。如果设备不支持，IsAvifEnable() 返回 false，拦截器不会被添加，遇到 AVIF 图片时默认解码器返回 false，链尾没有下一个节点，上层报解码失败。整个过程不碰任何现有代码。

RegisterLoader 则提供了更粗粒度的定制。注册进 loaderMap_ 的是一个完整的 ImageKnifeLoader 对象，包含自己的四条拦截器链。ArkTS 层通过字符串指定 loader 名称，不同业务场景可以用不同的拦截器组合——一个走 CDN 下载用 WebP 解码，另一个走内网专线用自研格式，互不干扰。

CreateEmptyImageLoader 创建四条链全空的 loader，由开发者自行填充。CreateDefaultImageLoader 则预装全套默认拦截器，开箱即用的同时保留了每条链上的插入能力。出于灵活性和开箱即用之间的平衡，大多数应用使用默认 loader 加上少量自定义插入即可。

以上就是本篇内容的所有了~有什么问题欢迎在评论区提出

---

项目地址：ImageKnifePro