更新记录

1.0.0（2026-06-29）

• 发布 lizhao-video-thumb 视频封面与视频缩略图 UTS 插件首个正式版本。
• 定义本地视频、网络视频、毫秒级取帧、批量取帧、Base64 返回、自定义输出、缓存清理和能力矩阵接口。
• 完成 Android 基础取帧：支持本地视频、file://、_doc、_downloads、content://、毫秒级取帧、唯一文件名、Base64、批量和缓存清理。
• 完成 iOS 基础取帧：使用 AVAssetImageGenerator 支持本地视频、file://、_doc、_downloads、方向修正、空白帧邻近时间点兜底、唯一文件名、Base64、批量和缓存清理。
• 完成 Android/iOS 网络视频与批量队列增强：网络视频可先下载到插件私有缓存后取帧，支持超时、大小限制、进度回调和批量唯一文件名。
• 完成 Web 降级取帧与非 App 平台明确不支持边界：Web 使用 video + canvas 返回 data URL；HarmonyOS、微信小程序和支付宝小程序返回明确错误，不伪造成功。
• 修复 Android 回调兼容问题：避免把 VideoThumbnailOptions 运行时强转为回调对象导致 ClassCastException，真实触发 success / fail / complete。
• 完善 uni-app 与 uni-app x 示例：选择或录制视频后自动生成并展示封面，优先使用 Base64 data URI 预览，避免 App 私有缓存路径在 WebView 中显示为空。
• 新增示例页与回归守卫：补齐主项目 uni-app 示例、插件内 uni-app 示例、插件内 uni-app x 示例，覆盖本地视频、网络视频、Base64、批量、多时间点、路径归一、网络下载、缓存清理和选择视频封面展示。
• 发布前将插件 ID 从 lizhao-video-thumbnail 调整为 lizhao-video-thumb，满足插件市场 ID 最长 20 个字符限制。
• 优化 README：按功能理解、接入方式、最小示例、增强示例、平台边界、API 细节和作者其他插件推荐的顺序介绍。
• 发布包整理：移除本地生成的插件市场封面素材目录，发布源码包应以完整 uni_modules/lizhao-video-thumb 为根目录。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-video-thumb

lizhao-video-thumb 是面向 uni-app / uni-app x 的视频封面、视频缩略图和视频帧图提取 UTS 插件。你只需要传入视频地址，就可以在 App 端使用原生能力取出指定时间点的封面图，也可以在 Web 端使用降级方案生成预览图。

这个插件适合短视频列表、课程封面、聊天视频消息、素材库、视频编辑器时间轴、上传前预览等场景。插件会把真实项目里常见的路径、格式、批量、缓存和平台差异问题收进插件层处理，减少业务页反复写兼容代码。

你可以先这样理解

1. 只想取一张封面：调用 getVideoThumbnail。
2. 想在一个视频里取多个时间点：调用 getVideoThumbnails。
3. 想批量处理多个视频：调用 getVideoThumbnailBatch。
4. 视频是网络地址：先开启 allowNetwork，插件会下载到私有缓存再取帧。
5. 页面要直接预览：outputType 使用 base64 或 both，可直接拿到 Base64。

功能特色

• 支持本地视频、_doc、file://、content://、uni.saveFile 临时路径、相册资源和网络视频的统一入口设计。
• Android/iOS 已实现网络视频下载到私有缓存后取帧，downloadVideoForThumbnail 已可直接返回本地缓存路径。
• 对于网络视频，downloadVideoForThumbnail 已可直接返回本地缓存路径，后续可继续调用取帧接口。
• 支持毫秒级 timeMs 取帧，避免只能按整数秒取封面导致画面不准确。
• 支持单个视频、多时间点、多个视频批量生成缩略图，批量任务默认使用异步队列和并发限制。
• 默认生成唯一文件名，支持自定义输出目录、文件名和覆盖策略，避免多个视频得到重复图片或缓存互相覆盖。
• 输出支持本地文件、Base64 或两者同时返回，方便上传、预览和业务缓存。
• Android 已实现本地视频、content://、file://、_doc、_downloads 基础取帧，并在此基础上支持网络视频下载取帧，覆盖 Android 10 分区存储下的内容 URI 读取、毫秒级取帧、唯一文件名和 Base64 输出。
• iOS 已实现本地视频、file://、_doc、_downloads 基础取帧，并在此基础上支持网络视频下载取帧。iOS 使用 AVAssetImageGenerator 并默认修正视频方向，覆盖 iOS 旋转修正，兼容 MOV / HEVC 系统解码能力并提供空白帧邻近时间点兜底。
• 相册选择和录制视频拿到的本地临时路径会走同一套路径归一与取帧流程，避免录制视频无响应。
• 网络视频默认关闭，业务需显式设置 allowNetwork: true，并关注下载超时、最大字节数和 App 网络权限。
• 提供 clearThumbnailCache 缓存清理能力，避免长期使用产生过多图片文件。
• 批量队列会为每个视频生成唯一文件名，减少多视频同时处理时的重复图片和互相覆盖问题。

接入方式选择

最小可运行示例

import { getVideoThumbnail } from '@/uni_modules/lizhao-video-thumb'

// Android/iOS 已支持原生取帧；Web 已支持 video + canvas 降级取帧。
// HarmonyOS 和小程序当前会返回明确不支持错误，不会伪造成功。
getVideoThumbnail({
  src: '_doc/demo.mp4',
  timeMs: 0,
  outputType: 'file',
  success(res) {
    console.log('视频封面生成成功', res.imagePath)
  },
  fail(err) {
    console.log('视频封面生成失败', err.errCode, err.errMsg)
  },
  complete(res) {
    console.log('视频封面流程结束', res)
  }
})

常见增强示例

import { getVideoThumbnailBatch } from '@/uni_modules/lizhao-video-thumb'

// 批量任务建议设置 concurrency，避免多个大视频同时解码造成界面阻塞。
getVideoThumbnailBatch({
  items: [
    { id: 'local-1', src: '_doc/a.mp4', timeMs: 350 },
    { id: 'camera-1', src: 'file:///storage/emulated/0/DCIM/Camera/demo.mp4', timeMs: 1200 }
  ],
  concurrency: 2,
  common: {
    outputType: 'both',
    fixOrientation: true
  },
  progress(event) {
    console.log('批量缩略图进度', event.current, event.total, event.message)
  },
  success(res) {
    console.log('批量缩略图完成', res.results)
  },
  fail(err) {
    console.log('批量缩略图失败', err.errMsg)
  }
})

完整示例源码路径

支持平台

getVideoThumbnail(options)

说明 生成单个视频在指定时间点的视频封面或视频缩略图。

参数

返回值

错误码

自定义基座说明

当前版本已经修改 App 端 utssdk/app-android/**/*.uts、utssdk/app-ios/**/*.uts、iOS Swift 桥接文件，并新增 Android AndroidManifest.xml 的 INTERNET 权限，用于网络视频下载。客户真机要使用 Android / iOS 最新原生逻辑时，需要重新运行对应平台原生联编或重新打对应平台自定义基座；仅更新 wgt/appResource 不能替换旧基座中的原生逻辑。当前未新增 Android/iOS 三方 SDK、libs、res、Frameworks 或 Resources。

注意事项

• 当前 1.0.0 已完成 Android 与 iOS 基础取帧、网络视频下载取帧、批量队列，并补齐 Web 降级取帧与非 App 平台明确不支持边界。
• 插件层会优先把路径归一、缓存命名、批量队列和错误码做成稳定契约，后续平台实现不得要求客户改成唯一指定调用写法。
• 网络视频默认关闭，业务需显式设置 allowNetwork: true，并关注下载大小、超时和服务端是否支持移动端直接访问。
• HarmonyOS、微信小程序和支付宝小程序当前返回明确不支持错误，不伪造成功；只有拿到可编译、可验证的真实平台能力后才会打开能力矩阵。

作者其他插件推荐

如果你的项目围绕视频、媒体播放、文件处理或 App 原生能力搭建，可以搭配下面这些同作者插件使用：