更新记录

1.0.0（2026-05-23）

截取视频图片功能的添加

平台兼容性

uni-app(3.7.7)

uni-app x(3.7.7)

zl-videotool

视频缩略图工具（UTS 插件），提供基础的视频截图功能

平台支持

1. 引入模块

import { getVideoThumbnail } from "@/uni_modules/zl-videotool"

2. 获取本地视频缩略图

uni-app x 中不再支持 plus.io，本地视频需先通过 uni.getFileSystemManager().copyFile() 将 static 目录下的文件复制到用户目录，再传入插件调用。

// #ifdef APP
const fs = uni.getFileSystemManager()
const videoDestPath = `${uni.env.USER_DATA_PATH}/test.mp4`
// 先将 static 下的视频复制到用户目录（插件需要可访问的文件路径）
fs.copyFile({
  srcPath: "/static/test.mp4",
  destPath: videoDestPath,
  success() {
    getVideoThumbnail({
      videoPath: videoDestPath,
      saveImagePath: `${uni.env.USER_DATA_PATH}/TXVideoTool/`,
      saveImageName: "testLocal.png",
      second: 0,
      success(res) {
        console.log("缩略图路径:", res.imagePath)
      },
      fail(err) {
        console.log("错误:", err.errMsg)
      }
    })
  },
  fail() {
    // 文件可能已存在，直接使用
    getVideoThumbnail({
      videoPath: videoDestPath,
      saveImagePath: `${uni.env.USER_DATA_PATH}/TXVideoTool/`,
      saveImageName: "testLocal.png",
      second: 0,
      success(res) {
        console.log("缩略图路径:", res.imagePath)
      },
      fail(err) {
        console.log("错误:", err.errMsg)
      }
    })
  }
})
// #endif

3. 获取网络视频缩略图

getVideoThumbnail({
  videoPath: "https://example.com/video.mp4",
  saveImagePath: `${uni.env.USER_DATA_PATH}/TXVideoTool/`,
  saveImageName: "testNetwork.png",
  second: 6,
  success(res) {
    console.log("缩略图路径:", res.imagePath)
  },
  fail(err) {
    console.log("错误:", err.errMsg)
  }
})

4. Web 平台使用

// #ifdef WEB
getVideoThumbnail({
  videoPath: "/static/test.mp4",
  saveImagePath: "",
  saveImageName: "testLocal.png",
  second: 0,
  success(res) {
    // Web 端返回的是 base64 data URL，可直接用于 image src
    console.log("缩略图:", res.imagePath)
  },
  fail(err) {
    console.log("错误:", err.errMsg)
  }
})
// #endif

参数说明

成功回调参数

失败回调参数

错误码

路径说明（uni-app x）

uni-app x 中不再支持 plus.io，请使用以下方式获取路径：

注意：/static/ 下的文件为只读资源，插件内部需使用原生绝对路径。页面调用时传入 uni.env.USER_DATA_PATH 下的路径，插件会自动通过 UTSAndroid.convert2AbsFullPath() / UTSiOS.convert2AbsFullPath() 转换为平台原生绝对路径。

Web 平台说明

Web 平台由于浏览器安全限制无法写入本地文件，saveImagePath 和 saveImageName 参数无效，成功回调中 imagePath 返回的是 base64 数据 URL（如 data:image/png;base64,...），可直接用于 <image> 组件的 src 属性。