HarmonyOS NEXT 加载 SDK--veImageX-火山引擎

文档中心

veImageX

加载 SDK

HarmonyOS NEXT 加载 SDK

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

注意事项

HarmonyOS NEXT 图片加载 SDK 仍处于邀测阶段，本文所提到的功能均使用 HarmonyOS NEXT 5.1.0.150 SP15 版本和 HarmonyOS 6.1.0.117 SP6 版本进行测试。
暂不支持 AVIF 格式图片。
图片加载 SDK 需要使用 License 授权，火山引擎提供试用版 License 和正式版 License。试用版 License 仅用于功能调试，不支持续期，App 上线前请申请正式 License。

集成说明

获取 Token

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

购买授权

在 App 类型应用中的 License 授权区域，单击购买授权按钮。
在购买弹窗中，SDK 类型选择客户端图片加载 SDK，根据实际需要购买所需授权。调试期间，建议您购买免费试用版授权。
说明
- 每个账号仅支持购买一次可免费一个月的试用版授权，不支持重复购买。
- 定制版授权支持多种时长方案，可根据您的多应用场景（不同应用名称）选择购买多个授权，具体定价详情请联系我们。
绑定您的鸿蒙包名，绑定完成后，veImageX 将为您自动签发授权码。
License 签发完成后，单击操作列的下载授权码按钮，下载授权码至本地。

添加依赖

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

编辑.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/

在需要依赖 SDK 的 oh-package.json5 文件中添加本地依赖。
说明
你需要把 x.x.x 替换为使用的 SDK 版本号，参看发布历史获取版本号信息。
```
"dependencies": {
    "@imagex/imagex_veimageknife": "x.x.x"
}
```

配置鉴权

请将获取的 appID、Token 和授权码填入以下代码中，完成鉴权的配置以及初始化操作。appID 用来进行埋点数据上报。

// 建议将以下内容放在主页面加载之前
onWindowStageCreate(windowStage: window.WindowStage): void {
  // appID、authcode、token 均在控制台获取
  ImageKnife.getInstance().initVEImageKnifePro("appID", ['authCode1', 'authCode2'], 'token', this.context);

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

功能说明

图片库初始化

图片库的使用需要先初始化网络和缓存。

TTNetTobInit.initTTNet(true, null, false, this.context);
ImageKnife.getInstance().initFileCache(this.context, 256, 256 * 1024 * 1024);

显示本地资源图片

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)

显示本地 context files 下文件

ImageKnifeComponent({
  ImageKnifeOption: {
    loadSrc: "file:/data/storage/el2/base/haps/entry/files/example_cache_file",
    placeholderSrc: "file:/data/storage/el2/base/haps/entry/files/localFile",
    errorSrc: "file:/data/storage/el2/base/haps/entry/files/example_cache_fileTest",
    objectFit: ImageFit.Auto
  }
}).width(100).height(100)

显示网络图片

ImageKnifeComponent 支持静图和动图，并且加载动图时可以通过animatorOption来对动图进行播控，并监听相应事件。

ImageKnifeComponent({
  ImageKnifeOption: {
    loadSrc:"https://www.example.com/example.png",
    placeholderSrc: $r("app.media.loading"),
    errorSrc: $r("app.media.app_icon"),
    objectFit: ImageFit.Auto
  },
  // 动图配置，加载静图时无需使用
  animatorOption: {
    state: AnimationStatus.Running,
    iterations: -1,
  }
}).width(100).height(100)

监听网络下载进度

ImageKnifeComponent({
  ImageKnifeOption: {
    loadSrc:"https://www.example.com/example.png",
    progressListener:(progress:number) => {
        console.info("call back progress = " + progress)
    }
  }
}).width(100).height(100)

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

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

设置图片可拖拽

ImageKnifeComponent({
    imageKnifeOption: this.imageKnifeOption,
    imageDraggable: true
}).width(200).height(200)

监听图片加载状态

import { ImageKnifeComponent, ImageKnifeOption } from '@imagex/imagex_veimageknife'

@Component
struct ExamplePage {
  @State imageKnifeOption: ImageKnifeOption = {
    loadSrc: $r('app.media.rabbit'),
    onLoadListener: {
      onLoadStart: (imageInfo) => {
        console.info('Load start, requestId: ' + imageInfo.requestId)
      },
      onLoadFailed: (err, imageInfo) => {
        console.error('Load failed: ' + err)
      },
      onLoadSuccess: (imageInfo) => {
        console.info('Load Successful')
      },
      onLoadCancel: (reason, imageInfo) => {
        console.info('Load cancelled: ' + reason)
      }
    }
  }

  build() {
    Column() {
      ImageKnifeComponent({
        imageKnifeOption: this.imageKnifeOption
      }).width(200).height(200)
    }
  }
}

设置 HEIC 图片解码策略

// 全局设置
ImageKnife.getInstance().setHeicDecodeStrategy(HeicDecodeStrategy.DEFAULT);

export enum HeicDecodeStrategy {
  // 默认行为，先软解后硬解
  DEFAULT = 0,
  // 先硬解后软解
  SYSTEMFIRST = 1,
  // 只使用硬解
  SYSTEMONLY = 2,
  // 只使用软解
  SYSTEMWITHOUT = 3
}

设置 HEIC 图片降采样

export enum HeicInSampleRatio {
  RATIO_8K = 0,
  RATIO_4K = 1,
  RATIO_2K = 2
}
// 默认最大分辨率是 8K，超过 8K 的 heic 图片会被降采样到 8K，可以配置为 4K 或 2K。
ImageKnifeSwitch.getInstance().setHeicInSampleRatio(HeicInSampleRatio.RATIO_8K);

设置图片拉伸

通过 ImageKnifeOption 设置 resizeable 属性，可做到图片拉伸。

let imageKnifeOption: ImageKnifeOption =
  {
    loadSrc: url,
    ...
    // 设置拉伸含义，具体参考 ResizableOption 类；
    resizeable: {top:10, left:10, right: 10, bottom: 10},
  };

接口说明

initFileCache

初始化文件缓存个数、大小，以及路径。

类型

(context: Context, size: number = 256, maxDiskUsage: number = 256 * 1024 * 1024, path?: string): Promise<void>

参数

名称	类型	是否必选	默认值	说明
context	Context	是	无	上下文。
size	number	否	256	设置最大图片缓存数量。
maxDiskUsage	number	否	256 * 1024 * 1024	设置最大硬盘使用量。
path	string	否	"ImageKnife"	设置文件缓存的子目录。

返回值

Promise<void>

preLoad

预加载并返回对应图片请求的 ImageKnifeRequest 类。

类型

(loadSrc: string | ImageKnifeOption): ImageKnifeRequest

参数

名称	类型	是否必选	默认值	说明
loadSrc	string I ImageKnifeOption	是	无	设置预加载 url 或者预加载 ImageKnifeOption。

返回值

ImageKnifeRequest

addHeader

全局添加 HTTP 请求头。

类型

(key: string, value: Object): void

参数

名称	类型	是否必选	默认值	说明
key	string	是	无	请求 Header 的键。
value	Object	是	无	请求 Header 的值。

返回值

void

setHeaderOptions

全局批量设置 HTTP 请求头。

类型

(options: Array<HeaderOptions>): void

参数

名称	类型	是否必选	默认值	说明
options	Array	是	无	全局设置 Header 集合。

返回值

void

deleteHeader

全局删除 HTTP 请求头。

类型

(key: string): void

参数

名称	类型	是否必选	默认值	说明
key	string	是	无	指定要删除的 Header 的键。

返回值

void

ImageKnifeComponent

参数

参数	类型	是否必选	默认值	说明
imageKnifeOption	`ImageKnifeOption`	是	无	图片加载配置项。
animatorOption	`AnimatorOption`	否	无	动图播放控制选项。
imageDraggable	`boolean`	否	false	图片是否可拖拽。
syncLoad	`boolean`	否	false	是否同步加载，建议适用于小尺寸本地 Resource 图片。

ImageKnifeOption

参数

参数	类型	是否必选	默认值	说明
loadSrc	`string \| PixelMap \| Resource`	是	无	主图展示
placeholderSrc	`string \| PixelMap \| Resource`	否	无	占位图展示
thumbnailSrc	`string \| PixelMap \| Resource`	否	无	缩略图展示
errorSrc	`string \| PixelMap \| Resource`	否	无	错误图展示
imageKnifeLoader	`string`	否	无	自定义图片加载 loader, 需要在 C 侧实现自定义 loader 并注册。
headerOption	`Array<HeaderOptions>`	否	无	自定义网络加载请求头列表
dnsOption	`DnsOption`	否	无	自定义 DNS 配置
signature	`string`	否	无	自定义缓存 Key 生成所用的签名
objectFit	`ImageFit`	否	无	主图填充效果
placeholderObjectFit	`ImageFit`	否	无	占位图填充效果
thumbnailObjectFit	`ImageFit`	否	无	缩略图填充效果
errorObjectFit	`ImageFit`	否	无	错误图填充效果
resizeable	`ResizableOption`	否	无	图像拉伸时可调整大小的图像选项
writeCacheStrategy	`CacheStrategy`	否	无	写入缓存策略
onlyRetrieveFromCache	`boolean`	否	无	是否跳过网络和本地请求
border	`BorderOptions`	否	无	边框圆角
priority	`Priority`	否	无	加载优先级
context	`common.UIAbilityContext`	否	无	上下文
transformationOption	`TransformationOption`	否	无	图形变换对象，在图片加载过程中执行一次，优先级低于 `multiTransformationOption`
multiTransformationOption	`Array<TransformationOption>`	否	无	多次图形变换对象，优先级高于 transformationOption
progressListener	`(progress: number)=>void`	否	无	进度。
onLoadListener	`OnLoadCallBack \| undefined`	否	无	监听图片加载状态，可设置相关加载回调
animationDecodeMode	`AnimationDecodeMode`	否	`AnimationDecodeMode.AUTO`	动图解码模式
downSampling	`DownSamplingStrategy`	否	`DownSamplingStrategy.NONE`	设置降采样策略
fallbackUrls	`Array<string>`	否	无	备用图片地址
useSmartCrop	`boolean`	否	`false`	配合 ImageX 使用智能裁图。
tags	`ImageKnifeTag`	否	无	配置图片的标签。

AnimatorOption

参数

名称	类型	是否必选	默认值	说明
state	`AnimationStatus`	否	`AnimationStatus.Running`	播放状态
iterations	number	否	-1	播放次数，-1 表示无限循环
reverse	boolean	否	false	是否反向播放
onStart	() => void	否	无	动画开始播放时回调
onFinish	() => void	否	无	动画播放完成或停止时回调
onPause	() => void	否	无	动画暂停时回调
onCancel	() => void	否	无	动画返回初始状态时回调
onRepeat	() => void	否	无	动画重复播放时回调

最近更新时间：2026.06.02 20:01:29

这个页面对您有帮助吗？

有用

无用

veImageX

注意事项 #

集成说明 #

获取 Token #

购买授权 #

添加依赖 #

配置鉴权 #

功能说明 #

图片库初始化 #

显示本地资源图片 #

显示本地 context files 下文件 #

显示网络图片 #

监听网络下载进度 #

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

设置图片可拖拽 #

监听图片加载状态 #

设置 HEIC 图片解码策略 #

设置 HEIC 图片降采样 #

设置图片拉伸 #

接口说明 #

initFileCache #

类型

参数

返回值

preLoad #

类型

参数

返回值

addHeader #

类型

参数

返回值

setHeaderOptions #

类型

参数

返回值

deleteHeader #

类型

参数

返回值

ImageKnifeComponent #

参数

ImageKnifeOption #

参数

AnimatorOption #

参数

注意事项

集成说明

获取 Token

购买授权

添加依赖

配置鉴权

功能说明

图片库初始化

显示本地资源图片

显示本地 context files 下文件

显示网络图片

监听网络下载进度

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

设置图片可拖拽

监听图片加载状态

设置 HEIC 图片解码策略

设置 HEIC 图片降采样

设置图片拉伸

接口说明

initFileCache

preLoad

addHeader

setHeaderOptions

deleteHeader

ImageKnifeComponent

ImageKnifeOption

AnimatorOption