ImageKnife

專門為OpenHarmony打造的一款圖像加載緩存庫，致力于更高效、更輕便、更簡單。

簡介

OpenHarmony的自研版本：

• 支持內存緩存，使用LRUCache算法，對圖片數據進行內存緩存。
• 支持磁盤緩存，對于下載圖片會保存一份至磁盤當中。
• 支持進行圖片變換: 支持圖像像素源圖片變換效果。
• 支持用戶配置參數使用:( 例如：配置是否開啟一級內存緩存，配置磁盤緩存策略，配置僅使用緩存加載數據，配置圖片變換效果，配置占位圖，配置加載失敗占位圖等)。
• 推薦使用ImageKnifeComponent組件配合ImageKnifeOption參數來實現功能。
• 支持用戶自定義配置實現能力參考ImageKnifeComponent組件中對于入參ImageKnifeOption的處理。

下載安裝

ohpm install @ohos/imageknife

使用說明

1.依賴配置

在entrysrcmainetsentryabilityEntryAbility.ts中做如下配置初始化全局ImageKnife實例：

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import { ImageKnife } from '@ohos/imageknife'

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) = > {
    });
    // 初始化全局ImageKnife 
    ImageKnife.with(this.context);
  	// 后續訪問ImageKnife請通過:ImageKnifeGlobal.getInstance().getImageKnife()方式
  }
}

2.加載普通圖片

接下來我們來寫個簡單實例看看:

import { ImageKnifeComponent, ImageKnifeOption } from '@ohos/imageknife'

@Entry
@Component
struct Index {
  @State message: string = 'Hello World'
  @State option: ImageKnifeOption = {
    loadSrc: $r('app.media.icon')
  }

  build() {
      Row() {
        Column() {
          Text(this.message)
            .fontSize(50)
            .fontWeight(FontWeight.Bold)
          ImageKnifeComponent({ imageKnifeOption: this.option })
            .width(300)
            .height(300)
        }.width('100%')
      }.height('100%')
  }
}

非常簡單，僅需定義一個ImageKnifeOption數據對象，然后在你需要的UI位置，加入ImageKnifeComponent自定義組件就可以加載出一張圖像了。

3.加載SVG圖片

加載svg其實和普通流程沒有區別,只要將 loadSrc: $r('app.media.jpgSample'),``改成一張 loadSrc: $r('app.media.svgSample'), svg類型圖片即可。

4.加載GIF圖片

加載GIF其實和普通流程也沒有區別只要將 loadSrc: $r('app.media.jpgSample'),``改成一張 loadSrc: $r('app.media.gifSample'), GIF圖片即可。

5.自定義Key

因為通常改變標識符比較困難或者根本不可能，所以ImageKnife也提供了 簽名 API 來混合（你可以控制的）額外數據到你的緩存鍵中。 簽名(signature)適用于媒體內容，也適用于你可以自行維護的一些版本元數據。

將簽名傳入加載請求

imageKnifeOption = {
                loadSrc: 'https://aahyhy.oss-cn-beijing.aliyuncs.com/blue.jpg',
                signature: new ObjectKey(new Date().getTime().toString())
              }

詳細樣例請參考SignatureTestPage文件

代碼示例

進階使用

如果簡單的加載一張圖像無法滿足需求，我們可以看看ImageKnifeOption這個類提供了哪些擴展能力。

ImageKnifeOption參數列表

其他參數只需要在ImageKnifeOption對象上按需添加即可。

這里我們著重講一下 自定義實現繪制方案 。為了增強繪制擴展能力，目前ImageKnifeComponent使用了Canvas的渲染能力作為基礎。在此之上為了抽象組件繪制表達。我將圖像的狀態使用了 IDrawLifeCycle繪制生命周期進行表達 ，

大致流程 展示占位圖->展示網絡加載進度->展示縮略圖->展示主圖->展示重試圖層->展示失敗占位圖

ImageKnifeComponent內部，責任鏈實現。 用戶參數設置->全局參數設置->自定義組件內部設置

采用責任鏈的好處是，用戶可以通過自定義繪制，重新繪制圖層。如果不想繪制也可以通過預制回調獲取繪制流程信息。

場景1:默認的展示不滿足需求，需要加個圓角效果。

代碼如下:

import { ImageKnifeComponent } from '@ohos/imageknife'
import { ImageKnifeOption } from '@ohos/imageknife'
import { ImageKnifeDrawFactory } from '@ohos/imageknife'

@Entry
@Component
struct Index {
  @State imageKnifeOption1: ImageKnifeOption = { 
      // 加載一張本地的jpg資源（必選）
      loadSrc: $r('app.media.jpgSample'),
      // 占位圖使用本地資源icon_loading（可選）
      placeholderSrc: $r('app.media.icon_loading'),
      // 失敗占位圖使用本地資源icon_failed（可選）
      errorholderSrc: $r('app.media.icon_failed'),
      // 繪制圓角30，邊框5，邊框"#ff00ff".用戶自定義繪制（可選）
      drawLifeCycle:ImageKnifeDrawFactory.createRoundLifeCycle(5,"#ff00ff",30)
    };
        
    build(){
        Scroll() {
          Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
            ImageKnifeComponent({ imageKnifeOption: this.imageKnifeOption1 })
            .width(300) 
            .height(300)
          }
        }
        .width('100%')
        .height('100%')
    }
}

ImageKnifeDrawFactory.createRoundLifeCycle(5,"#ff00ff",30) 我們深入查看源碼可以發現，實際上是對IDrawLifeCycle接口的部分實現，這里我介紹一下IDrawLifeCycle。

IDrawLifeCycle的返回值代表事件是否被消費，如果被消費接下來組件內部就不會處理，如果沒被消費就會傳遞到下一個使用者。目前消費流程（用戶自定義-> 全局配置定義->組件內部默認定義） *

所以我們在當數據是一張PixelMap的時候（目前jpg png bmp webp svg返回的都是PixelMap，gif返回GIFFrame數組），我們返回了true。消費了事件，代表這個繪制流程用戶自定義完成。

由于IDrawLifeCycle實現較為冗長，我們封裝了ImageKnifeDrawFactory工廠，提供了網絡下載百分比效果、圓角、橢圓添加邊框等能力。下面我們就再看看使用工廠封裝之后的場景代碼。

場景2: 網絡下載百分比效果展示

當進行加載網絡圖片時，可能需要展示網絡下載百分比動畫。但是默認的動畫又不能滿足需求，這個時候我們就需要自定義網絡下載百分比效果。代碼如下:

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import { ImageKnifeGlobal,ImageKnife,ImageKnifeDrawFactory,LogUtil } from '@ohos/imageknife'
import abilityAccessCtrl,{Permissions} from '@ohos.abilityAccessCtrl';
export default class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage) {
        //.. 刪除不必要代碼
        windowStage.loadContent('pages/index', (err, data) = > {
        });
       	// 初始化ImageKnifeGlobal和ImageKnife
        ImageKnife.with(this.context);
        // 全局配置網絡加載進度條 使用ImageKnifeGlobal.getInstance().getImageKnife()訪問ImageKnife
ImageKnifeGlobal.getInstance().getImageKnife().setDefaultLifeCycle(ImageKnifeDrawFactory.createProgressLifeCycle("#10a5ff", 0.5))
    }
}

這里大家可能會問，為什么會將這個IDrawLifeCycle放在AbilityStage里面實現？

這是因為網絡下載百分比進度很多時候都是全局通用，如果有需要全局配置的自定義展示方案。推薦在AbilityStage里面，往ImageKnife的setDefaultLifeCycle函數中注入，即可將ImageKnifeComponent中的默認繪制方案替換。

在這里我們實現的效果如下圖所示。

高級用法

以上簡單使用和進階使用都是經過一層自定義組件封裝之后形成的，RequestOption封裝成了ImageKnifeOption,繪制部分封裝成了自定義組件ImageKnifeComponent。

如果用戶其實并不關心繪制部分，或者說想用自己的通用方案對自定義組件ImageKnifeComponent重構都是可以的。

下面我們會著重指導用戶如何復用圖片加載邏輯，重構自定義組件ImageKnifeComponent。

首先我們先看看RequestOption構建的內容,如下所示:

數據加載

RequestOption構建:

請查閱下文接口內容：[RequestOption接口方法]

了解了RequestOption的參數內容后，我們可以參考ImageKnifeComponent組件代碼進行分析。

從imageKnifeExecute()函數入口，首先我們需要構建一個RequestOption對象，let request = new RequestOption(), 接下來就是按需配置request對象的內容，最后使用 ImageKnifeGlobal.getInstance().getImageKnife()?.call(request)發送request執行任務即可。

是不是很簡單，而其實最重要的內容是就是: 按需配置request對象的內容 為了更好理解，我舉例說明一下:

場景一: 簡單加載一張圖片

let request = new RequestOption();
// (必傳)
request.load("圖片url")
  // (可選 整個request監聽回調)
	.addListener({callback:(err:BusinessError|string, data:ImageKnifeData) = > {
	// data 是ImageKnifeData對象
	if(data.isPixelMap()){
	// 這樣就獲取到了目標PixelMap
	let pixelmap = data.drawPixleMap.imagePixelMap;
	}
    return false;
  })
 
  let compSize:Size = {
    width: this.currentWidth,
    height:this.currentHeight
  }
  // (必傳)這里setImageViewSize函數必傳組件大小，因為涉及到圖片變換效果都需要適配圖像源和組件大小
 request.setImageViewSize(compSize)
 // 最后使用ImageKnife的call函數調用request即可
 let imageKnife:ImageKnife|undefined = ImageKnifeGlobal.getInstance().getImageKnife();
 if(imageKnife != undefined){
 	imageKnife.call(request)
 }

其他場景，可以按需加載

比如我需要配置 占位圖 只需要 在request對象創建好之后,調用 placeholder 函數即可

request.placeholder(this.imageKnifeOption.placeholderSrc, (data) = > {
  console.log('request.placeholder callback')
  this.displayPlaceholder(data)
})

再比如 我對緩存配置有要求，我要禁用內存緩存，調用 skipMemoryCache 函數即可

request.skipMemoryCache(true)

這里只是簡單介紹部分使用，更多的內容請參考 按需加載 原則，并且可以參考ImageKnifeComponent源碼或者根據文檔自行探索實現。

接口說明

RequestOption用戶配置參數

同時支持[圖片變換相關]接口。

ImageKnife 啟動器/門面類

緩存策略相關

AntiAliasing類型展示效果

ScaleType類型展示效果

圖片變換相關

setLruCacheSize

setLruCacheSize(size: number,memory:number): void

設置圖片文件緩存的大小上限，size單位為張數，memory單位為字節，提升再次加載同源圖片的加載速度，特別是對網絡圖源會有較明顯提升。 如果不設置則默認為100張，100MB。緩存采用內置的LRU策略。 size為0則代表不限制緩存張數，memory為0則代表不限制緩存大小。 建議根據應用實際需求，設置合理緩存上限，數字過大可能導致內存占用過高，可能導致OOM異常。

參數：

示例：

//EntryAbility.ets
import { InitImageKnife } from '...imageknife'
export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) { 
    InitImageKnife.init(this.context);
    let imageKnife: ImageKnife | undefined = ImageKnifeGlobal.getInstance().getImageKnife()
    if (imageKnife != undefined) {
      //設置全局內存緩存大小張數
      imageKnife.setLruCacheSize(100, 100 * 1204 * 1024)
    }
  }
}

約束與限制

在下述版本驗證通過： DevEco Studio 4.1（4.1.3.520）--SDK:API11（ 4.1.0.63） DevEco Studio 4.1（4.1.3.418）--SDK:API11（ 4.1.0.56） DevEco Studio 4.1（4.1.3.322）--SDK:API11（ 4.1.0.36） DevEco Studio 4.0（4.0.3.700）--SDK:API10（ 4.0.10.15）

HSP場景適配:

在使用ImageKnifeComponent進行加載圖片時, 提供的ImageKnifeOption配置類新增了可選參數context, 在HSP場景下需要傳入正確的context, 才能保證三方庫后續正確獲取Resource資源。

在使用RquestOption進行加載圖片時, 提供的RquestOption配置類新增了接口setModuleContext(moduleCtx:common.UIAbilityContext), 在HSP場景下需要傳入正確的context, 才能保證三方庫后續正確獲取Resource資源。

非HSP場景不影響原功能, ImageKnifeOption配置類新增的可選參數context可以不傳, RquestOption配置類新增的接口可以不調用。

更多鴻蒙開發知識已經更新在[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]前往參考。

遺留問題

1.目前只支持一種圖片變換效果。

2.目前svg和gif動圖不支持變換效果。

補充說明

SVG標簽說明

使用版本為(SVG)1.1,當前支持的標簽列表有：

• a
• circla
• clipPath
• defs
• ellipse
• feBlend
• feColorMatrix
• feComposite
• feDiffuseLighting
• feDisplacementMap
• feDistantLight
• feFlood
• feGaussianBlur
• feImage
• feMorphology
• feOffset
• fePointLight
• feSpecularLighting
• feSpotLight
• feTurbulence
• filter
• g
• image
• line
• linearGradient
• mask
• path
• pattern
• polygon
• polyline
• radialGradient
• rect
• stop
• svg
• text
• textPath
• tspan
• use

審核編輯 黃宇