更新记录

1.0.1（2026-01-14）

调整

1.0.0（2026-01-14）

新增功能

• ✅ 支持 HEIC/HEIF 格式图片转换为 JPG
• ✅ 支持 HEIC/HEIF 格式图片转换为 PNG
• ✅ 支持自定义 JPG 质量参数
• ✅ Android 平台完整实现
• ✅ 支持 Android 5.0+ (API 21+)，自动降级处理
• ✅ 集成 libheif 库支持 Android 9.0 以下版本
• ✅ 支持自动生成临时文件路径（类似 uni.compressImage，outputPath 可选）

平台支持

• ✅ Android 9.0+ (API 28+): 完全支持，使用系统原生 ImageDecoder API（零依赖）
• ✅ Android 5.0-8.1 (API 21-27): 完全支持，使用 libheif 库（需要添加依赖）

技术改进

• ✅ 实现版本检测和自动降级策略
• ✅ Android 9.0+ 使用系统 API，零依赖，性能最佳
• ✅ Android 9.0 以下使用 libheif 库，通过反射调用，无需直接依赖
• ✅ 自动检测 libheif 是否可用，提供友好的错误提示

平台兼容性

uni-app(4.66)

uni-app x(4.66)

xun-heic-converter

HEIC/HEIF 图片格式转换为 JPG/PNG 格式的 UTS 插件，支持 Android 平台。

UTS环境兼容性

功能特性

• ✅ HEIC/HEIF 格式图片解码
• ✅ 转换为 JPG 格式
• ✅ 转换为 PNG 格式
• ✅ 支持自定义图片质量（JPG）
• ✅ 支持自定义输出路径
• ✅ 基于 Android ImageDecoder（API 28+），性能优异

安装使用

1. 导入插件

将 xun-heic-converter 目录放入项目的 uni_modules 目录；App 端支持 Android（iOS 暂不支持）。

2. 平台要求

• Android: 最低 SDK 版本 21 (Android 5.0+)
  • Android 9.0+ (API 28+): 完全支持，使用系统原生 API（零依赖）
  • Android 9.0 以下: 需要集成 libheif 库才能支持 HEIC 解码（见下方配置说明）
• HBuilderX: 3.6+ (uni-app) / 3.9+ (uni-app x)

2. 快速使用

// #ifdef APP-PLUS-ANDROID
import { convertHeicToJpg, convertHeicToPng } from '@/uni_modules/xun-heic-converter'

// 方式 1：自动生成临时文件路径（推荐，类似 uni.compressImage）
const result = convertHeicToJpg({
  inputPath: '/path/to/image.heic',
  quality: 90  // 可选，1-100，默认 90
})

if (result.code == 0) {
  console.log('转换成功，临时文件路径:', result.data.outputPath)
  // result.data.outputPath 是自动生成的临时文件路径
  // 类似 uni.compressImage 返回的 tempFilePath
} else {
  console.error('转换失败:', result.data.error)
}

// 方式 2：指定输出路径
const result2 = convertHeicToJpg({
  inputPath: '/path/to/image.heic',
  outputPath: '/path/to/output.jpg',  // 指定输出路径
  quality: 90
})

// 转换为 PNG（同样支持自动生成临时文件路径）
const result3 = convertHeicToPng({
  inputPath: '/path/to/image.heic'
  // 不提供 outputPath，会自动生成临时文件路径
})

if (result3.code == 0) {
  console.log('转换成功，临时文件路径:', result3.data.outputPath)
}
// #endif

API 文档

convertHeicToJpg(options)

将 HEIC/HEIF 图片转换为 JPG 格式（同步方法）。

参数说明：

• options: ConvertOptions
  • inputPath: string - 输入文件路径（必填）
  • outputPath?: string - 输出文件路径（可选，不提供时自动生成临时文件路径）
  • quality?: number - JPG 质量，1-100，默认 90（可选）

返回值：

• ConvertResult - 转换结果对象
  • code: number - 0 表示成功，非 0 表示失败
  • data: UTSJSONObject - 结果数据
  • outputPath: string - 输出文件路径（成功时，类似 uni.compressImage 的 tempFilePath）
  • error: string - 错误信息（失败时）

示例：

// 自动生成临时文件路径（推荐）
const result = convertHeicToJpg({
  inputPath: '/storage/emulated/0/DCIM/image.heic',
  quality: 95
})
// result.data.outputPath 是自动生成的临时文件路径，位于应用缓存目录

// 指定输出路径
const result2 = convertHeicToJpg({
  inputPath: '/storage/emulated/0/DCIM/image.heic',
  outputPath: '/storage/emulated/0/DCIM/image.jpg',
  quality: 95
})

convertHeicToPng(options)

将 HEIC/HEIF 图片转换为 PNG 格式（同步方法）。

参数说明：

• options: ConvertOptions
  • inputPath: string - 输入文件路径（必填）
  • outputPath?: string - 输出文件路径（可选，不提供时自动生成临时文件路径）

返回值：

• ConvertResult - 转换结果对象（格式同 convertHeicToJpg）

示例：

// 自动生成临时文件路径（推荐）
const result = convertHeicToPng({
  inputPath: '/storage/emulated/0/DCIM/image.heic'
})
// result.data.outputPath 是自动生成的临时文件路径

// 指定输出路径
const result2 = convertHeicToPng({
  inputPath: '/storage/emulated/0/DCIM/image.heic',
  outputPath: '/storage/emulated/0/DCIM/image.png'
})

使用示例

完整示例（自动生成临时文件路径）

<template>
  <view>
    <button @click="handleConvert">转换 HEIC 图片</button>
    <text v-if="result">{{ result }}</text>
  </view>
</template>

<script>
// #ifdef APP-PLUS-ANDROID
import { convertHeicToJpg } from '@/uni_modules/xun-heic-converter'
// #endif

export default {
  data() {
    return {
      result: ''
    }
  },
  methods: {
    handleConvert() {
      // #ifdef APP-PLUS-ANDROID
      // 不提供 outputPath，自动生成临时文件路径（类似 uni.compressImage）
      const result = convertHeicToJpg({
        inputPath: '/storage/emulated/0/DCIM/image.heic',
        quality: 90
      })

      if (result.code == 0) {
        // result.data.outputPath 是自动生成的临时文件路径
        // 类似 uni.compressImage 返回的 tempFilePath
        this.result = '转换成功，临时文件: ' + result.data.outputPath

        // 可以使用这个临时文件路径进行后续操作，如上传、显示等
        // 注意：临时文件位于应用缓存目录，应用卸载或清理缓存时会被删除
      } else {
        this.result = '转换失败: ' + result.data.error
      }
      // #endif
    }
  }
}
</script>

指定输出路径示例

// #ifdef APP-PLUS-ANDROID
import { convertHeicToJpg } from '@/uni_modules/xun-heic-converter'

// 指定输出路径
const result = convertHeicToJpg({
  inputPath: '/storage/emulated/0/DCIM/image.heic',
  outputPath: '/storage/emulated/0/DCIM/image.jpg',  // 指定输出路径
  quality: 90
})
// #endif

平台支持

技术实现

• Android 9.0+: 使用系统自带的 ImageDecoder API 进行 HEIC 解码，然后使用 Bitmap.compress() 方法编码为 JPG/PNG 格式（零依赖，性能最佳）
• Android 9.0 以下: 使用阿里云提供的 libheif 库进行 HEIC 解码（需要添加依赖，见配置说明）
• 自动降级: 插件会自动检测 Android 版本和 libheif 库是否可用，选择最优的解码方案
• 性能: Android 9.0+ 基于系统原生 API，性能优异；libheif 库针对 ARM 平台进行了优化，解码效率高

libheif 库说明

本插件使用阿里云提供的 libheif 库（com.aliyun:libheif:1.0.0），该库基于开源的 libheif 和 libde265 进行优化：

• ✅ 针对 ARM 平台进行了性能优化
• ✅ 支持 Android 5.0+ (API 21+)
• ✅ 解码效率高，内存占用合理
• ⚠️ 会增加约 2-5MB 的应用体积

注意：

• Android 9.0+ 设备会自动使用系统原生 API，无需 libheif 依赖
• 如果未添加 libheif 依赖，Android 9.0 以下设备会返回友好的错误提示，引导用户配置依赖

注意事项

1. 文件路径: 确保应用有读写文件的权限
2. 文件格式: 输入文件必须是有效的 HEIC/HEIF 格式
3. 输出路径:
   • 自动生成临时文件路径（推荐）：不提供 outputPath 时，会自动在应用缓存目录生成临时文件，类似 uni.compressImage 的行为
   • 指定输出路径：提供 outputPath 时，确保输出目录存在，否则转换会失败
4. 临时文件：自动生成的临时文件位于应用缓存目录，应用卸载或清理缓存时会被删除，建议及时使用或移动到其他位置
5. 内存: 大尺寸图片转换时可能占用较多内存，建议在后台线程处理

参考资源

• Android ImageDecoder 文档
• libheif 官方文档