更新记录

1.0.5（2026-08-04）

• 新增 getVideoStoryboard，可按起止时间一次生成带确定性帧坐标的视频时间轴预览整图或雪碧图。
• Android、iOS 和 Web 支持统一的居中采样、网格布局、cover / contain 适配、背景色、缓存复用、任务取消与进度回调。
• 默认生成 12 帧、4 列、160×90 单元格；帧数限制为 2-60，并按 App 1600 万像素、Web 800 万像素限制最终画布，避免大图内存风险。
• HarmonyOS、微信小程序和支付宝小程序继续返回明确不支持，不伪造时间轴预览成功。
• uni-app 示例新增手动入口和一键自检第 14 项，覆盖整图、行列、时间递增、坐标边界与缓存命中。
• App 原生实现已变化，升级后需要重新构建并安装对应平台自定义基座。

1.0.4（2026-07-31）

• HarmonyOS 新增视频路径文本归一化、空缓存统计和空缓存清理基础能力，并使用显式结果类兼容 ArkTS 名义类型。
• 能力矩阵继续明确真实视频信息、取帧、批量和智能封面尚未实现，不伪造媒体处理成功。
• Harmony 真机一键自检的路径与缓存基础项已通过；Harmony 原生 UTS 已变化，升级后需要重新构建并安装匹配的 Harmony HAP 或自定义基座。

1.0.2（2026-07-28）

• 新增任务 ID 与 cancelVideoThumbnailTask，支持取消单帧、多时间点、批量及网络下载任务，取消统一返回 9060011，重复或未知任务取消保持幂等。
• 新增显式 cachePolicy: 'reuse'、cacheMaxAgeMs、cacheHit 和 getThumbnailCacheInfo；默认仍为 refresh，保持既有唯一文件名和输出路径行为。
• Android 增加下载循环、解码前后、缓存写入前和批量项间取消检查，并支持稳定文件缓存复用与统计。
• 修复 Android 取消、缓存统计、缓存清理和独立下载回调结果被编译为 UTSJSONObject 后触发具体结果类型强转崩溃的问题。
• iOS 增加 Swift 异步可取消取帧桥、AVAssetImageGenerator 取消、单次回调仲裁、取消输出清理及缓存图片读取统计。
• Web 增加 video/canvas 任务清理和最多 32 项的进程内 LRU 缓存；HarmonyOS、微信小程序和支付宝小程序继续返回明确不支持。
• 同步更新 uni-app / uni-app x 示例、能力矩阵、平台声明、客户文档和任务缓存回归守卫。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-video-thumb

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

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

你可以先这样理解

1. 不知道哪一帧适合做封面：调用 getSmartVideoThumbnail 自动分析和选择。
2. 播放器或编辑器需要一张时间轴预览整图：调用 getVideoStoryboard。
3. 只想取指定时间的一张封面：调用 getVideoThumbnail。
4. 想在一个视频里取多个时间点：调用 getVideoThumbnails。
5. 想批量处理多个视频：调用 getVideoThumbnailBatch。
6. 视频是网络地址：在 common 或普通取帧参数中开启 allowNetwork。
7. 页面要直接预览：outputType 使用 base64 或 both，可直接拿到 Base64。
8. 想主动停止耗时任务：传入 taskId，再调用 cancelVideoThumbnailTask。
9. 想复用相同结果：设置 cachePolicy: 'reuse'，通过 cacheHit 判断是否命中。

功能特色

• 支持本地视频、_doc、file://、content://、uni.saveFile 临时路径、相册资源和网络视频的统一入口设计。
• Android/iOS 已实现网络视频下载到私有缓存后取帧，downloadVideoForThumbnail 已可直接返回本地缓存路径。
• 对于网络视频，downloadVideoForThumbnail 已可直接返回本地缓存路径，后续可继续调用取帧接口。
• 支持毫秒级 timeMs 取帧，避免只能按整数秒取封面导致画面不准确。
• 支持智能封面：默认在视频 5% 到 95% 区间分析 7 个候选帧，自动避开近黑、近白和曝光异常画面，并返回每个候选的质量指标。
• 支持视频时间轴预览与雪碧图：一次顺序提取多帧并合成网格整图，同时返回每帧对应的时间和像素坐标，适合播放器悬停预览与视频编辑器。
• 支持单个视频、多时间点、多个视频批量生成缩略图，批量任务默认使用异步队列和并发限制。
• 默认生成唯一文件名，支持自定义输出目录、文件名和覆盖策略，避免多个视频得到重复图片或缓存互相覆盖。
• 输出支持本地文件、Base64 或两者同时返回，方便上传、预览和业务缓存。
• Android 已实现本地视频、content://、file://、_doc、_downloads 基础取帧，并在此基础上支持网络视频下载取帧，覆盖 Android 10 分区存储下的内容 URI 读取、毫秒级取帧、唯一文件名和 Base64 输出。
• iOS 已实现本地视频、file://、_doc、_downloads 基础取帧，并在此基础上支持网络视频下载取帧。iOS 使用 AVAssetImageGenerator 并默认修正视频方向，覆盖 iOS 旋转修正，兼容 MOV / HEVC 系统解码能力并提供空白帧邻近时间点兜底。
• 相册选择和录制视频拿到的本地临时路径会走同一套路径归一与取帧流程，避免录制视频无响应。
• 网络视频默认关闭，业务需显式设置 allowNetwork: true，并关注下载超时、最大字节数和 App 网络权限。
• 提供 clearThumbnailCache 缓存清理能力，避免长期使用产生过多图片文件。
• 批量队列会为每个视频生成唯一文件名，减少多视频同时处理时的重复图片和互相覆盖问题。
• 支持任务 ID 和协作式取消，取消、成功、失败互斥，complete 只触发一次。
• 支持显式缓存复用、最大缓存年龄和缓存统计；默认仍生成唯一文件，不改变既有接入行为。

接入方式选择

最小可运行示例

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 { getSmartVideoThumbnail } from '@/uni_modules/lizhao-video-thumb'

// 智能封面会先分析候选帧，再使用同一套输出参数生成最终缩略图。
getSmartVideoThumbnail({
  src: '_doc/demo.mp4',
  candidateCount: 7,
  startRatio: 0.05,
  endRatio: 0.95,
  common: {
    outputType: 'both',
    fixOrientation: true,
    maxWidth: 720,
    maxHeight: 405
  },
  success(res) {
    // 业务日志建议只记录摘要，不要输出 thumbnail.base64 正文。
    console.log('智能封面完成', res.selectedTimeMs, res.score, res.thumbnail.imagePath)
  },
  fail(err) {
    console.log('智能封面失败', err.errCode, err.errMsg)
  },
  complete() {
    console.log('智能封面流程结束')
  }
})

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

// 批量任务建议设置 concurrency，避免多个大视频同时解码造成界面阻塞。
getVideoThumbnailBatch({
  taskId: 'video-cover-batch-001',
  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,
    // 复用相同视频、时间点和图片参数生成的受管缓存。
    cachePolicy: 'reuse',
    cacheMaxAgeMs: 86400000
  },
  progress(event) {
    console.log('批量缩略图进度', event.current, event.total, event.message)
  },
  success(res) {
    console.log('批量缩略图完成', res.results)
  },
  fail(err) {
    console.log('批量缩略图失败', err.errMsg)
  }
})

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

// 默认会在视频有效区间居中采样 12 帧，并合成为 4 列网格整图。
getVideoStoryboard({
  taskId: 'video-storyboard-001',
  src: '_doc/demo.mp4',
  frameCount: 12,
  columns: 4,
  frameWidth: 160,
  frameHeight: 90,
  fitMode: 'cover',
  backgroundColor: '#000000',
  common: {
    outputType: 'both',
    fixOrientation: true,
    cachePolicy: 'reuse'
  },
  success(res) {
    // frames 可直接映射时间点与整图中的 x/y/width/height 区域。
    console.log('时间轴预览完成', res.imagePath, res.columns, res.rows, res.frames)
  },
  fail(err) {
    console.log('时间轴预览失败', err.errCode, err.errMsg)
  },
  complete() {
    console.log('时间轴预览流程结束')
  }
})

如果播放器需要单行横向雪碧图，可将 columns 设置为与 frameCount 相同；例如 frameCount: 12, columns: 12 会生成一行 12 格整图。Web 读取跨域视频时，视频服务仍需允许 CORS，否则浏览器无法把画面绘制到可导出的 canvas。

取消任务与查询缓存

import {
  cancelVideoThumbnailTask,
  getThumbnailCacheInfo
} from '@/uni_modules/lizhao-video-thumb'

// taskId 应由业务保证唯一；取消未知或已完成任务会返回 accepted: false。
cancelVideoThumbnailTask({
  taskId: 'video-cover-batch-001',
  success(res) {
    console.log('取消请求结果', res.accepted, res.state)
  }
})

// 只统计该视频相关的插件受管缓存；不传 src 时统计全部。
getThumbnailCacheInfo({
  src: '_doc/demo.mp4',
  success(res) {
    console.log('缓存文件与命中情况', res.fileCount, res.totalBytes, res.hitCount)
  }
})

完整示例源码路径

支持平台

getVideoThumbnail(options)

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

参数

返回值

getVideoStoryboard(options)

说明 在指定时间区间内按帧中心点均匀采样，将所有帧顺序合成为一张网格整图，并返回每帧对应的时间和像素坐标。Android、iOS 和 Web 支持；HarmonyOS 与小程序返回明确不支持。

参数

App 最终画布限制为 1600 万像素，Web 最终画布限制为 800 万像素。超过限制会返回 9060015，业务应减少帧数、列数或单元格尺寸。

返回值

getSmartVideoThumbnail(options)

说明 在指定视频区间内等距分析多个候选帧，综合亮度、对比度、清晰度和黑白画面占比，选择质量更高的封面。候选分析不会生成临时图片文件；最终封面复用普通缩略图的输出和缓存参数。

参数

返回值

错误码

自定义基座说明

插件包含 App 端 utssdk/app-android/**/*.uts、utssdk/app-ios/**/*.uts 和 iOS Swift 桥接逻辑，Android 网络视频还使用 INTERNET 权限。客户真机要使用 Android / iOS 最新原生逻辑时，需要重新运行对应平台原生联编或重新打对应平台自定义基座；仅更新 wgt/appResource 不能替换旧基座中的原生逻辑。时间轴预览和智能封面没有新增 Android/iOS 三方 SDK、libs、res、Frameworks 或 Resources。

注意事项

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

作者系列UTS插件

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