Fluttertpc_Chewie 鸿蒙平台使用指南

Fluttertpc_Chewie是一款专为HarmonyOS优化的Flutter视频播放插件，基于官方video_player封装，提供Material和Cupertino双风格界面。核心功能包括完整播放控制、字幕支持、播放速度调节（0.25x-2.0x）、自动全屏切换和自定义主题等。适用于在线视频、教育课程、新闻资讯等多种场景。安装需通过Git方式引入依赖，支持基础播放、字幕添加、自定义控制和

全堆鸿蒙

578人浏览 · 2025-12-21 21:56:43

全堆鸿蒙 · 2025-12-21 21:56:43 发布

一、插件介绍

Fluttertpc_Chewie 是一个基于 Flutter 官方 video_player 插件封装的视频播放控件库，专为 HarmonyOS 平台进行了适配和优化。它提供了友好的 Material 和 Cupertino 风格的视频播放界面，支持丰富的视频控制功能，让开发者能够轻松实现高质量的视频播放体验。

核心功能

🎬 完整的播放控制：播放/暂停、快进/快退、进度条拖动
🎨 双风格界面：支持 Material 和 Cupertino 两种 UI 风格
⚙️ 丰富的播放选项：循环播放、自动播放、音量控制
⏱️ 播放速度调节：支持 0.25x 到 2.0x 多种播放速度
📝 字幕支持：可自定义字幕内容、样式和显示方式
🔄 自动切换全屏：支持横竖屏切换和全屏播放
🎯 自定义主题：可自定义进度条颜色、控制按钮样式等
⚡ 流畅的用户体验：自动隐藏控件、加载缓冲提示等

适用场景

Fluttertpc_Chewie 适用于各种需要视频播放功能的 HarmonyOS Flutter 应用，如：

在线视频播放应用
教育类应用的视频课程播放
新闻资讯应用的视频内容展示
社交媒体应用的视频分享功能
电商应用的产品视频展示

二、安装与集成

2.1 环境要求

Flutter: 3.7.12-ohos-1.0.6 或更高版本
HarmonyOS SDK: 5.0.0(12) 或更高版本
DevEco Studio: 5.0.13.200 或更高版本

2.2 依赖配置

由于这是一个自定义修改版本的 Chewie 库，需要通过 Git 方式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  chewie:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_chewie.git"
      path: "fluttertpc_chewie"
  video_player:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_video_player.git"
      path: "fluttertpc_video_player"

2.3 安装依赖

执行以下命令安装依赖：

flutter pub get

三、API 文档与使用示例

3.1 基础使用

以下是一个简单的视频播放示例：

import 'package:chewie/chewie.dart';
import 'package:flutter/material.dart';
import 'package:video_player/video_player.dart';

class VideoPlayerScreen extends StatefulWidget {
  const VideoPlayerScreen({super.key});

  @override
  State<VideoPlayerScreen> createState() => _VideoPlayerScreenState();
}

class _VideoPlayerScreenState extends State<VideoPlayerScreen> {
  late VideoPlayerController _videoPlayerController;
  ChewieController? _chewieController;

  @override
  void initState() {
    super.initState();
    _initializePlayer();
  }

  Future<void> _initializePlayer() async {
    // 初始化视频控制器
    _videoPlayerController = VideoPlayerController.networkUrl(
      Uri.parse('https://assets.mixkit.co/videos/preview/mixkit-spinning-around-the-earth-29351-large.mp4'),
    );

    await _videoPlayerController.initialize();

    // 创建 Chewie 控制器
    _chewieController = ChewieController(
      videoPlayerController: _videoPlayerController,
      autoPlay: true,
      looping: true,
      showControls: true,
      materialProgressColors: ChewieProgressColors(
        playedColor: Colors.red,
        handleColor: Colors.blue,
        backgroundColor: Colors.grey,
        bufferedColor: Colors.lightGreen,
      ),
      placeholder: Container(
        color: Colors.grey,
        child: const Center(child: Text('加载中...')),
      ),
    );

    setState(() {});
  }

  @override
  void dispose() {
    _videoPlayerController.dispose();
    _chewieController?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('视频播放器')),
      body: Center(
        child: _chewieController != null &&
               _chewieController!.videoPlayerController.value.isInitialized
            ? Chewie(controller: _chewieController!)
            : const CircularProgressIndicator(),
      ),
    );
  }
}

3.2 字幕功能

Chewie 支持自定义字幕功能，可以为视频添加多段字幕：

// 创建字幕列表
final subtitles = [
  Subtitle(
    index: 0,
    start: Duration.zero,
    end: const Duration(seconds: 10),
    text: '欢迎使用 Fluttertpc_Chewie',
  ),
  Subtitle(
    index: 1,
    start: const Duration(seconds: 10),
    end: const Duration(seconds: 20),
    text: '这是一个功能强大的视频播放器',
  ),
  Subtitle(
    index: 2,
    start: const Duration(seconds: 20),
    end: const Duration(seconds: 30),
    text: '支持字幕、播放速度调节等功能',
  ),
];

// 在 ChewieController 中配置字幕
_chewieController = ChewieController(
  videoPlayerController: _videoPlayerController,
  autoPlay: true,
  looping: true,
  subtitle: Subtitles(subtitles),
  subtitleBuilder: (context, dynamic subtitle) => Container(
    padding: const EdgeInsets.all(10.0),
    decoration: BoxDecoration(
      color: Colors.black.withOpacity(0.7),
      borderRadius: BorderRadius.circular(5),
    ),
    child: Text(
      subtitle.toString(),
      style: const TextStyle(color: Colors.white, fontSize: 16),
    ),
  ),
);

3.3 自定义控制选项

可以通过 additionalOptions 参数为视频播放器添加自定义控制选项：

_chewieController = ChewieController(
  videoPlayerController: _videoPlayerController,
  autoPlay: true,
  looping: true,
  additionalOptions: (context) {
    return <OptionItem>[
      OptionItem(
        onTap: () {
          // 切换到另一个视频源
          _switchVideoSource();
        },
        iconData: Icons.live_tv_sharp,
        title: '切换视频源',
      ),
      OptionItem(
        onTap: () {
          // 分享当前视频
          _shareVideo();
        },
        iconData: Icons.share,
        title: '分享视频',
      ),
    ];
  },
);

3.4 播放速度控制

Chewie 默认支持播放速度调节功能，用户可以在选项菜单中选择不同的播放速度：

_chewieController = ChewieController(
  videoPlayerController: _videoPlayerController,
  autoPlay: true,
  looping: true,
  // 可以指定默认的播放速度
  playbackSpeeds: [0.25, 0.5, 0.75, 1.0, 1.25, 1.5, 2.0],
  // 默认播放速度
  playbackSpeed: 1.0,
);

3.5 控件样式切换

Chewie 支持 Material 和 Cupertino 两种控件样式，可以根据平台自动适配：

// 在 MaterialApp 中设置平台
MaterialApp(
  theme: ThemeData(
    platform: TargetPlatform.android, // 使用 Material 风格控件
    // platform: TargetPlatform.iOS, // 使用 Cupertino 风格控件
  ),
  home: const VideoPlayerScreen(),
);

四、HarmonyOS 平台特定配置

4.1 权限配置

在 HarmonyOS 平台上使用视频播放功能，需要在 module.json5 文件中配置相关权限：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "Fluttertpc_Chewie 示例应用",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "EntryAbility",
        "icon": "$media:app_icon",
        "label": "fluttertpc_chewie_example",
        "startWindowIcon": "$media:app_icon",
        "startWindowBackground": {
          "type": "color",
          "value": "#FFFFFF"
        },
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ],
    "reqPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.READ_MEDIA",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

4.2 兼容性说明

HarmonyOS 版本	Flutter 版本	支持状态
5.0.0(12)	3.7.12-ohos-1.0.6	✅ 完全支持
4.1.0(10)	3.7.12-ohos-1.0.6	⚠️ 部分支持
4.0.0(9)	3.7.12-ohos-1.0.6	❌ 不支持

五、API 参考

5.1 核心类

ChewieController

参数名	类型	说明	HarmonyOS 支持
videoPlayerController	VideoPlayerController	视频控制器	✅
autoPlay	bool	是否自动播放	✅
looping	bool	是否循环播放	✅
showControls	bool	是否显示控件	✅
materialProgressColors	ChewieProgressColors	Material 风格进度条颜色	✅
cupertinoProgressColors	ChewieProgressColors	Cupertino 风格进度条颜色	✅
placeholder	Widget	加载占位符	✅
autoInitialize	bool	是否自动初始化	✅
startAt	Duration	起始播放位置	✅
subtitle	Subtitles	字幕配置	✅
subtitleBuilder	Widget Function(BuildContext, dynamic)	字幕构建器	✅
additionalOptions	List Function(BuildContext)	额外控制选项	✅
playbackSpeeds	List	播放速度列表	✅
optionsTranslation	OptionsTranslation	选项翻译配置	✅
hideControlsTimer	Duration	控件自动隐藏时间	✅

Chewie

参数名	类型	说明	HarmonyOS 支持
controller	ChewieController	Chewie 控制器	✅
key	Key	Widget Key	✅

5.2 方法

方法名	返回值	说明	HarmonyOS 支持
play()	Future	开始播放	✅
pause()	Future	暂停播放	✅
seekTo(Duration moment)	Future	跳转到指定位置	✅
setLooping(bool looping)	Future	设置是否循环播放	✅
setVolume(double volume)	Future	设置音量	✅
enterFullScreen()	void	进入全屏模式	✅
exitFullScreen()	void	退出全屏模式	✅