更新记录

1.0.0（2026-10-31）

• 首个版本，仅支持 App-Android（minSdkVersion 21）
• 新增 combiner：jpg + mp4 合成实况照片（XMP 采用小米 MicroVideo 写法，华为/荣耀机型自动追加 60 字节尾部信息）
• 新增 split：实况照片分离为静态 jpg 与 mp4，按「华为尾部 -> 小米 MicroVideoOffset -> Google XMP Item Length -> ftyp 扫描」四级识别
• 新增 requestPermissions / checkAllFilesPermission / toAllFilesPermissionPage 存储权限辅助方法
• 所有方法统一 { params, success, fail, complete } 形态，回调结构为 { code, data, message }
• 支持普通路径、file:// 前缀与 content://（后者复制到应用缓存目录）

平台兼容性

uni-app(4.72)

uni-app x(4.72)

zy-livePhoto

实况照片（Motion Photo）合成与分离 UTS 插件，仅支持 Android（uni-app / uni-app x）。

插件能力

• combiner：把一张 jpg 图片 + 一段 mp4 视频合成实况照片（jpg 内写入 XMP 元数据，尾部追加 mp4 数据）
• split：把实况照片分离成静态 jpg 与 mp4 视频
• requestPermissions / checkAllFilesPermission / toAllFilesPermissionPage：存储权限辅助方法

兼容性

合成结果的 XMP 采用小米 GCamera:MicroVideo 写法（同时写入 Google MotionPhoto Container 字段），国内相册（小米/OPPO/vivo/华为）与 Google Photos 均可识别；在华为/荣耀机型上会自动追加 60 字节尾部信息（v2_f29 + 207:1000 + LIVE_<长度>）以兼容其系统相册。

分离支持 4 级识别策略，依次为：

1. 华为尾部信息（最后 40 字节内的 LIVE_<长度>）
2. 小米 GCamera:MicroVideoOffset
3. Google Container:Item 的 Item:Length（MotionPhoto 语义）
4. 按 ftyp 标记兜底扫描

快速开始

import { combiner, split } from '@/uni_modules/zy-livePhoto'

combiner({
  params: {
    imagePath: '/storage/emulated/0/DCIM/xxx.jpg',
    videoPath: '/storage/emulated/0/DCIM/xxx.mp4'
  },
  complete: (res) => {
    if (res.code == 0) {
      console.log('合成结果', res.data.path)
    } else {
      console.log('失败', res.code, res.message)
    }
  }
})

split({
  params: { path: '/storage/emulated/0/DCIM/xxxMP.jpg' },
  complete: (res) => {
    if (res.code == 0) {
      console.log(res.data.imagePath, res.data.videoPath, res.data.method)
    }
  }
})

API

所有方法都接收 { params, success, fail, complete }，三个回调都收到同一结构：

type ZyLivePhotoResult = {
  code: number      // 0 成功，其他为错误码
  data: UTSJSONObject
  message: string
}

requestPermissions

data：{ type: 'onGranted' | 'onDenied', allGranted: boolean, permissions: string[], deniedPermissions: string[] }

注意：申请是异步的，data 反映的是发起弹窗那一刻的授予状态，弹窗结果请在页面 onShow 时再调用一次本方法或 checkAllFilesPermission 获取。

checkAllFilesPermission

无参数，data：{ status: boolean }

toAllFilesPermissionPage

无参数，data：{ status: boolean }（跳转时刻的权限状态；建议 onShow 时重新检查）

combiner

data：{ path: string }（合成后的文件路径）

split

data：{ imagePath: string, videoPath: string, method: string }（method 为识别方式，便于排查）

权限说明

• 输出到默认目录（App 私有外部目录）无需任何权限；
• 输出到公共目录（如 /storage/emulated/0/DCIM）需要：
  • Android 10 及以下：WRITE_EXTERNAL_STORAGE / READ_EXTERNAL_STORAGE（用 requestPermissions 申请）
  • Android 11+：MANAGE_EXTERNAL_STORAGE（运行时弹窗无法授予，需 toAllFilesPermissionPage 引导用户到系统页面开启）

错误码

已知限制

• imagePath / videoPath 支持普通路径、file:// 前缀与 content://（后者会先复制到应用缓存目录）；
• 合成后的实况照片请用「相册」类应用查看效果，HBuilderX 预览无法播放。