以下将为您介绍如何集成 HarmonyOS 图片编码 SDK。

环境要求

注意事项

• HEIF 编码库为 veImageX 的白名单能力，您需要购买授权使用，购买前您可提交工单联系技术支持为您开通购买白名单。

• Grid 编码不支持编码带有 alpha 通道的图片。如需正常编码带有 alpha 通道的图片，请关闭 Grid 编码。

• 编码前原图支持以下格式：

  • 像素数据：YUV、YUVA、RGB、RGBA

  • 本地图片：建议为 jpeg、png、webp 等系统原生解码支持良好的图片格式

集成准备

获取 Token

1. 登录 veImageX 控制台。

2. 单击左侧导航栏的应用管理，进入应用管理页面。

3. 单击您的 APP 应用卡片，进入应用详情页。

4. 在基本信息区域，单击查看 Token按钮，获取账号唯一的 Token 值。

购买授权

1. 在 APP 应用中的 License 授权区域，单击购买授权按钮。

2. 在购买弹窗中，SDK 类型选择客户端 HEIF 库，根据实际需要购买所需授权。版本类型中请选择带有 HEIF 编码的版本。调试期间，建议您购买免费试用版授权。

   说明

   • 每个账号仅支持购买一次可免费一个月的试用版授权，不支持重复购买。

   • 定制版授权支持多种时长方案，可根据您的多应用场景（不同应用名称）选择购买多个授权（License），具体定价详情请联系我们。

   

3. 绑定您的鸿蒙包名，绑定完成后，veImageX 将为您自动签发授权码。

4. Lincense 签发完成后，单击操作列的下载授权码按钮，下载授权码至本地。

   

获取 SDK 最新版本

请参考版本发布历史，获取 SDK 最新版本信息。

添加依赖

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_heifencoder": "0.0.4-tob",
       // 添加鉴权库依赖
       "@imagex/imagex_authorization": "0.0.4-tob",
   }
   

配置鉴权

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

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

接口说明

编码类

将图像文件或像素数据转换为 HEIF 数据。

• 通过给定的图片文件 URI 和配置参数将图像文件转换为 HEIF 数据；

• 直接将像素数据转换为 HEIF 数据，并且有同步和异步两种版本的像素数据转换方法。

  • 同步场景：适用于少量像素数据的编码场景

  • 异步场景：适用于大规模和耗时较高的编码场景

# HeifEncoder

class EncodeErrorPair {
  errCode: number; //错误码
  errMsg: string;  //错误描述
}

/**
 * 将指定 URI 的本地图像文件转换为 HEIC 格式数据。
 * @note 转换过程依赖于系统的解码能力，系统能够正常解码的图片格式即可使用该接口完成编码。
 * @param fileUri 图片存储 URI
 * @param config 本地存储文件编码配置
 * @returns 若转码失败则返回 EncodeErrorPair，表示错误码和错误描述；若转码成功则返回 ArrayBuffer，表示 heic 数据。
 */
static async imageFileToHeifWithConfigAsync(
  fileUri: string,
  config: BDEncoderLocalPicConfig,
  alpha: boolean | null = null
): Promise<ArrayBuffer | EncodeErrorPair>

/**
 * 【同步】将指定的像素数据(RGBA、RGB、YUV、YUVA)转换为 HEIC 格式数据。
 * @param config 像素文件编码配置。
 * @returns 若转码失败则返回 EncodeErrorPair，表示错误码和错误描述；若转码成功则返回 ArrayBuffer，表示 heic 数据。
 */
static pixelsToHeifWithConfig(config: BDEncoderConfig): ArrayBuffer | EncodeErrorPair 

/**
 * 【异步】将指定的像素数据(RGBA、RGB、YUV、YUVA)转换为 HEIC 格式数据。
 * @param config 像素文件编码配置。
 * @returns 若转码失败则返回 EncodeErrorPair，表示错误码和错误描述；若转码成功则返回 ArrayBuffer，表示 heic 数据。
 */
static async pixelsToHeifWithConfigAsync(config: BDEncoderConfig): Promise<ArrayBuffer | EncodeErrorPair>

编码配置类

• 本地存储图片编码配置类

  # BDEncoderLocalPicConfig
  
  // 设置编码档位
  export enum EncodePreset {
    FAST = 0,
    SLOW = 1
  }
  
  /**
   * 针对存储在 veImageX 服务的图片文件的编码配置类
   */
  export declare class BDEncoderLocalPicConfig {
      /**
       * BDEncoderLocalPicConfig 针对本地图片文件的编码配置类
       * @param quality 编码质量，取值范围[1,100]，值越大，压缩率越高，图像越模糊。
       * @param useGrid 是否开启 Grid 编码，开启后会使编码图片时会使用更少的内存完成编码
       * @param preset 编码档位，"EncodePreset.FAST" 表示编码压缩率低速度快，"EncodePreset.SLOW"表示编码压缩率高速度慢
       */
      constructor(quality: number, useGrid: boolean, preset: EncodePreset);
  }
  

• 像素文件编码配置类

  # BDEncoderConfig 
  
  // 编码格式
  export enum EncodeFormat {
    RGBA = 0,
    RGB = 1,
    YUV = 2,
    YUVA = 3
  }
  
  /**
   * BDEncoderConfig 针对 YUVA、YUV、RGBA、RGB 文件的编码配置类
   * @param pixelData 像素数据（YUVA、YUV、RGBA、RGB数据）
   * @param width 编码宽
   * @param height 编码高
   * @param quality 编码质量，取值范围[1,100]，值越大，压缩率越高，图像越模糊。
   * @param hasAlpha 编码是否有 alpha  透明通道
   * @param useGrid 是否开启 Grid 编码，开启后会使编码图片时会使用更少的内存完成编码
   * @param preset 编码档位，"EncodePreset.FAST" 表示编码压缩率低速度快，"EncodePreset.SLOW"表示编码压缩率高速度慢
   * @param format 编码格式（EncodeFormat.RGBA、EncodeFormat.RGB、EncoderFormat.YUV、EncoderFormat.YUVA）
   * @param exifData 图片的 exif 信息
   */
  constructor(pixelData: Uint8Array | null,
    width: number, height: number, quality: number,
    hasAlpha: boolean | null = null,
    useGrid: boolean = false,
    preset: EncodePreset = EncodePreset.FAST,
    format: EncodeFormat = EncodeFormat.RGBA,
    exifData: Uint8Array | null = null)
  

Exif 类

# ExifUtils // 提取 exif 数据的工具类

/**
 * 获取常规图片的 exif 信息（仅支持：WebP、PNG、JPEG、HEIC）
 * @param imgData 图片数据
 * @returns 图片 exif 信息，获取不到则返回 null
 */
static getExifInfoFromNormalImgData(imgData: Uint8Array): Uint8Array | null

/**
 * 获取常规图片的 exif 信息（仅支持：WebP、PNG、JPEG、HEIC）
 * @param filePath 图片路径
 * @returns 图片 exif 数据，获取不到则返回 null
 */
static getExifInfoFromNormalImgFile(filePath: string): Uint8Array | null

/**
 * 获取 Webp 图片 exif 信息
 * @param webpData webp 图片字节数据
 * @returns 图片 exif 数据的 byte 数组
 */
static getExifInfoFromWebPData(webpData: Uint8Array): Uint8Array | null

/**
 * 获取 PNG 图片的 exif 信息
 * @param pngData PNG 图片字节数据
 * @returns 图片 exif 数据的 byte 数组
 */
static getExifInfoFromPngData(pngData: Uint8Array): Uint8Array | null

/**
 * 获取 JPEG 图片 exif 信息
 * @param jpegData JPEG 图片字节数据
 * @returns 图片 exif 数据的 byte 数组
 */
static getExifInfoFromJpegData(jpegData: Uint8Array): Uint8Array | null

/**
 * 获取 Heic 图片 exif 信息
 * @param heicData Heic 图片字节数据
 * @returns 图片 exif 数据的 byte 数组
 */
static getExifInfoFromHeicData(heicData: Uint8Array): Uint8Array | null

Demo 介绍

veImageX 提供了封装好的编码 App，您可以直接运行，以帮助您快速实现业务需求，节约您的开发时间和成本。您可在 App 中体验图片编码各种功能能力，并根据自身业务需求进行针对性的调试和使用。

HMTestNew.zip

161.53KB