插件介绍

fluttertpc_video_thumbnail 是一个专为 Flutter 应用开发的视频缩略图生成插件，已针对鸿蒙平台进行了全面适配。该插件可以从本地视频文件或网络视频 URL 生成高质量的缩略图，支持多种图片格式和自定义参数，帮助开发者轻松实现视频内容的预览功能。

主要功能特性：

• 支持从本地视频文件生成缩略图
• 支持从网络视频 URL 生成缩略图（鸿蒙平台部分支持，详见已知问题）
• 提供内存缩略图（Uint8List）和文件缩略图两种输出形式
• 支持 JPEG、PNG、WEBP 三种图片格式
• 可自定义缩略图分辨率、质量和时间点
• 支持 HTTP 请求头配置
• 鸿蒙平台原生实现，性能优异

如何使用插件

包的引入

由于本三方库为自定义修改版本，需要以 git 形式引入。在 Flutter 项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  video_thumbnail_ohos:
    git:
      url: "https://gitcode.com/openharmony-sig/fluttertpc_video_thumbnail.git"
      path: "ohos"

添加依赖后，执行以下命令获取包：

flutter pub get

权限配置（鸿蒙平台特有）

在鸿蒙平台上使用该插件需要配置文件访问权限。请按照以下步骤进行配置：

1. 修改 module.json5 文件

   打开 entry/src/main/module.json5 文件，添加读取图片和视频的权限：

   "requestPermissions": [
     {
       "name": "ohos.permission.READ_IMAGEVIDEO",
       "reason": "需要访问视频文件以生成缩略图",
       "usedScene": {
         "abilities": ["EntryAbility"],
         "when": "inuse"
       }
     }
   ]
   

2. 添加权限描述字符串

   打开 entry/src/main/resources/base/element/string.json 文件，添加权限描述：

   {
     "string": [
       {
         "name": "EntryAbility_label",
         "value": "视频缩略图生成"
       }
     ]
   }
   

API 的调用

1. 导入包

在 Dart 代码中导入插件：

import 'package:video_thumbnail_ohos/video_thumbnail_ohos.dart';

2. 生成内存缩略图

从视频文件或 URL 生成内存中的缩略图（Uint8List），适用于直接在 UI 中显示：

import 'dart:typed_data';
import 'package:flutter/material.dart';
import 'package:video_thumbnail_ohos/video_thumbnail_ohos.dart';

// 从本地视频文件生成内存缩略图
Future<Uint8List?> generateThumbnailFromFile(String videoPath) async {
  final uint8list = await VideoThumbnailOhos.thumbnailData(
    video: videoPath,
    imageFormat: ImageFormat.JPEG, // 图片格式
    maxWidth: 128, // 缩略图最大宽度，高度会自动按比例缩放
    quality: 25, // 图片质量（0-100），PNG格式会忽略此参数
  );
  return uint8list;
}

// 在 UI 中显示缩略图
Image thumbnailImage(Uint8List thumbnailData) {
  return Image.memory(thumbnailData);
}

3. 生成文件缩略图

将生成的缩略图保存为文件：

import 'dart:io';
import 'package:path_provider/path_provider.dart';
import 'package:video_thumbnail_ohos/video_thumbnail_ohos.dart';

// 从视频 URL 生成文件缩略图
Future<String?> generateThumbnailFile(String videoUrl) async {
  // 获取临时目录
  final tempDir = await getTemporaryDirectory();

  final fileName = await VideoThumbnailOhos.thumbnailFile(
    video: videoUrl,
    thumbnailPath: tempDir.path, // 缩略图保存路径
    imageFormat: ImageFormat.WEBP, // 图片格式
    maxHeight: 64, // 缩略图最大高度，宽度会自动按比例缩放
    quality: 75, // 图片质量
    timeMs: 1000, // 从视频的第1秒处生成缩略图
  );

  return fileName;
}

// 使用生成的缩略图文件
void useThumbnailFile(String thumbnailPath) {
  final thumbnailFile = File(thumbnailPath);
  // 可以将文件路径传递给 Image.file() 或进行其他处理
}

4. 从 Assets 中生成缩略图

如果视频文件作为 Assets 包含在项目中，可以按照以下方式生成缩略图：

import 'dart:io';
import 'package:flutter/services.dart';
import 'package:path_provider/path_provider.dart';
import 'package:video_thumbnail_ohos/video_thumbnail_ohos.dart';

// 从 Assets 视频生成缩略图
Future<String?> generateThumbnailFromAssets(String assetPath) async {
  // 加载 Assets 视频
  final byteData = await rootBundle.load(assetPath);

  // 创建临时文件
  final tempDir = await getTemporaryDirectory();
  final tempVideoPath = '${tempDir.path}/temp_video.mp4';

  final tempVideoFile = File(tempVideoPath)
    ..createSync(recursive: true)
    ..writeAsBytesSync(byteData.buffer.asUint8List(
      byteData.offsetInBytes,
      byteData.lengthInBytes
    ));

  // 生成缩略图
  final thumbnailPath = await VideoThumbnailOhos.thumbnailFile(
    video: tempVideoPath,
    thumbnailPath: tempDir.path,
    imageFormat: ImageFormat.PNG,
    quality: 100,
  );

  return thumbnailPath;
}

5. 自定义参数说明

参数名	类型	默认值	说明
video	String	必需	视频文件路径或网络 URL
headers	Map<String, String>?	null	HTTP 请求头（用于网络视频）
thumbnailPath	String?	null	缩略图保存路径，null 表示保存在视频同一目录
imageFormat	ImageFormat	ImageFormat.PNG	输出图片格式（JPEG/PNG/WEBP）
maxHeight	int	0	缩略图最大高度，0 表示与原视频相同
maxWidth	int	0	缩略图最大宽度，0 表示与原视频相同
timeMs	int	0	生成缩略图的视频时间点（毫秒）
quality	int	10	图片质量（0-100），PNG 格式忽略此参数

已知问题

1. 网络视频支持限制

   • 鸿蒙平台上，thumbnailFile 方法使用在线视频生成缩略图文件目前存在问题，建议优先使用本地视频文件。
   • 网络视频的 thumbnailData 方法在某些情况下可能无法正常工作。

2. 性能考虑

   • 生成高分辨率、高质量的缩略图可能会消耗较多资源，建议根据实际需求合理设置参数。
   • 处理大文件时，建议在异步线程中执行，避免阻塞 UI。

兼容性要求

• Flutter 版本：3.7.12-ohos-1.0.6
• SDK 版本：5.0.0(12)
• IDE：DevEco Studio 5.0.13.200
• ROM：5.1.0.120 SP3

总结

fluttertpc_video_thumbnail 是鸿蒙平台上一个功能强大、易于使用的 Flutter 视频缩略图生成插件。它提供了丰富的 API 和灵活的参数配置，支持从本地文件、网络 URL 和 Assets 中生成高质量的缩略图，满足各种视频预览场景的需求。

该插件针对鸿蒙平台进行了原生适配，性能优异，同时保持了与其他平台一致的 API 设计，降低了跨平台开发的学习成本。虽然在网络视频支持方面存在一些限制，但对于本地视频文件的处理已经非常成熟稳定。

无论是开发短视频应用、视频播放器还是需要视频预览功能的其他应用，fluttertpc_video_thumbnail 都是一个值得信赖的选择。

欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net