# ImageKnifeC **Repository Path**: krri/image-knife-c ## Basic Information - **Project Name**: ImageKnifeC - **Description**: ImageKnifeC是一个OpenHarmony/HarmonyOS图片加载缓存库 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 10 - **Created**: 2024-11-25 - **Last Updated**: 2025-03-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ImageKnifeC 专门为OpenHarmony打造的一款图像加载缓存库，致力于更高效、更轻便、更简单 ## 简介 ImageKnifeC是一个OpenHarmony/HarmonyOS图片加载缓存库，是[ImageKnife](https://gitee.com/openharmony-tpc/ImageKnife)的C化实现，特点如下： * 支持自定义内存缓存策略，支持设置内存缓存的大小(默认LRU策略)。 * 支持磁盘二级缓存，对于下载图片会保存一份至磁盘当中。 * 支持自定义实现图片获取/网络下载 * 支持自定义解码 * 支持自定义文件缓存 * 支持监听网络下载回调进度 * 继承Image的能力，支持option传入border，设置边框，圆角 * 继承Image的能力，支持option传入objectFit设置图片缩放，包括objectFit为auto时根据图片自适应高度 * 并发请求数量，支持请求排队队列的优先级 * 支持生命周期已销毁的图片，不再发起请求 * 自定义缓存key生成策略 * 自定义http网络请求头 * 支持writeCacheStrategy控制缓存的存入策略(只存入内存或文件缓存，或不使用缓存) * 支持preLoad预加载图片 * 支持onlyRetrieveFromCache仅用缓存加载 待实现特性： * 默认解码支持图片降采样加载 * 支持使用一个或多个图片变换，如模糊，高亮等 * 支持通过设置transform缩放图片 相较ImageKnife ArkTs版本，主要体现在： * 提供ArkTs API和C API两种使用方式：既提供ArkTs组件方式给ArkTs原生应用使用，也提供Native组件的方式给RN等框架映射使用。 * 内置使用系统网络KIT CAPI下载和系统Image CAPI渲染，图片加载更快。 * (目前仅提供capi自定义拓展)支持通过拦截器的方式，自定义网络下载，解码，文件缓存，内存缓存。通过责任链-拦截器模式，图片加载任务可以同时应用多个自定义加载方式。 ## 下载安装 * ohpm har包安装 指定路径下（如：项目根路径/entry），输入如下命令安装ohpm har包依赖 ``` cd entry ohpm install @ohos/imageknifec ``` * 源码安装 需要安装submodule ``` git clone https://gitee.com/openharmony-tpc-incubate/image-knife-c git submodule update --init ``` ## 使用方式 如果需要用文件缓存，需要提前初始化文件缓存 ``` ImageKnife.getInstance().initFileCache(context, 256, 256 * 1024 * 1024) ``` ### arkts使用示例 #### 1.显示本地资源图片 ``` ImageKnifeComponent({ ImageKnifeOption: { loadSrc: $r("app.media.app_icon"), placeholderSrc: $r("app.media.loading"), errorSrc: $r("app.media.app_icon"), objectFit: ImageFit.Auto } }).width(100).height(100) ``` #### 2.显示本地context files下文件 ``` ImageKnifeComponent({ ImageKnifeOption: { loadSrc: this.localFile, placeholderSrc: $r("app.media.loading"), errorSrc: $r("app.media.app_icon"), objectFit: ImageFit.Auto } }).width(100).height(100) ``` #### 3.显示网络图片 ``` ImageKnifeComponent({ ImageKnifeOption: { loadSrc:"https://www.openharmony.cn/_nuxt/img/logo.dcf95b3.png", placeholderSrc: $r("app.media.loading"), errorSrc: $r("app.media.app_icon"), objectFit: ImageFit.Auto } }).width(100).height(100) ``` #### 4.监听网络下载进度 ``` ImageKnifeComponent({ ImageKnifeOption: { loadSrc:"https://www.openharmony.cn/_nuxt/img/logo.dcf95b3.png", progressListener:(progress:number)=>{console.info("ImageKinfe:: call back progress = " + progress)} } }).width(100).height(100) ``` #### 5.支持option传入border，设置边框，圆角 暂时实现了border width与radius的支持，设置的数据类型为number,**其他数据类型尚未实现暂不支持** **border color与style 尚未实现暂不支持** ``` ImageKnifeComponent({ ImageKnifeOption: { loadSrc: $r("app.media.rabbit"), border: {radius:50} } }).width(100).height(100) ``` #### 6.监听图片加载成功与失败 ``` ImageKnifeComponent({ ImageKnifeOption: { loadSrc: $r("app.media.rabbit"), onLoadListener:{ onLoadStart:(imageInfo)=>{ this.starTime = new Date().getTime() console.info("Load start: "); }, onLoadFailed: (err, imageInfo) => { console.error("Load Failed Reason: " + err + " cost " + (new Date().getTime() - this.starTime) + " milliseconds"); }, onLoadSuccess: (imageInfo) => { console.info("Load Successful: cost " + (new Date().getTime() - this.starTime) + " milliseconds"); return data; }, onLoadCancel(reason, imageInfo){ console.info(reason) } } } }).width(100).height(100) ``` #### 7.同步加载ImageKnifeComponent - syncLoad 设置是否同步加载图片，默认是异步加载。建议只将加载尺寸较小的Resource图片时将syncLoad设为true，因为耗时较短，在主线程上执行亦可。 ``` ImageKnifeComponent({ imageKnifeOption:{ loadSrc:$r("app.media.pngSample"), placeholderSrc:$r("app.media.loading") },syncLoad:true }) ``` #### 8.动图组件ImageKnifeAnimatorComponent 示例 ``` ImageKnifeAnimatorComponent({ imageKnifeOption: { loadSrc:"https://gd-hbimg.huaban.com/e0a25a7cab0d7c2431978726971d61720732728a315ae-57EskW_fw658", placeholderSrc:$r('app.media.loading'), errorSrc:$r('app.media.failed') },animatorOption:this.animatorOption }).width(300).height(300).backgroundColor(Color.Orange).margin({top:30}) ``` 可以通过`animatorOption`来控制动图的播放，暂停，播放次数，以及监听相应的事件。 ``` @State animatorOption: AnimatorOption = { state: AnimationStatus.Running, iterations: -1, onFinish: () => { LogUtil.info('ImageKnifeAnimatorComponent animatorOption onFinish') }, onStart: () => { LogUtil.info('ImageKnifeAnimatorComponent animatorOption onStart') }, onPause: () => { LogUtil.info('ImageKnifeAnimatorComponent animatorOption onPause') }, onCancel: () => { LogUtil.info('ImageKnifeAnimatorComponent animatorOption onCancel') }, onRepeat: () => { LogUtil.info('ImageKnifeAnimatorComponent animatorOption onRepeat') } } ``` #### 9.加载图片回调信息数据 示例 ``` ImageKnifeComponent({ ImageKnifeOption: = { loadSrc: $r('app.media.pngSample'), objectFit: ImageFit.Contain, onLoadListener: { onLoadStart: (imageInfo) => { let startCallBackData = JSON.stringify(imageInfo); }, onLoadFailed: (err, imageInfo) => { let failedBackData = err + ";" + JSON.stringify(imageInfo); }, onLoadSuccess: (imageInfo) => { let successBackData = JSON.stringify(imageInfo); }, onLoadCancel: (reason) => { let cancelBackData = reason + ";" + JSON.stringify(imageInfo); } }, border: { radius: 50 }, onComplete: (event) => { if (event && event.loadingStatus == 0) { let render_success = JSON.stringify(Date.now()) } } } }).width(100).height(100) ``` #### ArkTs 使用自定义的加载，解码，缓存 **注意：因为无法在c++子线程里执行ArkTs自定义下载，缓存，图形变化等方法，所以目前只能在c++侧进行自定义实现** C侧实现的自定义拦截器在添加至全局默认loader以后，ArkTs层默认应用，无需操作。 如果指定图片使用特定的加载方法（非设置的全局默认loader），则可以在C侧创建的loader并注册后，ArkTs层进行选择使用。 ``` ImageKnifeComponent({ imageKnifeOption: { loadSrc: "https://www.openharmony.cn/_nuxt/img/logo.dcf95b3.png", imageKnifeLoader: "myCustomLoader" }, }).width('100%').height(200) ``` 通过imageKnifeLoader成员选择特定loader，该loader需要在C侧创建完成自定义并以对应的名称进行注册。 #### 复用场景 在aboutToRecycle生命周期清空组件内容；通过watch监听触发图片的加载。 ### C++使用方式 ImageKnifeC **已经**在对应包的napi init函数中对ImageKnife进行了默认的初始化，如需自定义加载等过程需覆盖默认初始化中设置的loader 默认loader包含了通过多种拦截器实现，提供图片加载，解码，缓存等能力。 #### c++简单使用示例（使用默认的loader以及配置） 引入`imageKnife.h`头文件 ```cpp //1.创建ImageKnifeOption auto imageKnifeOption = std::make_shared(); //2.设置图片加载选项参数, 只有主图源loadSrc必填，其他为可选参数 imageKnifeOption->loadSrc.SetString("https://www.openharmony.cn/_nuxt/img/logo.dcf95b3.png"); imageKnifeOption->placeholderSrc.SetString("占位图"); imageKnifeOption->errorSrc.SetString("错误图"); imageKnifeOption->onLoadListener = std::make_shared(); imageKnifeOption->onLoadListener->onLoadStart = [](ImageInfo info) {}; imageKnifeOption->onLoadListener->onLoadFailed = [](std::string err, ImageInfo info) {}; imageKnifeOption->objectFit = ARKUI_OBJECT_FIT_COVER; //3.通过Option创建图片组件，开始图片加载 auto imageKnifeNode = std::make_shared(imageKnifeOption); //4.获取原始ArkUI_NodeHandle，C API图片节点挂树布局需要自己操作handle ArkUI_NodeHandle handle = imageKnifeNode->GetHandle(); ``` ### 通过拦截器自定义加载过程（ArkTs API适用） #### 拦截器用法 * 支持下载，内存缓存，文件缓存，解码4种拦截器扩展默认实现 * 每个拦截器需要继承对应的基类实现对应的虚函数，Resolve负责拦截器的功能实现，Cancel负责取消Resolve中的耗时动作。 * Resolve返回true则代表执行成功，责任链终止，进入下一个流程。返回false则代表执行失败，交由责任链上后一个拦截器。 * 拦截器需添加至ImageLoader中，默认全局应用。ImageKnifeOption中也可以使用指定的loader。 #### 拦截器在责任链之间流转数据 * 拦截器通过`ImageKnifeTask`来传递参数和执行结构，其中`product`成员为拦截器生成的产品，执行结果需写回至`product`的成员上来传递至下一流程。 * `Product.CacheTaskType` 成员表示当前缓存拦截器的任务类型，其他责任链类型为NONE * 通过`GetImageSource()`成员为当前加载任务对应的图片数据源，可能是网络图片url 或本地文件路径，Resource资源图等。 ```cpp class ImageKnifeTask { public: struct Product{ // 原始图片buffer, std::shared_ptr imageBuffer = nullptr; // 原始图片长度 uint32_t imageLength = 0; // 解码后或图形变换后的pixelmap图片数据，可能由单帧或多帧（动图），如果是多帧则还包含每帧的时间信息 std::shared_ptr imageData = nullptr; // 图片内存缓存的数据对象，用于组件直接渲染显示。该对象在加载成功后自动生成，内存缓存拦截器只能缓存读取其智能指针 std::shared_ptr imageDataCache = nullptr; } // 内存缓存/文件缓存子任务描述对象，非缓存责任链无需处理 struct CacheTask { // 当前图片加载对应的缓存key, 用于内存/文件缓存拦截器，可作为文件缓存的文件名 std::string cacheKey; // 标识内存缓存/文件缓存拦截器的任务类型，非缓存责任链该成员为NONE CacheTaskType type = CacheTaskType::NONE; }; // 拦截器产品 Product product; // 缓存子任务描述对象 CacheTask cacheTask; // 获取图片请求类型，标识当前任务加载的是主图，占位图，还是错误图 virtual ImageRequestType GetImageRequestType() const = 0; // 获取加载任务的图片源ImageSource, 任务类型为加载主图，返回loadSrc。加载占位图返回placeholderSrc。加载错误图返回errorSrc virtual ImageSource *GetImageSource() const = 0; // 获取当前任务对应的图片请求ImageKnifeRequest对象 virtual std::shared_ptr GetImageKnifeRequest() const = 0; }; ``` #### 拦截器自定义数据 * `ImageKnifeOption`中预留了`void* customData`成员，用户可以将自定义数据类型赋给改成员，并在拦截器中通过`ImageKnifeTask`的`GetImageKnifeRequest()->GetImageKnifeOption()->customData`取得。 * 通过设置`ImageKnifeOption`中的`std::function onFinalize`成员来完成了对`customData`的析构以及其他操作。 该函数指针将保证在整个图片请求（包含主图，占位图，错误图）结束后触发，即在请求失败，成功，取消结束后回调。 #### 自定义拦截器示例 ArkTs API 自定义加载过程也是通过C++继承拦截器基类实现,并添加至默认loader或指定loader上。ArkTs API 调用时，可以通过loader名称选择对应loader或者使用默认loader ##### c++自定义图片下载 ```cpp class MyDownloadInterceptor: public ImageKnifeC::LoadInterceptor{ public: bool Resolve(std::shared_ptr task) override { // 自实现网络请求，数据通过task->product传递 // 图片源信息由task->GetImageSource()获取 std::string url; if (task->GetImageSource()->GetString(url)) { // 下载的图片数据写入至product.imageBuffer， 交由一个责任链解码 // 对应的buffer长度需写入product.imageLength return loadImageFromUrl(url, task); // 如执行成功，下载责任链结束 } // 执行失败或不支持，将执行加载责任链的下一个拦截器 return false; } }; ``` ##### c++自定义解码图片 ```cpp class MyDecodeInterceptor: public ImageKnifeC::DecodeInterceptor{ public: bool Resolve(std::shared_ptr task) override { //自定义解码实现 //从task->product.imageBuffer 中获取待解码的图片数据buffer //解码后的结果写入task->product.imageData。 解码成OH_PixelmapNative *对象并用其构造ImageData return true;// 执行成功，责任链结束 return false; // 执行失败或不支持，将执行责任链的下一个拦截器 } }; ``` ##### c++自定义内存缓存 ```cpp class MyMemoryInterceptor: public ImageKnifeC::MemoryCacheInterceptor{ public: bool Resolve(std::shared_ptr task) override { // 自定义缓存实现 内存缓存读取对象: task->product.imageDataCache // 使用task->cacheTask.cacheKey 来记录缓存数据 if (task->cacheTask.type == ImageKnifeC::CacheTaskType::READ) { // 自定义读缓存实现 } else if (task->cacheTask.type == ImageKnifeC::CacheTaskType::WRITE) { // 自定义写缓存实现 } return true;// 执行成功，责任链结束 return false; // 执行失败或不支持，将执行责任链的下一个拦截器 } }; ``` ##### c++自定义文件缓存 ```cpp class MyFileInterceptor: public ImageKnifeC::FileCacheInterceptor{ public: bool Resolve(std::shared_ptr task) override { // 自定义文件缓存实现 文件缓存数据源操作对象为task->product.imageBuffer // 使用task->cacheTask.cacheKey 来记录缓存数据，可以直接用作文件缓存的文件名 if (task->cacheTask.type == ImageKnifeC::CacheTaskType::READ) { // 自定义读缓存实现 } else if (task->cacheTask.type == ImageKnifeC::CacheTaskType::WRITE) { // 自定义写缓存实现 } return true;// 执行成功，责任链结束 return false; // 执行失败或不支持，将执行责任链的下一个拦截器 } }; ``` #### 应用自定义拦截器 **自定义加载等过程需覆盖默认初始化中设置的loader** 拦截器使用需要其添加至对应的责任链中。图片加载的责任链为：内存缓存责任链，文件缓存责任链，加载责任链，解码责任链。 其中，默认的网络下载拦截器，本地资源加载拦截器都在加载责任上 ```cpp // 创建默认的loader，内部包含默认的拦截器实现。也可以选择创建空的loader auto imageLoader = ImageKnifeC::ImageKnifeLoader::CreateDefaultImageLoader(); // 将创建的loader设置为全局默认的loader来覆盖默认配置，将全局默认应用 ImageKnifeC::ImageKnife::GetInstance().SetDefaultImageKnifeLoader(imageLoader); // 将前面例子中自定义的拦截器添加至对应的责任链中，每条责任链可以添加任意多个拦截器，默认添加至责任链的开始位置 imageLoader->AddMemoryCacheInterceptor(std::make_shared()); imageLoader->AddFileCacheInterceptor(std::make_shared()); imageLoader->AddLoadInterceptor(std::make_shared()); imageLoader->AddDecodeInterceptor(std::make_shared()); ``` #### 使用非全局默认的图片loader 允许定义多个loader实例，每个图片可指定不同loader，通过`ImageKnifeOption`指定使用特定loader，来实现不同图片使用不同方式加载 ```cpp auto loader1 = ImageKnifeC::ImageKnifeLoader::CreateDefaultImageLoader(); auto loader2 = ImageKnifeC::ImageKnifeLoader::CreateDefaultImageLoader(); // 将创建的loader设置为全局默认的loader来覆盖默认配置，将全局默认应用 ImageKnifeC::ImageKnife::GetInstance().SetDefaultImageKnifeLoader(loader1); auto option = std::make_shared(); option->loadSrc.SetString("https://www.openharmony.cn/_nuxt/img/logo.dcf95b3.png"); // ImageKnifeOption 指定使用特定的loader来加载图片 option->imageKnifeLoader = loader2; auto imageNode = std::make_shared(option); // 注册loader，使得ArkTs侧的ImageKnifeOption能够通过字符串名称选择特定loader ImageKnifeC::ImageKnife::GetInstance().RegisterLoader("loader2", loader2); ``` ArkTs侧使用非默认的图片loader, 需要按上方示例在C侧创建自定义loader并注册 ``` ImageKnifeComponent({ imageKnifeOption: { loadSrc: "https://www.openharmony.cn/_nuxt/img/logo.dcf95b3.png", imageKnifeLoader: "loader2" }, }).width('100%').height(200) ``` ## ArkTs接口说明 ### ImageKnife组件 | 组件名称 | 入参内容 | 功能简介 | |-----------------------------|---------------------------------|--------| | ImageKnifeComponent | ImageKnifeOption | 图片显示组件 | | ImageKnifeAnimatorComponent | ImageKnifeOption、AnimatorOption | 动图控制组件 | ### AnimatorOption成员列表 | 成员名称 | 类型 | 功能简介 | |------------|-----------------|----------| | state | AnimationStatus | 播放状态（可选） | | iterations | number | 播放次数（可选） | | reverse | boolean | 播放顺序（可选） | | onStart | ()=>void | 动画开始播放时触发（可选） | | onFinish | ()=>void | 动画播放完成时或者停止播放时触发（可选） | | onPause | ()=>void | 动画暂停播放时触发（可选） | | onCancel | ()=>void | 动画返回最初状态时触发（可选） | | onRepeat | ()=>void | 动画重复播放时触发（可选） | ### ImageKnifeOption成员列表 | 成员名称 | 类型 | 功能简介 | |-----------------------|-----------------------------------------|-----------------| | loadSrc | string \| PixelMap \| Resource | 主图展示 | | placeholderSrc | string \| PixelMap \| Resource | 占位图图展示（可选） | | errorSrc | string \| PixelMap \| Resource | 错误图展示（可选） | | objectFit | ImageFit | 主图填充效果（可选） | | placeholderObjectFit | ImageFit | 占位图填充效果（可选） | | errorObjectFit | ImageFit | 错误图填充效果（可选） | | writeCacheStrategy | CacheStrategyType | 写入缓存策略(可选) | | onlyRetrieveFromCache | boolean | 是否跳过网络和本地请求（可选） | | border | BorderOptions | 边框圆角（可选）（暂部分实现） | | priority | Priority | 加载优先级（可选） | | context | common.UIAbilityContext | 上下文（可选） | | progressListener | (progress: number)=>void | 下载回调进度（可选） | | signature | String | 自定义缓存关键字（可选） | | headerOption | Array | 设置请求头（可选） | | transformation | PixelMapTransformation | 图片变换（可选）（待实现） | | drawingColorFilter | ColorFilter \| drawing.ColorFilter | 图片变换（可选） （待实现） | | onComplete | (event:EventImage \| undefined) => voi | 图片加载完成回调（可选） | | onLoadListener | OnLoadCallBack | 监听图片加载成功与失败 | | imageKnifeLoader | string | 监听图片加载成功与失败 | ### ImageInfo成员列表 | 成员名称 | 类型 | 功能简介 | |-------------|--------|-------------| | requestId | string | 图片加载请求的ID标识 | | imageWidth | number | 原始图片宽度 | | imageHeight | number | 原始图片高度 | | bufSize | number | 原始图片字节数 | | type | ImageFormat | 原始图片格式 | | httpCode | number | 网络请求状态码 | | frameCount | number | 图片帧数 | | decodeImages | Array | 解码后的图片信息 | | timeInfo | TimeInfo | 加载图片的各个时间点 | | errorInfo | ErrorInfo | 加载图片的错误信息 | ### ImageFormat枚举 | 枚举名称 | 值 | |------|---| |UNKNOWN| 0 | |JPG| 1 | |PNG| 2 | |WEBP| 3 | |BMP| 4 | |GIF| 5 | |SVG| 6 | |TIFF| 7 | |HEIC| 8 | |ICO| 9 | ### DecodeImageInfo成员列表 | 成员名称 | 类型 | 功能简介 | |-------------|--------|----------| | contentWidth | number | 解码后的图片宽度 | | contentHeight | number | 解码后的图片高度 | ### ErrorInfo成员列表 | 成员名称 | 类型 | 功能简介 | |-------------|--------|----------| | phase | string | 图片加载阶段信息 | | code | number | 错误码 | ### TimeInfo | 成员名称 | 类型 | 功能简介 | |-------------|--------|-----------------------| | executeTime | number | 请求创建完成，开始处理的时间 | | requestStartTime | number | 请求开始加载的时间 | | requestEndTime | number | 请求结束时间 | | requestCancelTime | number | 请求取消时间 | | memoryCheckStartTime | number | 内存缓存责任链读缓存任务开始时间 | | memoryCheckEndTime | number | 内存缓存责任链读缓存任务结束时间 | | diskCheckStartTime | number | 文件缓存责任链读缓存任务开始时间 | | diskCheckEndTime | number | 文件缓存责任链读缓存任务结束时间 | | loadImageStartTime | number | 图片加载责任链开始时间 | | loadImageEndTime | number | 图片加载责任链结束时间 | | decodeStartTime | number | 图片解码责任链开始时间 | | decodeEndTime | number | 图片解码责任链结束时间 | ### CacheStrategy枚举 | 枚举名称 | 值 | 说明 | |------|---|-----------| |DEFAULT| 0 | 使用内存和文件缓存 | |MEMORY| 1 | 只使用内存缓存 | |FILE| 2 | 只使用文件缓存 | |NONE| 3 | 不使用缓存 | ### ImageKnife接口 | 接口名称 | 入参内容 | 功能简介 | |----------------------|-----------------------------------------------------------------------------------------------------|--------------------------------------| | setMaxRequests | concurrency: number | 设置请求最大的并发数量 | | setCacheLimit | strategy: CacheStrategy, maxSize: number, maxUsage: number | 设置磁盘或者内存缓存的使用上限 | | initFileCache | context: Context, size: number, memory: number | 初始化文件缓存数量和大小 | | isFileCacheInit | | 判断文件缓存初始化是否完成 | | getCacheLimitSize | cacheStrategy?: CacheStrategy | 获取磁盘或者内存缓存上限 | | getCurrentCacheNum | cacheStrategy?: CacheStrategy | 获取磁盘或者内存缓存当前缓存的图片数量 | | getCurrentCacheSize | cacheStrategy?: CacheStrategy | 获取磁盘或者内存已用空间大小，获取内存使用量功能在相关系统接口上线后更新 | | removeMemoryCache | url: string \| ImageKnifeOption | 清理指定内存缓存 | | removeAllMemoryCache | | 清理所有磁盘缓存 | | removeMemoryCache | | 清理所有内存缓存 | | removeAllFileCache | url: string \| ImageKnifeOption | 清理指定磁盘缓存 | | preload | loadSrc: string \| ImageKnifeOption | 图片预加载 | | cancel | request: ImageKnifeRequest | 取消图片预加载 | | reaload | requestId: string | 重新加载请求 | | preLoadCache | loadSrc: string I ImageKnifeOption | 预加载并返回文件缓存路径（待实现） | | getCacheImage | loadSrc: string, cacheType: CacheStrategy = CacheStrategy.Default, signature?: string) | 从内存或文件缓存中获取资源 （待实现） | | addHeader | key: string, value: Object | 全局添加http请求头 | | setHeaderOptions | Array | 全局设置http请求头 | | deleteHeader | key: string | 全局删除http请求头 | | putCacheImage | url: string, pixelMap: PixelMap, cacheType: CacheStrategy = CacheStrategy.Default, signature?: string | 写入内存磁盘缓存 (待实现) | ## 与ImageKnife3.x特性对比 #### ImageKnifeOption | 属性 | ImageKnife3.x(js api) | ImageKnifeC(js api) | ImageKnifeC(c api) | |-----------|---------------------------------------------------|--------------------------------|-------------| | 主图 | loadSrc:string, PixelMap, Resource | 一致 | | | 占位图 | placeholderSrc?: string,PixelMap,Resource | 一致 | | | 错误图 | errorholderSrc?: string,PixelMap,Resource | errorSrc?: string,PixelMap,Resource | | | http请求头 | headerOption?: Array | 一致(待实现) | | | 自定义关键字 | signature?: string | 一致 | | | 主图缩放效果 | objectFit?: ImageFit | 一致 | | | 占位图缩放效果 | placeholderObjectFit?: ImageFit | 一致 | | | 错误图缩放效果 | errorholderObjectFit?: ImageFit | errorObjectFit?: ImageFit | | | 自定义下载方法 | customGetImage:function | 不一致，成员移除 | 拦截器实现 | | 圆角边框 | border?: BorderOptions | 一致（暂实现了number类型的radius与border width） | | | 写缓存策略 | writeCacheStrategy?: CacheStrategy | 一致 | | | 仅使用缓存加载 | onlyRetrieveFromCache?: boolean | 一致 | | | 请求优先级 | priority?: taskpool.Priority | priority?: Priority | | | 页面上下文 | context?: common.UIAbilityContext | 一致 | 使用C API 无效 | | 下载进度监听 | progressListener?: (progress: number) => void | 一致，但有跨线程延迟 | | | 图形变化 | transformation?: PixelMapTransformation | 不一致(待C侧实现) | | | 请求回调 | onLoadListener?: OnLoadCallBack \| undefined | 不一致，内部回调函数使用ImageInfo入参 | | | 渲染完成回调 | onComplete?:(event:EventImage,undefined) => void | 一致 | | | 颜色修改 | drawingColorFilter?: ColorFilter,drawing.ColorFilter | 一致(待实现) | | | 降采样策略 | downsampleOf?: DownsampleStrategy | 一致(待实现) | | | http ca证书 | caPath?: string | 一致(待实现) | | #### ImageKnife全局方法 | 方法 | ImageKnife3.x(js api) | ImageKnifeC(js api) | ImageKnifeC(c api) | | --------------------- |----------------------------------------------------------------------------------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------| | 初始化文件缓存 | InitFileCache(context: Context, size: number = 256, memory: number = 256 * 1024 * 1024,path?: string) | 一致 | InitFileCacheAsync(std::string cachePath, size_t size, size_t memory, std::string path) | | 判断文件缓存是否已完成初始化 | isFileCacheInit(): boolean | 一致 | bool IsFileCacheInit() | | 重新加载 | reload(request: ImageKnifeRequest) | reload(requestId: string) | void reload(std::string requestId) | | 全局添加单个请求头header | addHeader(key: string, value: Object) | 一致 | 待实现C接口 | | 全局设置请求头header | setHeaderOptions(options) | 一致 | 待实现C接口 | | 删除单个请求头header | deleteHeader(key: string) | 一致 | 待实现C接口 | | 设置自定义的内存缓存 | initMemoryCache(newMemoryCache: IMemoryCache) | 不一致(拦截器实现) | | | 预加载 | preload(loadSrc:string \| ImageKnifeOption) | 一致 | Preload(std::shared_ptr imageKnifeOption) | | 取消图片请求 | Cancel(request:ImageKnifeRequest) | 一致 | Cancel(std::shared_ptr request) | | 预加载图片到文件缓存,返回文件路径 | preLoadCache(loadSrc: string \| ImageKnifeOption) | 一致（待实现） | | | 从内存或文件缓存中获取图片数据 | getCacheImage(loadSrc: string,cacheType: CacheStrategy = CacheStrategy.Default, signature?: string) | 一致(待确认) | | | 预加载缓存（用于外部已获取pixelmap，需要加入imageknife缓存的场景） | PutCacheImage(url: string, pixelMap: PixelMap, cacheType: CacheStrategy = CacheStrategy.Default, signature?: string) | 一致(待确认) | | | 清除所有文件缓存 | removeAllFileCache() | 一致 | RemoveAllFileAsync(void) | | 清除指定文件缓存 | removeFileCache(url: string \| ImageKnifeOption) | 一致 | RemoveFileAsync(std::string &url)，RemoveFileAsync(std::shared_ptr option) | | 清除所有内存缓存 | removeAllMemoryCache() | 一致 | RemoveAllMemoryCache() | | 清除指定内存缓存 | removeMemoryCache(url: string \| ImageKnifeOption) | 一致 | RemoveMemoryCache(std::string url)，RemoveMemoryCache(std::shared_ptr imageKnifeOption) | | 设置请求并发数量 | setMaxRequests(concurrency: number) | 一致 | SetMaxRequests(int concurrency) | | 获取缓存限制的大小 | getCacheLimitSize(cacheType?: CacheStrategy) | 一致 | GetCacheLimitSize(CacheStrategy cacheStrategy) | | 获取缓存限制的数量 | getCurrentCacheNum(cacheType: CacheStrategy) | 一致 | GetCurrentCacheNum(CacheStrategy cacheStrategy) | | 获取当前缓存大小 | getCurrentCacheSize(cacheType: CacheStrategy) | 一致 | GetCurrentCacheSize(CacheStrategy cacheStrategy) | | 自定义缓存key生成方法 | SetEngineKeyImpl(impl: IEngineKey) | 不一致 | SetCacheKeyGenerator(CacheKeyGenerator *keyPtr) | | 全局设置自定义下载 | setCustomGetImage(...) | 不一致 | 拦截器实现 | | 全局获取自定义下载 | getCustomGetImage() | 不一致 | 拦截器实现 | #### 其它属性 | 属性 | ImageKnife3.x(js api) | ImageKnifeC(js api) |ImageKnifeC(c api) | | --------------------- | ----------------------------------------------------- | ------------------------------ |------------------------------ | | 同步加载 | syncLoad: boolean | 一致 | | | 动图控制及回调 | animatorOption: AnimatorOption | 一致 | | | 放大缩小等组件缩放 | Transform(matrix:object) | 一致(待实现) | | | 组件自适应图片宽高 | ImageFit.Auto | 一致 | | ## Benchmark 待测试比较imageknife3.x,imageknifeC,系统image,安卓fresco/glide 加载图片速度和白块率。 ## 开源协议 本项目基于 [Apache License 2.0](https://gitee.com/openharmony-tpc/ImageKnife/blob/master/LICENSE) ，请自由的享受和参与开源。