更新记录

1.0.1（2026-04-21）

视频取帧方案优化

1.0.0（2026-04-01）

初始版本，支持单帧/批量截图、本地/网络视频、等比缩放

平台兼容性

uni-app(4.0)

uni-app x(5.0)

其他

dh-video-thumbnail — UTS 原生视频截图插件（Android + iOS）

基于 Android / iOS 原生能力的视频截图插件，支持毫秒级精度的单帧截图、批量截图，可用于生成视频缩略图、视频封面图、进度条预览图等，支持本地视频和网络视频。

常见使用场景：

• 视频列表页：为每条视频自动截图生成缩略图 / 封面图，替代手动上传封面
• 视频播放器：拖拽进度条时实时截取视频帧预览（时间轴缩略图）
• 视频上传前：自动截取第一帧作为视频封面，无需用户手动选择
• 短视频应用：批量截图生成多帧预览图，用于视频摘要或故事板展示

快速开始

import { getThumbnail, getThumbnails } from '@/uni_modules/dh-video-thumbnail';

// 单帧截图：提取第 3 秒帧
getThumbnail({
  videoPath: 'file:///var/mobile/.../video.mp4',
  time: 3000, // 毫秒
  width: 320, // 0 = 原始宽度
  quality: 80, // 0-100
  keepAspectRatio: true,
  success: (res) => {
    console.log(res.path); // file:///tmp/dh_vt_xxx.jpg
    console.log(res.width); // 320
    console.log(res.height); // 180
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg);
  },
});

// 批量截图：按 2 秒间隔截取前 6 帧
getThumbnails({
  videoPath: 'file:///var/mobile/.../video.mp4',
  interval: 2000,
  count: 6,
  width: 200,
  success: (res) => {
    console.log(res.paths); // string[]
    console.log(res.times); // number[]（毫秒）
  },
});

API

getThumbnail(options)

提取单帧截图。

ThumbnailResult

getThumbnails(options)

批量提取多帧截图。时间点来源二选一：times（指定时间点数组）或 interval + count（自动间隔）。times 优先。

BatchThumbnailResult

某帧提取失败时会自动跳过，不影响其他帧。

错误码

示例

网络视频截图（自动缓存）

getThumbnail({
  videoPath: 'https://example.com/demo.mp4',
  time: 10000,
  width: 480,
  height: 270,
  keepAspectRatio: true,
  success: (res) => console.log(res.path),
  fail: (err) => {
    if (err.errCode === 8040005) {
      console.log('网络下载失败，请检查网络');
    }
  },
});

按指定时间点批量截图

getThumbnails({
  videoPath: 'file:///var/mobile/.../video.mp4',
  times: [0, 5000, 10000, 15000, 20000],
  width: 320,
  quality: 70,
  success: (res) => {
    res.paths.forEach((path, i) => {
      console.log(`第 ${res.times[i] / 1000}s:`, path);
    });
  },
});

自动生成视频封面图（取第 0 帧）

上传视频时常用：截取第 0 毫秒的帧作为封面图，省去用户手动选封面的步骤。

getThumbnail({
  videoPath: 'file:///var/mobile/.../video.mp4',
  time: 0,       // 取第一帧作为封面
  width: 720,
  quality: 90,
  success: (res) => {
    // res.path 即为封面图路径，可直接上传或展示
    uploadCover(res.path);
  },
});

注意事项

• 提取的图片保存在系统临时目录（tmp/），App 重启后会被清除，如需持久化请自行复制到其他路径
• 网络视频会下载到临时目录并缓存，相同 URL 不重复下载
• iOS 帧提取允许 ±1 秒容差以命中最近关键帧，性能更优
• keepAspectRatio: false 时会拉伸到精确的 width × height，可能变形
• 批量截图在后台线程执行，不会阻塞 UI