更新记录

1.0.0（2026-08-24）

• 首次发布实况影像处理能力，支持 iOS Live Photo 与 Android 实况图。
• 支持从系统相册读取实况图，并分离获取封面图片和动态视频。
• 支持普通视频转实况图、实况图转普通视频。
• 支持将转换结果写入系统相册，已适配的系统和品牌可识别为实况照片。
• 提供原生实况播放组件，支持加载、播放、停止和重新加载。
• 苹果 iOS 已通过实况图读取、互转、播放、写入和系统相册识别真机验收。
• Android 新增品牌自动适配，vivo、小米、荣耀、OPPO 和一加已通过对应品牌真机相册识别与播放验收。
• 未列出的 Android 品牌默认使用 Google 标准兼容模式。
• 支持 uni-app x App 与 uni-app App nvue，覆盖 Android 5.0 及以上、iOS 14 及以上。
• 媒体资源全程在设备本地处理，不上传、不采集用户数据。

平台兼容性

uni-app(3.8.2)

uni-app x(3.8.2)

其他

实况图互转与相册识别

kongbai-live-photo 是一款面向 App 端的实况影像处理插件，覆盖实况图读取、图片与视频分离、实况播放、视频转实况图、实况图转普通视频以及系统相册写入。

插件针对不同系统和品牌相册进行独立适配。当前已在 苹果 iOS、vivo、小米、荣耀、OPPO 和一加 真机上完成读取、互转、播放、写入与系统相册识别验收。

核心能力

• 读取实况图：从系统相册选择实况图，获取封面图片与动态视频资源。
• 分离实况资源：将实况图拆分为可独立使用的图片和普通视频。
• 视频转实况图：将本地视频转换为 iOS Live Photo 或 Android 实况图。
• 实况图转视频：从实况图中导出可播放、可分享的普通视频。
• 写入系统相册：转换结果可保存到系统相册，已适配的系统和品牌可直接识别为实况照片。
• 原生实况播放：内置实况播放组件，支持加载、播放、停止和重新加载。
• 全程本地处理：媒体资源仅在用户设备上处理，不上传、不采集，不依赖业务服务器。

平台支持

真机兼容

真机验收结果以当前已测设备为准。同一品牌的不同机型、系统版本或相册版本可能存在差异，正式上线前建议使用目标机型进行回归测试。

Android 自动适配

auto 是推荐选择。插件会先识别当前设备品牌，优先使用对应品牌的独立适配；仅在品牌方案无法完成时，才尝试通用 Google 标准兼容模式。

Redmi、POCO、realme 和 iQOO 会按所属品牌路线自动处理；未列出的 Android 设备会自动使用 Google 标准兼容模式。通用模式的最终实况识别效果取决于目标设备的系统相册支持情况。

快速接入

选择并读取实况图

import { ChooseKBPhoto } from '@/uni_modules/kongbai-live-photo'

ChooseKBPhoto(null, (result) => {
  console.log('image:', result.imagePath)
  console.log('video:', result.videoPath)
  console.log('isLivePhoto:', result.isLivePhoto)
  console.log('isMotionPhoto:', result.isMotionPhoto)
}, (error) => {
  console.log(error.code, error.message)
})

选择成功后，imagePath 和 videoPath 可分别用于预览、编辑、上传或后续业务处理。

视频转实况图并写入相册

import {
  ConvertKBVideoToLivePhoto,
  SaveKBMediaToAlbum
} from '@/uni_modules/kongbai-live-photo'

ConvertKBVideoToLivePhoto({
  videoPath: videoPath,
  coverTime: 0
}, (result) => {
  SaveKBMediaToAlbum({
    mediaType: result.mediaType,
    imagePath: result.imagePath,
    videoPath: result.videoPath,
    androidProfile: 'auto'
  }, (saved) => {
    console.log('saved:', saved.savedToAlbum)
  }, (error) => {
    console.log(error.code, error.message)
  })
}, (error) => {
  console.log(error.code, error.message)
})

Android 建议始终使用 androidProfile: 'auto'，交由插件自动匹配当前设备。iOS 会自动生成并写入 Live Photo。

实况图转普通视频

import { ConvertKBLivePhotoToVideo } from '@/uni_modules/kongbai-live-photo'

ConvertKBLivePhotoToVideo(null, (result) => {
  console.log('video:', result.outputPath)
}, (error) => {
  console.log(error.code, error.message)
})

播放实况图

<kongbai-live-photo
  style="width: 100%; height: 500rpx;"
  :image-path="imagePath"
  :video-path="videoPath"
  content-mode="aspectFill"
  @load="onLoad"
  @play="onPlay"
  @stop="onStop"
  @error="onError"
/>

播放组件支持 reload()、play() 和 stop() 方法。

主要 API

同时保留小写别名：chooseKBPhoto、chooseKBLivePhoto、convertKBVideoToLivePhoto、convertKBLivePhotoToVideo、saveKBMediaToAlbum 和 getKBLivePhotoSupport。

Android 可选模式

业务接入建议使用 auto。显式指定品牌模式主要用于指定设备或测试场景，不建议在不匹配的品牌设备上强制使用。

权限与隐私

• 所有转换均在设备本地完成。
• 插件不上传、不采集用户照片或视频。
• 只有业务主动调用 SaveKBMediaToAlbum 时，结果才会写入系统相册。
• 用户取消选择、拒绝权限或资源无法读取时，均会返回明确的失败回调。

接入建议

• 首次进入功能页时，可先调用 GetKBLivePhotoSupport() 判断当前设备能力。
• 转换成功只代表已生成本地结果；需要在系统相册中使用时，请继续调用 SaveKBMediaToAlbum。
• 建议保留失败回调并向用户展示友好提示。
• 不同系统版本和相册版本可能存在差异，发布前建议覆盖业务的主要目标机型。