更新记录

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);
    });
  },
});

注意事项

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