更新记录

1.0.0（2026-01-23）

• docs: 标注支持 uni-app（App 端 Android/iOS）
• feat: 对齐 expo-video-thumbnails：提供 getThumbnailAsync(sourceFilename, { time, quality, headers })
• feat: 返回 { uri, width, height }，输出格式固定为 jpg
• fix(android): 处理部分机型 getFrameAtTime 已自动旋转导致的缩略图方向错误（避免 double-rotation）

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-video-thumb

在 uni-app / uni-app x 中生成视频缩略图（App 端 Android/iOS）。

适用范围

• 支持：uni-app / uni-app x 的 App 端：Android / iOS
• 不支持：H5、各类小程序、Harmony（当前为 stub）

安装

将本插件放入项目 uni_modules/hans-video-thumb/，然后在页面中直接引入使用。

快速开始（uni-app / uni-app x）

import { getThumbnailAsync } from '@/uni_modules/hans-video-thumb'

const options = { // 可选
    time: 0,
    quality: 1.0,
    headers: {
        // Authorization: 'Bearer ...'
    },
}

getThumbnailAsync('file:///xxx.mp4', options).then((res) => {
    console.log(res.uri, res.width, res.height)
})

API

getThumbnailAsync(sourceFilename, options?)

• 作用：从视频生成一张 jpg 缩略图
• 返回：Promise<{ uri: string, width: number, height: number }>

参数

• sourceFilename：视频来源（本地或远程）
  • 本地：文件路径（例如 uni.chooseVideo 的 tempFilePath）、file://...、content://...（Android）
  • 远程：http://... / https://...

options

• time：截帧时间（毫秒），默认 0
• quality：0..1，默认 1.0
• headers：远程 URL 请求头（可选，建议 value 使用字符串）

返回值

• uri：输出图片 URI（缓存/临时目录，jpg）
• width / height：图片尺寸（像素）

错误处理（Promise reject）

失败时会 reject 一个带 errCode/errMsg 的对象（具体类型以 utssdk/interface.uts 为准）。

import { getThumbnailAsync } from '@/uni_modules/hans-video-thumb'

getThumbnailAsync('https://example.com/a.mp4', { time: 1000, quality: 0.9 })
    .then((res) => {
        console.log('ok', res.uri)
    })
    .catch((err) => {
        console.log('fail', err?.errCode, err?.errMsg ?? err)
    })

错误码（errCode）

• 9012101：参数错误（sourceFilename/time/quality/headers）
• 9012102：下载失败（远程 URL）
• 9012103：解码失败（取帧失败/视频不可用）
• 9012104：写文件失败（无法输出图片）
• 9012199：未知错误 / 平台不支持

平台支持

• Android：√
• iOS：√
• Harmony：-

备注（使用注意）

• 输出格式固定为 jpg。
• 输出图片位于缓存/临时目录，可能被系统清理；如需长期保存请自行拷贝到业务目录。
• time=0 可能取到黑帧/首帧不理想时，可尝试 time=200~1000（取关键帧依赖视频编码）。
• Android：远程 http(s) 会先下载到缓存目录临时文件再取帧；iOS 使用 AVURLAsset 直接读取（行为以系统为准）。
• Android：会自动处理视频旋转信息；若遇到封面方向异常，请优先确认原视频本身方向与机型差异（部分设备可能已在取帧时自动旋转）。
• 若 uni.chooseVideo 返回类似 _doc/... 的路径，请先用 plus.io.convertLocalFileSystemURL 转为真实本地路径或 file://... 再传入（仅 App 端可用）。