更新记录

1.0.10（2026-07-30）

• 新增 getGalleryMetadata，支持按媒体 ID 批量读取图片 EXIF 与视频标准化元数据。
• 图片元数据支持方向、拍摄时间、相机厂商、相机型号、镜头、ISO、曝光时间、光圈和焦距等字段；视频元数据支持方向、时长、编码格式（codec）、码率（bitrate）和帧率（frameRate）等字段。
• GPS 默认关闭；仅在业务方显式传入 includeLocation=true 时读取位置信息；插件不进行逆地理编码。
• 位置信息不会缓存、记录或上传；元数据缓存仅保存非敏感字段。
• Harmony、Web、微信小程序和支付宝小程序暂不支持元数据读取，调用时明确返回错误码 9070031，不会伪造成功。
• clearGalleryCache 新增 metadata 范围，可单独清理非敏感元数据缓存。
• 修复 iOS 云打包时有限数校验中的 -Infinity 被生成成对 NSNumber 使用一元负号，导致 SwiftCompile 报错的问题。
• iOS 元数据数值校验改用 Number.isFinite，继续过滤 NaN 与正负无穷值，不改变公开 API 和 Android 行为。
• Android 原生实现已变更，升级后需重新制作 Android 自定义基座并安装；仅更新页面资源不能带入本次能力。
• iOS 原生实现与 UTS 生成兼容性已变更，升级后需重新制作 iOS 自定义基座并安装；仅更新页面资源不能带入本次能力和修复。

1.0.9（2026-07-30）

• 修复 HBuilderX 5.15 下 iOS 页面回调被桥接为不同具体闭包类型时，统一动态强转可能造成首次结果回调或精确变化监听闪退的问题；各 API 现在按公开结果类型派发成功、失败、进度和变化回调。
• 修复 iOS 原生缩略图与导出文件仅返回沙盒绝对路径，导致页面不能显示封面或预览的问题；插件现在区分页面缓存路径与原生上传路径。
• uni-app 使用 _doc 页面缓存路径，uni-app x 使用 unifile://cache；原生读写、上传、保存与缓存清理继续使用对应绝对路径。
• 示例页媒体列表支持点击全屏预览：图片先导出完整文件后调用系统图片预览，视频先导出完整文件后进入原生 video 全屏播放器。
• 自动读取列表仅更新选中状态，不会自动弹出全屏；预览准备期间会阻止重复导出，页面离开后不再触发延迟播放。
• 本版修改了 iOS 原生桥接与 UTS 平台实现，发布和真机复验前必须重新原生联编或重新制作 iOS 自定义基座；仅更新页面资源不能带入本次原生修复。

1.0.8（2026-07-29）

• 修复 iOS 云打包时精确相册监听的 fail 回调使用协议型参数，导致 Swift 无法推断闭包参数类型的问题。
• 修复 PHAuthorizationStatus.limited 未完全隔离到 iOS 14 可用域，导致最低支持 iOS 12 时的 Swift availability 编译错误。
• 本次仅调整 iOS 生成兼容性，不改变公开 API、回调语义和 Android 行为；升级后需重新原生联编或制作 iOS 自定义基座。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-gallery-pro

lizhao-gallery-pro 是面向 uni-app / uni-app x 的相册媒体 UTS 插件，授权后可读取系统相册图片和视频，并提供分页、筛选、缩略图、导出临时文件、批量保存到系统相册、来源分类和上传辅助。

联系方式：信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

功能特色

• 相册变化实时监听：Android 与 iOS 原生监听系统相册变化，支持防抖、多监听器和回到前台后的补偿刷新。

• 批量保存到系统相册：将业务生成或插件导出的本地图片、视频按输入顺序保存到默认或自定义相册，并返回逐项进度和明细。	能力	解决的问题	对应 API
  图片、视频、混合列表	不弹系统选择器，授权后直接读取相册媒体列表	getGalleryImages / getGalleryVideos / getGalleryMedia
  分页读取	大图库不会一次性塞满内存，可用 nextPageToken 循环读取下一页	pageSize / pageToken
  时间筛选	只读取最近一天、最近一周或指定时间段内的媒体	startTime / endTime
  来源分类	识别相机、截图、微信、QQ、下载等来源，方便做相册入口和筛选	sourceType / sourceLabel
  相册分组	返回相册数量、图片/视频数量、封面和最新媒体信息	getGalleryAlbums
  缩略图	列表先显示小图，减少原图加载压力	getGalleryThumbnails
  临时文件导出	把系统媒体导出成页面可显示、接口可上传的路径	exportMediaToTempFile
  上传辅助	内置导出、上传、dry-run 校验、进度、重试和结果顺序对齐	uploadGalleryMedia
  批量保存	把本地图片、视频混合批量写入系统默认或自定义相册，可选择跳过可见重复项	saveMediaToGallery
  隐私安全的元数据	按媒体 ID 批量读取图片 EXIF、视频参数，并由调用方显式决定是否读取位置	getGalleryMetadata
  缓存清理	缩略图、导出、增量游标和非敏感元数据缓存可以分开清理	clearGalleryCache
  能力矩阵	先判断平台能力，再决定是否展示业务入口	getGalleryCapabilities

适合哪些场景

• 社区发帖、评价晒单、工单上报，需要从相册读取图片或视频。
• 素材库、云盘、相册备份，需要分页读取大量本地媒体。
• 内容审核、巡检记录、设备报修，需要按相机、截图、微信、QQ、下载等来源做分类。
• 自定义相册选择器，需要自己做 UI、分页、封面、预览和上传。
• iOS 页面需要稳定显示相册图片，不能直接依赖不可访问的原始资产路径。
• 上传前需要先生成可上传路径，或用 dryRun=true 在无服务端时验证导出链路。

接入方式怎么选

最小示例

import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'

// 第一步：先检查权限。success / fail / complete 都会按调用结果触发。
GalleryPro.checkGalleryPermission({
  mediaType: 'all',
  success(res) {
    console.log('相册权限状态', res.status, res.message)
    if (!res.granted) {
      // 第二步：未授权时再请求权限，避免一进页面就打扰用户。
      GalleryPro.requestGalleryPermission({
        mediaType: 'all',
        success(auth) {
          console.log('授权结果', auth.granted, auth.status)
        }
      })
    }
  },
  fail(err) {
    console.log('权限检查失败', err.errCode, err.errMsg)
  }
})

媒体元数据最小示例

先从列表取得稳定媒体 ID，再按需读取单项元数据。GPS 默认关闭，只有把 includeLocation 显式设为 true 才会读取位置。

import { getGalleryMetadata } from '@/uni_modules/lizhao-gallery-pro'

getGalleryMetadata({
  ids: ['media-id-1'],
  // 不传 includeLocation，默认 false，不读取敏感位置。
  success(res) {
    console.log('媒体元数据读取结果', res.success, res.items[0].message)
  },
  fail(err) {
    console.log('元数据批次无法启动', err.errCode, err.errMsg)
  }
})

批量读取允许部分成功，items 始终与 ids 输入顺序一致；每处理完一项会触发一次 progress。

import { getGalleryMetadata } from '@/uni_modules/lizhao-gallery-pro'

getGalleryMetadata({
  ids: ['media-id-1', 'media-id-2'],
  includeExif: true,
  includeLocation: false,
  progress(event) {
    console.log('元数据进度', event.current, event.total, event.successCount, event.failCount)
  },
  success(res) {
    console.log('成功数、失败数', res.successCount, res.failCount)
    res.items.forEach((item, index) => {
      console.log('输入序号与媒体ID', index, item.id, item.success, item.message)
    })
  },
  fail(err) {
    console.log('元数据批次无法启动', err.errCode, err.errMsg)
  }
})

getGalleryMetadata(options)

按稳定媒体 ID 批量读取标准化元数据。支持 uni-app 与 uni-app x 的 Android / iOS；批次启动后允许单项失败，最终仍通过 success 返回有序明细。

参数

GalleryMetadataResult

GalleryMetadataProgress

GalleryMetadataItem

GalleryMediaLocation

图片与视频字段差异

隐私与缓存

• GPS 默认关闭；includeLocation 只有显式为 true 时才读取位置。
• 不进行逆地理编码，不把坐标转换成地址。
• Android / iOS 均使用系统公开 API 在本地解析；插件不发起网络请求；iCloud-only 资源在本地不可用时可能单项失败。
• 不上传、不记录、不持久化位置；调用方也不应把位置写入日志。
• 非敏感 metadata 缓存只包含 schemaVersion / id / mediaType / modifiedTime / width / height / durationMs / orientation / captureTime / cameraMake / cameraModel / lensModel / iso / exposureTime / aperture / focalLength / focalLength35mm / videoCodec / videoBitrate / videoFrameRate。
• 位置每次新鲜读取且不进入缓存；即使 useCache: true 也不会复用位置。

平台与自定义基座

本能力新增 Android 依赖以及 Android / iOS 原生逻辑。发布或使用前，两端都必须重新制作并重新安装与插件代码匹配的自定义基座；只更新普通页面资源不能替代原生联编。

图片列表

import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'

// 读取最新 30 张图片。includeThumbnail=true 会尽量返回缩略图路径。
GalleryPro.getGalleryImages({
  pageSize: 30,
  includeThumbnail: true,
  success(res) {
    console.log('图片总数', res.total)
    console.log('本页图片', res.items)
    console.log('下一页令牌', res.nextPageToken)
  }
})

视频列表

import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'

// 只读取最近 7 天的视频，适合短视频投稿和素材管理。
GalleryPro.getGalleryVideos({
  pageSize: 20,
  startTime: Date.now() - 7 * 24 * 60 * 60 * 1000,
  includeThumbnail: true,
  success(res) {
    console.log('视频列表', res.items)
  }
})

图片视频混合列表示例

import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'

let nextPageToken = ''

function loadMixedPage() {
  // mediaType='all' 表示图片视频混合列表；pageToken 为空时读取第一页。
  GalleryPro.getGalleryMedia({
    mediaType: 'all',
    pageSize: 40,
    pageToken: nextPageToken,
    sourceType: 'all',
    sortOrder: 'desc',
    success(res) {
      console.log('当前页媒体', res.items)
      nextPageToken = res.nextPageToken

      // 需要全量读取时，不要一次性设置超大 pageSize；建议这样循环读取下一页。
      if (res.hasMore) {
        loadMixedPage()
      }
    }
  })
}

缩略图与导出示例

import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'

// 列表页建议先拿缩略图，减少原图/原视频加载压力。
GalleryPro.getGalleryThumbnails({
  ids: ['media-id-1', 'media-id-2'],
  width: 240,
  height: 240,
  success(res) {
    console.log('缩略图结果', res.items)
  }
})

// 用户点击预览、编辑或上传前，再导出临时文件。
GalleryPro.exportMediaToTempFile({
  id: 'media-id-1',
  exportType: 'render',
  success(res) {
    console.log('renderPath 用于页面显示，uploadPath 用于上传')
    console.log(res.renderPath, res.uploadPath)
  }
})

批量保存到系统相册

saveMediaToGallery 接收已经存在且可读取的本地图片、视频路径，按 paths 顺序逐项保存。它不负责下载网络 URL；如媒体来自系统相册，请先通过 exportMediaToTempFile 取得 uploadPath，再传给保存 API。

uni-app 示例

import { saveMediaToGallery } from '@/uni_modules/lizhao-gallery-pro'

// 图片和视频可以混合传入，结果 items 与 paths 保持相同顺序。
saveMediaToGallery({
  paths: [
    '/absolute/path/generated-poster.jpg',
    '/absolute/path/rendered-video.mp4'
  ],
  albumName: '业务素材',
  duplicatePolicy: 'allow',
  progress(event) {
    console.log('保存进度', event.current, event.total, event.progress)
  },
  success(res) {
    console.log('保存成功数、跳过数、失败数', res.successCount, res.skippedCount, res.failCount)
    console.log('逐项结果', res.items)
  },
  fail(err) {
    console.log('参数或权限检查失败', err.errCode, err.errMsg)
  }
})

uni-app x 示例

import {
  saveMediaToGallery,
  type GallerySaveOptions,
  type GallerySaveProgress,
  type GallerySaveResult,
  type GalleryFail
} from '@/uni_modules/lizhao-gallery-pro'

const paths = ['/absolute/path/generated-poster.jpg'] as Array<string>

// skip 只跳过平台公开 API 能可靠识别的可见重复项，不读取私有元数据。
saveMediaToGallery({
  paths,
  albumName: '',
  duplicatePolicy: 'skip',
  progress: (event : GallerySaveProgress) => console.log('保存进度', event.progress),
  success: (res : GallerySaveResult) => console.log('保存结果', res.items),
  fail: (err : GalleryFail) => console.log('保存失败', err.errCode, err.errMsg)
} as GallerySaveOptions)

参数

返回值

权限与平台边界

• Android 10 及以上通过 MediaStore 写入；Android 9 及以下需要 WRITE_EXTERNAL_STORAGE，插件清单仅声明到 API 28。
• iOS 默认相册且 duplicatePolicy: 'allow' 时只请求添加权限；自定义相册或 skip 判重需要 PhotoKit 读写权限。
• skip 不是内容哈希去重。只有文件名、媒体类型和文件大小等公开信息可靠可见时才会跳过；无法可靠判断时继续保存，避免误判。
• Web、Harmony 和小程序当前明确返回 9070024，不会伪造保存成功。
• 本功能包含 App 原生 UTS / Swift 和权限清单，升级插件后必须重新制作对应平台自定义基座。

上传示例

Android / iOS 均支持 concurrency、retryCount 和 dryRun。实际上传前插件会先把相册资产导出为可上传临时路径，dryRun=true 只做导出校验并保留结果顺序，不会发起网络请求。

import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'

// 有服务端时，传入 url 后插件会先导出文件，再调用上传接口。
GalleryPro.uploadGalleryMedia({
  ids: ['media-id-1', 'media-id-2'],
  url: 'https://example.com/upload',
  dryRun: false,
  name: 'file',
  concurrency: 2,
  retryCount: 1,
  progress(event) {
    console.log('上传进度', event.stage, event.current, event.total, event.progress)
  },
  success(res) {
    console.log('上传成功数', res.successCount)
    console.log('上传失败数', res.failCount)
    console.log('items 顺序与 options.ids 一致，index 是传入 ids 的原始序号', res.items)
  }
})

没有上传服务器时，可以先用 dryRun=true 校验导出链路。它只导出并返回路径，不会发起网络请求。

import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'

GalleryPro.uploadGalleryMedia({
  ids: ['media-id-1'],
  dryRun: true,
  progress(event) {
    console.log('导出校验进度', event.stage, event.progress)
  },
  success(res) {
    console.log('可上传路径', res.items[0].uploadPath)
  }
})

完整示例路径

相册变化实时监听

插件提供轻量原生变化通知，只告诉业务“相册可能发生变化”，不会擅自修改页面列表；收到事件后继续调用已有的 getGalleryMedia、getGalleryImages 或 getGalleryVideos 获取最新数据。

uni-app 示例

import {
  startGalleryChangeObserver,
  stopGalleryChangeObserver,
  getGalleryMedia
} from '@/uni_modules/lizhao-gallery-pro'

let observerId = ''

// 页面进入后启动；change 是持续回调。
startGalleryChangeObserver({
  mediaType: 'all',
  debounceMs: 300,
  change(event) {
    if (event.reason == 'permissionChanged') return
    // 原生通知不携带精确增删 ID，业务重新查询当前列表。
    getGalleryMedia({
      mediaType: 'all',
      pageSize: 30,
      success(res) {
        console.log('最新媒体列表', res.items)
      }
    })
  },
  success(res) {
    observerId = res.observerId
  },
  fail(err) {
    console.log('监听启动失败', err)
  }
})

// 页面卸载前必须停止，避免页面回调被长期持有。
function releaseGalleryObserver() {
  if (observerId.length == 0) return
  stopGalleryChangeObserver({
    observerId,
    success() {
      observerId = ''
    }
  })
}

uni-app x 示例

import {
  startGalleryChangeObserver,
  stopGalleryChangeObserver,
  getGalleryImages,
  type GalleryChangeEvent,
  type GalleryChangeObserverStartResult
} from '@/uni_modules/lizhao-gallery-pro'

const observerId = ref<string>('')

function reloadImages() : void {
  getGalleryImages({
    pageSize: 30,
    success: (res) => {
      console.log('最新图片数量：' + res.items.length.toString())
    }
  })
}

function startObserver() : void {
  startGalleryChangeObserver({
    mediaType: 'image',
    debounceMs: 300,
    change: (event : GalleryChangeEvent) => {
      if (event.reason != 'permissionChanged') reloadImages()
    },
    success: (res : GalleryChangeObserverStartResult) => {
      observerId.value = res.observerId
    }
  })
}

function stopObserver() : void {
  if (observerId.value.length == 0) return
  stopGalleryChangeObserver({
    observerId: observerId.value,
    success: (_) => {
      observerId.value = ''
    }
  })
}

startGalleryChangeObserver(options)

启动系统相册变化监听。启动前应先完成相册读取授权。

启动成功结果：

变化事件：

stopGalleryChangeObserver(options)

停止指定监听器。页面卸载前应显式调用。

监听兼容边界

持久化增量游标

适合相册备份、素材库同步、云盘增量上传和列表局部刷新。首次不传 cursor 建立基线，业务处理完变化后再持久化 nextCursor；旧游标在有效期内保持不可变，处理失败时可安全重试。

import {
  getGalleryChanges,
  clearGalleryChangeCursor
} from '@/uni_modules/lizhao-gallery-pro'

// 首次建立基线；把 nextCursor 保存到业务持久化存储。
getGalleryChanges({
  mediaType: 'all',
  success(res) {
    uni.setStorageSync('galleryCursor', res.nextCursor)
  },
  fail(err) {
    console.error('相册增量基线建立失败', err)
  }
})

// 下次启动后继续读取精确变化；处理成功后才推进游标。
getGalleryChanges({
  cursor: uni.getStorageSync('galleryCursor'),
  mediaType: 'all',
  maxChanges: 2000,
  success(res) {
    if (res.resetRequired) {
      // 权限、过滤条件、过期或变化过多时，先重新加载完整列表。
      console.log('需要重建全量列表', res.resetReason)
    } else {
      console.log('新增', res.addedIds)
      console.log('删除', res.removedIds)
      console.log('修改', res.updatedIds)
    }
    uni.setStorageSync('galleryCursor', res.nextCursor)
  }
})

getGalleryChanges(options)

clearGalleryChangeCursor(options)

API 说明

API 参数表

checkGalleryPermission(options) / requestGalleryPermission(options)

getGalleryMedia(options) / getGalleryImages(options) / getGalleryVideos(options)

getGalleryThumbnails(options)

getMediaById(options)

exportMediaToTempFile(options)

uploadGalleryMedia(options)

getGalleryAlbums(options)

clearGalleryCache(options)

import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'

// 只清理缩略图缓存，不影响已经导出的上传临时文件。
GalleryPro.clearGalleryCache({ cacheType: 'thumbnail' })

返回值表

GalleryPermissionResult

GalleryQueryResult

GalleryMediaItem

GalleryExportResult

GalleryUploadResult

GalleryAlbumItem

错误码

权限与自定义基座

App 端首次集成或修改 utssdk/app-android、utssdk/app-ios、权限配置、原生依赖后，需要重新制作并安装自定义基座。只修改页面示例、样式、README、普通脚本时，通常不需要重新打自定义基座。

Android 权限建议：

• Android 13 及以上：系统会按图片、视频分别授予读取权限。
• Android 12 及以下：使用外部存储读取权限。
• 如果用户拒绝并勾选不再询问，业务应根据 shouldOpenSettings 引导用户到系统设置。

iOS 权限建议：

• authorized 表示可读取完整相册。
• limited 表示用户只授权了部分照片，插件会按系统可见范围读取。
• 需要在原生配置中声明相册读取和保存相关用途说明。

注意事项

• 页面只从插件根目录导入：import * as GalleryPro from '@/uni_modules/lizhao-gallery-pro'，不要导入 utssdk 子路径。
• 异步 API 都支持 success / fail / complete，业务可以统一做成功、失败和收尾处理。
• 建议先调用 checkGalleryPermission，未授权再调用 requestGalleryPermission。
• 大图库请分页读取，不建议用超大 pageSize 做一次性全量读取；如确需全量读取，请使用 nextPageToken 循环读取下一页。
• 列表页优先显示 thumbnailPath；需要原图预览或上传时，再调用 exportMediaToTempFile。
• renderPath 用于页面显示，uploadPath 用于上传；不同平台路径格式不同，业务不要自行拼接路径。
• uploadGalleryMedia 的结果明细顺序与 options.ids 一致，index 是传入 ids 的原始序号。
• 来源分类依赖系统相册目录、文件名和平台元数据，能覆盖相机、截图、微信、QQ、下载等常见来源，但不同 ROM 或应用保存目录可能存在差异。
• clearGalleryCache({ cacheType: 'thumbnail' }) 只清理缩略图缓存，cacheType: 'export' 只清理导出缓存。
• 不支持平台会明确失败，业务可通过 getGalleryCapabilities() 控制入口显示。

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。