ImageKnife

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

簡(jiǎn)介

OpenHarmony的自研版本：

• 支持內(nèi)存緩存，使用LRUCache算法，對(duì)圖片數(shù)據(jù)進(jìn)行內(nèi)存緩存。
• 支持磁盤緩存，對(duì)于下載圖片會(huì)保存一份至磁盤當(dāng)中。
• 支持進(jìn)行圖片變換: 支持圖像像素源圖片變換效果。
• 支持用戶配置參數(shù)使用:( 例如：配置是否開啟一級(jí)內(nèi)存緩存，配置磁盤緩存策略，配置僅使用緩存加載數(shù)據(jù)，配置圖片變換效果，配置占位圖，配置加載失敗占位圖等)。
• 推薦使用ImageKnifeComponent組件配合ImageKnifeOption參數(shù)來(lái)實(shí)現(xiàn)功能。
• 支持用戶自定義配置實(shí)現(xiàn)能力參考ImageKnifeComponent組件中對(duì)于入?yún)mageKnifeOption的處理。

下載安裝

ohpm install @ohos/imageknife

使用說(shuō)明

1.依賴配置

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

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);
  	// 后續(xù)訪問(wèn)ImageKnife請(qǐng)通過(guò):ImageKnifeGlobal.getInstance().getImageKnife()方式
  }
}

2.加載普通圖片

接下來(lái)我們來(lái)寫個(gè)簡(jiǎn)單實(shí)例看看:

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%')
  }
}

非常簡(jiǎn)單，僅需定義一個(gè)ImageKnifeOption數(shù)據(jù)對(duì)象，然后在你需要的UI位置，加入ImageKnifeComponent自定義組件就可以加載出一張圖像了。

3.加載SVG圖片

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

4.加載GIF圖片

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

5.自定義Key

因?yàn)橥ǔ８淖儤?biāo)識(shí)符比較困難或者根本不可能，所以ImageKnife也提供了 簽名 API 來(lái)混合（你可以控制的）額外數(shù)據(jù)到你的緩存鍵中。 簽名(signature)適用于媒體內(nèi)容，也適用于你可以自行維護(hù)的一些版本元數(shù)據(jù)。

將簽名傳入加載請(qǐng)求

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

詳細(xì)樣例請(qǐng)參考SignatureTestPage文件

代碼示例

進(jìn)階使用

如果簡(jiǎn)單的加載一張圖像無(wú)法滿足需求，我們可以看看ImageKnifeOption這個(gè)類提供了哪些擴(kuò)展能力。

ImageKnifeOption參數(shù)列表

其他參數(shù)只需要在ImageKnifeOption對(duì)象上按需添加即可。

這里我們著重講一下 自定義實(shí)現(xiàn)繪制方案 。為了增強(qiáng)繪制擴(kuò)展能力，目前ImageKnifeComponent使用了Canvas的渲染能力作為基礎(chǔ)。在此之上為了抽象組件繪制表達(dá)。我將圖像的狀態(tài)使用了 IDrawLifeCycle繪制生命周期進(jìn)行表達(dá) ，

大致流程 展示占位圖->展示網(wǎng)絡(luò)加載進(jìn)度->展示縮略圖->展示主圖->展示重試圖層->展示失敗占位圖

ImageKnifeComponent內(nèi)部，責(zé)任鏈實(shí)現(xiàn)。 用戶參數(shù)設(shè)置->全局參數(shù)設(shè)置->自定義組件內(nèi)部設(shè)置

采用責(zé)任鏈的好處是，用戶可以通過(guò)自定義繪制，重新繪制圖層。如果不想繪制也可以通過(guò)預(yù)制回調(diào)獲取繪制流程信息。

場(chǎng)景1:默認(rèn)的展示不滿足需求，需要加個(gè)圓角效果。

代碼如下:

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) 我們深入查看源碼可以發(fā)現(xiàn)，實(shí)際上是對(duì)IDrawLifeCycle接口的部分實(shí)現(xiàn)，這里我介紹一下IDrawLifeCycle。

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

所以我們?cè)诋?dāng)數(shù)據(jù)是一張PixelMap的時(shí)候（目前jpg png bmp webp svg返回的都是PixelMap，gif返回GIFFrame數(shù)組），我們返回了true。消費(fèi)了事件，代表這個(gè)繪制流程用戶自定義完成。

由于IDrawLifeCycle實(shí)現(xiàn)較為冗長(zhǎng)，我們封裝了ImageKnifeDrawFactory工廠，提供了網(wǎng)絡(luò)下載百分比效果、圓角、橢圓添加邊框等能力。下面我們就再看看使用工廠封裝之后的場(chǎng)景代碼。

場(chǎng)景2: 網(wǎng)絡(luò)下載百分比效果展示

當(dāng)進(jìn)行加載網(wǎng)絡(luò)圖片時(shí)，可能需要展示網(wǎng)絡(luò)下載百分比動(dòng)畫。但是默認(rèn)的動(dòng)畫又不能滿足需求，這個(gè)時(shí)候我們就需要自定義網(wǎng)絡(luò)下載百分比效果。代碼如下:

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);
        // 全局配置網(wǎng)絡(luò)加載進(jìn)度條 使用ImageKnifeGlobal.getInstance().getImageKnife()訪問(wèn)ImageKnife
ImageKnifeGlobal.getInstance().getImageKnife().setDefaultLifeCycle(ImageKnifeDrawFactory.createProgressLifeCycle("#10a5ff", 0.5))
    }
}

這里大家可能會(huì)問(wèn)，為什么會(huì)將這個(gè)IDrawLifeCycle放在AbilityStage里面實(shí)現(xiàn)？

這是因?yàn)榫W(wǎng)絡(luò)下載百分比進(jìn)度很多時(shí)候都是全局通用，如果有需要全局配置的自定義展示方案。推薦在AbilityStage里面，往ImageKnife的setDefaultLifeCycle函數(shù)中注入，即可將ImageKnifeComponent中的默認(rèn)繪制方案替換。

在這里我們實(shí)現(xiàn)的效果如下圖所示。

高級(jí)用法

以上簡(jiǎn)單使用和進(jìn)階使用都是經(jīng)過(guò)一層自定義組件封裝之后形成的，RequestOption封裝成了ImageKnifeOption,繪制部分封裝成了自定義組件ImageKnifeComponent。

如果用戶其實(shí)并不關(guān)心繪制部分，或者說(shuō)想用自己的通用方案對(duì)自定義組件ImageKnifeComponent重構(gòu)都是可以的。

下面我們會(huì)著重指導(dǎo)用戶如何復(fù)用圖片加載邏輯，重構(gòu)自定義組件ImageKnifeComponent。

首先我們先看看RequestOption構(gòu)建的內(nèi)容,如下所示:

數(shù)據(jù)加載

RequestOption構(gòu)建:

請(qǐng)查閱下文接口內(nèi)容：[RequestOption接口方法]

了解了RequestOption的參數(shù)內(nèi)容后，我們可以參考ImageKnifeComponent組件代碼進(jìn)行分析。

從imageKnifeExecute()函數(shù)入口，首先我們需要構(gòu)建一個(gè)RequestOption對(duì)象，let request = new RequestOption(), 接下來(lái)就是按需配置request對(duì)象的內(nèi)容，最后使用 ImageKnifeGlobal.getInstance().getImageKnife()?.call(request)發(fā)送request執(zhí)行任務(wù)即可。

是不是很簡(jiǎn)單，而其實(shí)最重要的內(nèi)容是就是: 按需配置request對(duì)象的內(nèi)容 為了更好理解，我舉例說(shuō)明一下:

場(chǎng)景一: 簡(jiǎn)單加載一張圖片

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

其他場(chǎng)景，可以按需加載

比如我需要配置 占位圖 只需要 在request對(duì)象創(chuàng)建好之后,調(diào)用 placeholder 函數(shù)即可

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

再比如 我對(duì)緩存配置有要求，我要禁用內(nèi)存緩存，調(diào)用 skipMemoryCache 函數(shù)即可

request.skipMemoryCache(true)

這里只是簡(jiǎn)單介紹部分使用，更多的內(nèi)容請(qǐng)參考 按需加載 原則，并且可以參考ImageKnifeComponent源碼或者根據(jù)文檔自行探索實(shí)現(xiàn)。

接口說(shuō)明

RequestOption用戶配置參數(shù)

同時(shí)支持[圖片變換相關(guān)]接口。

ImageKnife 啟動(dòng)器/門面類

緩存策略相關(guān)

AntiAliasing類型展示效果

ScaleType類型展示效果

圖片變換相關(guān)

setLruCacheSize

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

設(shè)置圖片文件緩存的大小上限，size單位為張數(shù)，memory單位為字節(jié)，提升再次加載同源圖片的加載速度，特別是對(duì)網(wǎng)絡(luò)圖源會(huì)有較明顯提升。 如果不設(shè)置則默認(rèn)為100張，100MB。緩存采用內(nèi)置的LRU策略。 size為0則代表不限制緩存張數(shù)，memory為0則代表不限制緩存大小。 建議根據(jù)應(yīng)用實(shí)際需求，設(shè)置合理緩存上限，數(shù)字過(guò)大可能導(dǎo)致內(nèi)存占用過(guò)高，可能導(dǎo)致OOM異常。

參數(shù)：

示例：

//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) {
      //設(shè)置全局內(nèi)存緩存大小張數(shù)
      imageKnife.setLruCacheSize(100, 100 * 1204 * 1024)
    }
  }
}

約束與限制

在下述版本驗(yàn)證通過(guò)： 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場(chǎng)景適配:

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

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

非HSP場(chǎng)景不影響原功能, ImageKnifeOption配置類新增的可選參數(shù)context可以不傳, RquestOption配置類新增的接口可以不調(diào)用。

更多鴻蒙開發(fā)知識(shí)已經(jīng)更新在[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]前往參考。

遺留問(wèn)題

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

2.目前svg和gif動(dòng)圖不支持變換效果。

補(bǔ)充說(shuō)明

SVG標(biāo)簽說(shuō)明

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

• 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

審核編輯 黃宇