更新记录

1.0.1（2026-08-23）

完善安卓端插件内部逻辑。

1.0.0（2026-08-23）

初始化版本发布。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

概述

ZF-livePhotoUTS 是 iOS Live Photo、Android Motion Photo 与 HarmonyOS MovingPhoto 合成/分离 UTS 插件，支持将图片和视频合成为动态照片，并返回图片、视频及动态照片文件路径。插件不采集数据，不依赖第三方 SDK。

使用前提

iOS

• iOS 12 及以上系统。
• 在宿主工程中声明相册读写权限：NSPhotoLibraryUsageDescription、NSPhotoLibraryAddUsageDescription。
• 合成输入使用本地图片路径和 MOV 视频路径；支持 file:// 路径。
• 插件会在调用时主动申请对应相册权限：合成使用添加权限，分离使用读写权限。

Android

• Android 5.0（API 21）及以上。
• auto 会优先按设备厂商选择协议：华为/荣耀使用 Huawei Moving Photo，其他未适配厂商使用 Google Motion Photo。
• 也可以在 format 中显式指定 google、huawei、xiaomi、oppo 或 vivo。
• 业务场景推荐始终传 format: 'auto'；显式厂商值仅用于协议调试、回归测试或强制覆盖设备自动判断，前端不需要让用户选择厂商。
• HEIF/AVIF 还必须通过设备编码器和 Motion Photo 容器能力检查；当前能力不足时会回退到标准 JPEG Motion Photo，并通过 fallback: true 标记。
• JPEG Motion Photo 使用 JPEG APP1 XMP + MP4(H.264/AAC) 追加结构，输出文件名为 *.MP.jpg。
• Huawei/Honor Android 使用原生单文件结构：JPEG + MP4 + 60 字节 ASCII v6_f.../LIVE_... 尾标，输出文件名为 *.live.jpg；这与 HarmonyOS MovingPhoto 媒体资产是两套实现。
• Xiaomi 使用 MVIMG_*.jpg 命名的标准 Motion Photo 单文件结构。
• OPPO/OnePlus 使用 OpCamera XMP 和 oplus_10485792 EXIF UserComment 标记，输出 OLIVE_*.jpg。
• vivo/iQOO 输出同名 IMG_LP_*.jpg + IMG_LP_*.mp4 双文件，回调中的 requiresPairing 为 true；最终是否由图库显示为实况仍取决于 OriginOS/图库版本。
• Android 6–9（API 23–28）需要宿主清单声明 READ_EXTERNAL_STORAGE、WRITE_EXTERNAL_STORAGE，插件会在合成前申请运行时权限，并将结果写入公共 Pictures/Motion Photos 目录后触发媒体扫描。
• Android 5（API 21–22）直接写入公共 Pictures/Motion Photos 目录并触发媒体扫描；Android 10 及以上通过 MediaStore 发布，motionPhotoPath 通常为 content://。

HarmonyOS

• HarmonyOS API 12 及以上，并使用支持 MediaLibraryKit MovingPhoto 的宿主工程。
• 宿主工程需要声明 ohos.permission.READ_IMAGEVIDEO、ohos.permission.WRITE_IMAGEVIDEO；插件调用时会申请对应运行时权限。
• 合成输入使用应用沙箱内的本地文件路径或 file:// URI，图片支持 JPEG、HEIF；鸿蒙使用系统 MovingPhoto 资产，不生成 Android JPEG/XMP 结构。
• HarmonyOS 合成结果的 motionPhotoPath 和 assetLocalIdentifier 为媒体库 URI；extractLivePhoto 使用该 URI 精确分离。
• extractMotionPhoto 在 HarmonyOS 返回不支持错误。

插件接口

createLivephoto

按队列将普通图片保存到相册，或将图片与视频合成为 Live Photo 并保存到相册。

uni-app项目中（nvue）调用示例：

import { createLivephoto } from '@/uni_modules/ZF-livePhotoUTS'

createLivephoto([
  { type: 1, images: '/var/mobile/input.jpg', thumbnail_path: '/var/mobile/input.jpg', video_path: '/var/mobile/input.mov', format: 'auto' }
], (result) => {
  console.log(result)
})

uni-app x项目（uvue）中调用示例：

import { createLivephoto } from '@/uni_modules/ZF-livePhotoUTS'
import { LivePhotoItem } from '@/uni_modules/ZF-livePhotoUTS/utssdk/interface.uts'

let item = {
  type: 1,
  images: '',
  thumbnail_path: '',
  video_path: ''
} as LivePhotoItem
createLivephoto([item], (res : any) => { console.log(res) })

可用性

iOS、Android、HarmonyOS 系统，可提供的插件 1.0.0 及更高版本。HarmonyOS 使用系统 MovingPhoto 资产；Android 返回中的 format 是实际文件格式，requestedFormat 是请求策略，fallback 表示是否回退到 JPEG。

extractorLivephoto

读取系统相册中按创建时间最近的一张 Live Photo，并返回分离后的图片与视频本地路径。调用方可继续使用 uni.saveImageToPhotosAlbum、uni.saveVideoToPhotosAlbum 保存副本。

uni-app项目中（nvue）调用示例：

import { extractorLivephoto } from '@/uni_modules/ZF-livePhotoUTS'

extractorLivephoto((result) => {
  console.log(result.imagePath, result.videoPath)
})

uni-app x项目（uvue）中调用示例：

import { extractorLivephoto } from '@/uni_modules/ZF-livePhotoUTS'

extractorLivephoto((res : any) => { console.log(res) })

可用性

iOS、Android、HarmonyOS 系统，可提供的插件 1.0.0 及更高版本。读取相册前需由宿主工程申请相册权限；HarmonyOS 查询 MovingPhoto 媒体资产，Android 优先查询 MediaStore 中最近的 *.MP.jpg、*.live.jpg、MVIMG_*.jpg、OLIVE_*.jpg 或 IMG_LP_*.jpg。

extractMotionPhoto

按指定路径分离 Android Motion Photo，支持普通文件路径、file:// 和 content:// URI。

uni-app项目中（nvue）调用示例：

import { extractMotionPhoto } from '@/uni_modules/ZF-livePhotoUTS'

extractMotionPhoto('content://media/external/images/media/123', (result) => {
  console.log(result.imagePath, result.videoPath)
})

uni-app x项目（uvue）中调用示例：

import { extractMotionPhoto } from '@/uni_modules/ZF-livePhotoUTS'

extractMotionPhoto('', (res : any) => { console.log(res) })

可用性

Android 系统，可提供的 Android 5.0（API 21）及更高版本。iOS、HarmonyOS 系统返回不支持错误。

extractLivePhoto

按 iOS Photos 的 assetLocalIdentifier 或 HarmonyOS 媒体库 URI 精确分离指定动态照片。

uni-app项目中（nvue）调用示例：

import { extractLivePhoto } from '@/uni_modules/ZF-livePhotoUTS'

extractLivePhoto('asset-local-identifier', (result) => {
  console.log(result.imagePath, result.videoPath, result.assetLocalIdentifier)
})

uni-app x项目（uvue）中调用示例：

import { extractLivePhoto } from '@/uni_modules/ZF-livePhotoUTS'

extractLivePhoto('', (res : any) => { console.log(res) })

可用性

iOS、HarmonyOS 系统，可提供的插件 1.0.0 及更高版本；HarmonyOS 参数使用媒体库 URI，iOS 参数使用 Photos assetLocalIdentifier。Android 系统返回不支持错误。

回调结果

• success：本次操作是否成功。
• imagePath、videoPath：合成或分离后的配对资源路径。
• currentIndex、totalCount、successCount、failCount：批量合成进度。
• error：失败时的中文错误信息。
• motionPhotoPath：Android Motion Photo 或 HarmonyOS MovingPhoto 媒体库 URI。
• protocol：实际使用的协议，例如 google、huawei。
• files：实际生成的文件列表；Huawei 单文件结果只包含一个路径。
• requiresPairing：是否需要图片与视频双文件配对；Android vivo 为 true，其他当前协议为 false。
• manufacturer：Android 检测到的设备厂商。
• format：实际写入格式；Android 基线为 jpeg，HarmonyOS 由输入图片决定为 jpeg 或 heif。
• requestedFormat：调用方传入的 auto、google、huawei、xiaomi、oppo、vivo、jpeg、heif 或 avif。
• fallback：请求格式因系统/编码器能力不足而回退时为 true。
• assetLocalIdentifier：iOS Photos 资产标识或 HarmonyOS 媒体库 URI，可用于后续精确分离。