更新记录

1.0.0（2026-06-30）

• 首版发布 lizhao-gallery-pro 相册媒体 UTS 插件。
• 支持 Android / iOS 相册图片与视频统一查询、分页、时间范围、来源分类和权限状态读取。
• 支持缩略图批量生成、按媒体 ID 导出可渲染/可上传临时文件、上传辅助、缓存清理和能力矩阵。
• 上传辅助支持 dryRun 导出校验，不配置上传地址也能验证媒体可上传路径且不会发起网络请求。
• 上传结果明细新增 index 字段，并按传入 ids 顺序返回，方便业务和原始选择列表对齐。
• 缓存清理支持按 all / thumbnail / export 分类型清理，避免缩略图缓存和导出上传缓存互相影响。
• 相册分组返回图片/视频数量、封面缩略图、最新媒体 ID、最新文件名和最新创建时间，便于直接构建相册入口页。
• 相册分组支持 sourceType 来源过滤，可直接读取截图、相机、微信、QQ、下载等来源相册。
• Android 视频缩略图兜底改用 MediaMetadataRetriever 取帧，移除废弃的 createVideoThumbnail / MINI_KIND 调用。
• 提供 uni-app 与 uni-app x 内置示例，示例从插件根目录导入，覆盖权限检查、图片列表、视频列表、混合列表、导出显示和上传流程。
• 文档采用客户接入顺序组织，并在底部补充作者系列 UTS 插件推荐。

平台兼容性

uni-app(5.07)

lizhao-gallery-pro

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

当前版本：1.0.0

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

功能特色

适合哪些场景

• 社区发帖、评价晒单、工单上报，需要从相册读取图片或视频。
• 素材库、云盘、相册备份，需要分页读取大量本地媒体。
• 内容审核、巡检记录、设备报修，需要按相机、截图、微信、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)
  }
})

图片列表

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)
  }
})

上传示例

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)
  }
})

完整示例路径

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 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。