更新记录

1.0.9（2026-11-10）

• 修复 HarmonyOS 最低 API 13 的项目运行时，视频缩略图原生依赖要求 API 20 而导致构建失败的问题；保持原有调用方式，升级后重新构建鸿蒙 App。
• 优化说明文档，补齐“作者系列 UTS 插件”清单及插件市场链接，便于按能力查找。

1.0.8（2026-11-05）

• 新增 HarmonyOS 本地及网络视频信息、单帧、多时间点、批量、智能封面和时间轴能力，支持缓存、进度与任务取消。
• 新增 HarmonyOS 显式自定义沙箱目录的同名图片覆盖尝试，实际可用性取决于系统文件接口和权限。
• 新增 HarmonyOS 显式自定义目录的非覆盖直出尝试，同名自动换名，系统不支持时保留安全回退。
• 新增 HarmonyOS 默认缓存目录固定名称的覆盖尝试，旧文件身份不明或同名冲突时保留原文件。
• 修复 HarmonyOS 两种宿主用户数据路径转换不一致，以及缓存清理后统计计数未重置的问题。
• 修复 HarmonyOS 时间轴覆盖参数误报不支持、缓存结果在回调前提前释放、暂存关闭失败时的清理处理及输出失败状态提示不完整的问题。
• 修复 iOS 单帧最大宽高设置未生效的问题。
• 修复 iOS 活动任务与缓存清理、下载完成时序冲突，以及进度回调修改在途批量参数的问题。
• 修复 Web 时间轴输出类型缓存、透明背景颜色、缓存筛选及单帧时间和时长字段问题。
• 修复 HarmonyOS 时间轴已交付图片但临时目录清理未确认时的状态提示。
• 优化 HarmonyOS 自定义目录缓存复用，符合条件时直接交付到指定目录并保留安全回退。
• 统一 uni-app 和 uni-app x 示例的操作顺序、状态展示及异步任务处理。

1.0.7（2026-11-04）

• 修复示例页面和辅助模块使用相对引入路径的问题，统一通过 @/uni_modules/ 引用插件内文件，复制页面到其他目录时无需另行复制辅助代码。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-video-thumb 帮你从视频中生成封面、多帧预览和时间轴图片。

功能与场景

• 指定时间生成视频列表封面，也可以自动选择画面质量较好的候选帧。
• 为播放进度预览生成时间轴整图及每帧坐标，或一次处理多个时间点、多个视频。
• 按需返回图片路径或 Base64，查询视频信息、复用缓存和取消活动任务。

适用于 uni-app 和 uni-app x；Android、iOS、HarmonyOS 和 Web 的具体限制见文末。视频必须能被当前平台读取并解码。

下载与导入

从插件市场下载并导入 lizhao-video-thumb，在页面中从 @/uni_modules/lizhao-video-thumb 导入需要的方法。完整页面可参考 uni-app 示例 和 uni-app x 示例。

基础使用：生成一张封面

适合在用户选择视频后生成列表封面。将 src 换成选择器返回的可读路径；timeMs 的单位是毫秒。

uni-app：

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

getVideoThumbnail({
  src: '替换为选择视频返回的可读路径',
  timeMs: 1000,
  outputType: 'both',
  success: (res) => console.log('封面路径', res.imagePath),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

uni-app x：

import { getVideoThumbnail, type VideoThumbnailOptions, type VideoThumbnailResult, type VideoThumbnailFail } from '@/uni_modules/lizhao-video-thumb'

const options : VideoThumbnailOptions = {
  src: '替换为选择视频返回的可读路径',
  timeMs: 1000,
  outputType: 'both',
  success: (res : VideoThumbnailResult) => { console.log('封面路径', res.imagePath) },
  fail: (err : VideoThumbnailFail) => { console.error(err.errCode, err.errMsg) }
}
getVideoThumbnail(options)

下面各业务片段使用 JavaScript 展示调用方式；uni-app x 可像上例一样为参数和回调声明插件导出的对应类型。运行前请替换视频路径、网络地址和任务 ID。

按业务使用

按名称保存封面

需要使用固定文件名更新封面时，可指定可写目录；允许覆盖后，同名文件可能被替换。

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

getVideoThumbnail({
  src: '替换为可读视频路径',
  outputDir: '替换为可写的应用沙箱目录',
  fileName: 'cover.jpg',
  cachePolicy: 'refresh',
  overwrite: true,
  success: (res) => console.log(res.imagePath),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

自动选择封面

不确定选择哪个时间点时，分析候选画面并返回选中的缩略图与评分。

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

getSmartVideoThumbnail({
  src: '替换为可读视频路径',
  candidateCount: 7,
  success: (res) => console.log(res.selectedTimeMs, res.score, res.thumbnail.imagePath),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

评分辅助选择，不保证符合主观审美。如果至少有一帧分析成功但质量均较低，会返回其中最高分并设置 fallbackUsed；全部候选解码失败时进入 fail。

候选数量默认 7，归一到 3–20；startRatio 和 endRatio 默认为 0.05 和 0.95，均在 0–1 范围内，开始比例须小于结束比例。

生成时间轴预览

播放器需要拖动预览时，可生成一张整图并根据 frames 中的坐标显示对应画面。

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

getVideoStoryboard({
  src: '替换为可读视频路径',
  frameCount: 12,
  columns: 4,
  frameWidth: 160,
  frameHeight: 90,
  fitMode: 'cover',
  common: { outputType: 'both', cachePolicy: 'reuse' },
  success: (res) => console.log(res.imagePath, res.frames),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

frames 中每项包含帧序号、时间与 x、y、width、height，坐标相对于返回整图。startTimeMs / endTimeMs 可限制采样区间。

同一视频生成多张图片

需要展示指定时间点时，使用毫秒数组获取多张结果。

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

getVideoThumbnails({
  src: '替换为可读视频路径',
  timesMs: [1000, 3000, 5000],
  common: { outputType: 'both' },
  success: (res) => console.log('图片数量', res.results.length),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

批量处理多个视频

媒体列表需要批量封面时，检查成功和失败数量；部分失败时结果列表只包含成功项。

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

getVideoThumbnailBatch({
  items: [
    { src: '替换为第一个可读视频路径', timeMs: 1000 },
    { src: '替换为第二个可读视频路径', timeMs: 2000 }
  ],
  success: (res) => console.log(res.successCount, res.failCount),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

网络视频取帧

视频地址为 HTTP 或 HTTPS 时，需要显式允许网络来源。Web 跨域服务器还需要允许 CORS。

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

getVideoThumbnail({
  src: 'https://替换为真实地址/video.mp4',
  allowNetwork: true,
  timeMs: 1000,
  success: (res) => console.log(res.imagePath),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

读取视频信息

需要展示视频时长和尺寸时，先读取视频信息。路径归一化只识别地址类型，不保证文件可读。

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

getVideoInfo({
  src: '替换为可读视频路径',
  success: (res) => console.log(res.durationMs, res.width, res.height),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

检查输入路径的类型时，可以使用 normalizeVideoPath；检查成功不代表文件一定可读。

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

normalizeVideoPath({
  src: '替换为可读视频路径',
  success: (res) => console.log(res.pathType, res.normalizedPath),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

复用与清理缓存

多次请求同一个画面时设置 reuse；页面不再需要缓存时，可按来源和时间条件清理。

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

getVideoThumbnail({
  src: '替换为可读视频路径',
  timeMs: 1000,
  cachePolicy: 'reuse',
  cacheMaxAgeMs: 86400000,
  success: (res) => console.log('是否命中缓存', res.cacheHit),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

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

clearThumbnailCache({
  src: '替换为可读视频路径',
  success: (res) => console.log('已清理数量', res.removedCount),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

需要展示当前缓存占用时，可单独查询统计。

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

getThumbnailCacheInfo({
  success: (res) => console.log(res.fileCount, res.totalBytes),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

取消活动任务

任务可能持续较长时间时，传入唯一 taskId，再通过相同 ID 请求取消。取消受理后仍应等待原任务的成功或失败回调。

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

const taskId = '替换为本次唯一任务ID'
getVideoThumbnail({
  taskId,
  src: '替换为可读视频路径',
  success: (res) => console.log(res.imagePath),
  fail: (err) => console.error(err.errCode, err.errMsg)
})
// 用户选择取消时调用：
cancelVideoThumbnailTask({ taskId, success: (res) => console.log('已受理', res.accepted) })

单独下载网络视频

需要先下载再由业务使用本地路径时，可在 App 端单独下载。

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

downloadVideoForThumbnail({
  src: 'https://替换为真实地址/video.mp4',
  timeoutMs: 30000,
  maxBytes: 104857600,
  success: (res) => console.log('下载路径', res.localPath),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

查询当前平台能力

根据能力矩阵决定是否向用户展示对应操作。

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

const capabilities = getVideoThumbnailCapabilities()
console.log('支持时间轴', capabilities.storyboard)

用途速查

除能力矩阵同步返回外，各方法通过 success、fail、complete 返回结果；支持进度的方法可传入 progress。活动任务之间的 taskId 必须唯一。

单帧结果中的 imagePath、base64、width、height、timeMs、durationMs 和 cacheHit 可用于展示或记录；请以返回的实际路径为准，日志避免输出完整 Base64。进度包含任务 ID、阶段、百分比及批量序号。

常用配置

多帧、批量、智能封面和时间轴通过 common 传递通用配置。时间轴默认 12 帧、4 列、每格 160×90，支持 cover 和 contain；帧数归一到 2–60，列数归一到 1–帧数，单格宽高归一到 16–1024。App 画布上限为 1600 万像素，Web 为 800 万像素；背景色支持 #RRGGBB 和 #AARRGGBB。

平台差异与注意事项

可使用 getVideoThumbnailCapabilities() 判断当前平台能力。App 项目需使用包含本版本插件原生能力的安装包或自定义基座。读取网络视频前请确认网络权限与服务端授权；读取本地视频前请确认文件存在并拥有相应访问权限。

缓存清理的 olderThanMs 是毫秒时间戳，表示清理早于该时间的条目，省略或为 0 时不按时间筛选。Web 缓存在当前进程内，并按来源和时间筛选；统计字节数为估算值。Android 主要依据文件名中的来源哈希与修改时间筛选；iOS 对默认缓存根目录的一级条目执行清理，目录统计和删除数量不等同于递归文件大小。HarmonyOS 按受管缓存记录筛选，无法确定来源的旧条目可能导致按来源清理返回不支持。命中与未命中次数为当前进程累计，清理时重置。

错误码

遇到 9060009 且提示目标文件状态未确认时，请先检查提示中的输出路径再决定是否重试；提示目标文件已写入时，其他步骤仍可能失败。多帧或批量任务中途结束时，错误信息可能包含已经取得的输出路径。 临时资源清理未确认的提示也可能出现在成功结果的 message 中；请先结束应用再检查提示的临时路径，该路径不是已交付图片。

作者系列 UTS 插件

以下为作者已发布的 UTS 插件，可按能力方向查找。