火山引擎 HarmonyOS NEXT 图片加载 SDK 基于鸿蒙图片加载开源库 ImageKnife 3.0.0-rc.6 版本进行开发，额外提供了 HEIC 软解能力。本文为您介绍如何将 HarmonyOS NEXT 图片加载 SDK 集成到您的项目中，并使用 SDK 提供的功能。

注意事项

• HarmonyOS NEXT 图片加载 SDK 仍处于邀测阶段，本文所提到的功能均使用 HarmonyOS NEXT 5.0.0.115 SP6 版本进行测试，且存在下列已知问题。
• 请您在开发过程中使用本文提供的接口，veImageX 不保证开源库提供的其他接口的可用性。
• 图片加载 SDK 需要使用 License 授权，火山引擎提供试用版 License 和正式版 License。试用版 License 仅用于功能调试，不支持续期，App 上线前请申请正式 License。

发布历史

集成说明

获取 Token

1. 登录 veImageX 控制台。
2. 单击左侧导航栏的应用管理，进入应用管理页面。
   
3. 单击您的 APP 应用卡片，进入应用详情页。
4. 在基本信息区域，单击查看 Token，获取 Token 值。
   

购买授权

1. 在 APP 应用中的 License 授权区域，单击购买授权按钮。
2. 在购买弹窗中，SDK 类型选择客户端图片加载 SDK，根据实际需要购买所需授权。调试期间，建议您购买免费试用版授权。

   说明

   • 每个账号仅支持购买一次可免费一个月的试用版授权，不支持重复购买。
   • 定制版授权支持多种时长方案，可根据您的多应用场景（不同应用名称）选择购买多个授权，具体定价详情请联系我们。
3. 绑定您的鸿蒙包名，绑定完成后，veImageX 将为您自动签发授权码。
   
4. Lincense 签发完成后，单击操作列的下载授权码按钮，下载授权码至本地。

添加依赖

1. 在项目根目录中添加 SDK 依赖下载地址配置文件.ohpmrc。

2. 编辑.ohpmrc文件，并在文件中追加如下内容。

   @imagex:registry=https://artifact.bytedance.com/repository/byted-ohpm/
   @codec:registry=https://artifact.bytedance.com/repository/byted-ohpm/
   @bytedance:registry=https://artifact.bytedance.com/repository/byted-ohpm/
   

3. 在工程的 entry 下的 oh-package.json5 文件中添加本地依赖。

   // 请传入 SDK 在您项目中的实际路径
   "dependencies": {
       // 鉴权依赖
       "@imagex/imagex_authorization": "0.0.4-tob",
       // 加载库
       "@imagex/imagex_bdimageknife": "1.0.0-tob"
   }
   

配置鉴权

请将获取的 Token 和授权码填入以下代码中，完成鉴权的配置以及初始化操作。

// 建议将以下内容放在主页面加载之前
onWindowStageCreate(windowStage: window.WindowStage): void {
  let config: AuthInitConfig = new AuthInitConfig(this.context, "token", ["authCode"]); //请依次填写 Token 和授权码
  Authorization.init(config);

  windowStage.loadContent('xxx', (err) => {
    ...
  });
}

功能说明

显示本地资源图片

ImageKnifeComponent({
  ImageKnifeOption: {
    loadSrc: $r("app.media.app_icon"),
    placeholderSrc: $r("app.media.loading"),
    errorholderSrc: $r("app.media.app_icon"),
    objectFit: ImageFit.Auto
  }
}).width(100).height(100)

显示本地 context files 下文件

ImageKnifeComponent({
  ImageKnifeOption: {
    loadSrc: this.localFile,
    placeholderSrc: $r("app.media.loading"),
    errorholderSrc: $r("app.media.app_icon"),
    objectFit: ImageFit.Auto
  }
}).width(100).height(100)

显示网络图片

ImageKnifeComponent({
  ImageKnifeOption: {
    loadSrc:"https://www.openharmony.cn/_nuxt/img/logo.dcf95b3.png",
    placeholderSrc: $r("app.media.loading"),
    errorholderSrc: $r("app.media.app_icon"),
    objectFit: ImageFit.Auto
  }
}).width(100).height(100)

自定义下载图片

ImageKnifeComponent({
  ImageKnifeOption: {
    loadSrc: "https://file.atomgit.com/uploads/user/1704857786989_8994.jpeg",
    placeholderSrc: $r("app.media.loading"),
    errorholderSrc: $r("app.media.app_icon"),
    objectFit: ImageFit.Auto,
    customGetImage: custom
 }
}).width(100).height(100)

// 自定义实现图片获取方法，如自定义网络下载
@Concurrent
async function custom(context: Context, src: string | PixelMap | Resource): Promise<ArrayBuffer | undefined> {
  console.info("ImageKnife::  custom download：" + src)
  // 举例写死从本地文件读取，也可以自己请求网络图片
  return context.resourceManager.getMediaContentSync($r("app.media.bb").id).buffer as ArrayBuffer
}

监听网络下载进度

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)

图片变换，设置边框、圆角等

ImageKnifeComponent({ ImageKnifeOption: 
{
   loadSrc: $r("app.media.rabbit"),
   border: {radius:50}
  }
}).width(100).height(100)

ImageKnifeComponent({
  {
  loadSrc: $r('app.media.pngSample'),
  placeholderSrc: $r("app.media.loading"),
  errorholderSrc: $r("app.media.app_icon"),
  objectFit: ImageFit.Contain,
  border: { radius: { topLeft: 50, bottomRight: 50 } }, // 圆角设置
}
}).width(300)
  .height(300)
  .rotate({ angle: 90 }) // 旋转90度
  .contrast(12) // 对比度滤波器

监听图片加载成功与失败

ImageKnifeComponent({ ImageKnifeOption: 
{
   loadSrc: $r("app.media.rabbit"),
   onLoadListener:{
    onLoadStart:()=>{
     this.starTime = new Date().getTime()
     console.info("Load start: ");
    },
    onLoadFailed: (err) => {
     console.error("Load Failed Reason: " + err + "  cost " + (new Date().getTime() - this.starTime) + " milliseconds");
    },
    onLoadSuccess: (data) => {
     console.info("Load Successful: cost " + (new Date().getTime() - this.starTime) + " milliseconds");
     return data;
    },
   }
  }
}).width(100).height(100)

接口说明

initFileCache

初始化文件缓存数量和大小。

类型

(context: Context, size: number = 256, memory: number = 256 * 1024 * 1024): void 

参数

返回值

void

preLoadCache

预加载并返回文件缓存路径。

类型

(loadSrc: string | ImageKnifeOption): Promise<string>

参数

返回值

Promise<string>

addHeader

全局添加 HTTP 请求头。

类型

(key: string, value: Object): void 

参数

返回值

void

setHeaderOptions

全局设置 HTTP 请求头。

类型

(options: Array<HeaderOptions>): void 

参数

返回值

void

deleteHeader

全局删除 HTTP 请求头。

类型

(key: string): void

参数

返回值

void

ImageKnifeOption