📱 沉浸式小视频

沉浸式小视频提供类似抖音的全屏垂直视频浏览体验,支持上下滑动切换、点赞评论、一起看视频等丰富功能。

🚪 接入方式概览

两种方式共用 VideoConfig 配置对象,事件回调使用 VideoListener。

✅ 方式一:VideoNativeView(推荐)

VideoNativeView 通过 PlatformView 内嵌原生视频播放器,Flutter 端像普通 Widget 一样使用。

基础用法

import 'package:flutter/material.dart';
import 'package:pangrowth_content/pangrowth_content.dart';

class VideoPage extends StatelessWidget {
  const VideoPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: VideoNativeView(
        channelType: 1,  // 1-推荐,2-关注,3-推荐+关注
        autoPlay: true,
        listener: VideoListener(
          onVideoReady: (videoId) {
            debugPrint('视频就绪: $videoId');
          },
          onVideoError: (error) {
            debugPrint('视频错误: $error');
          },
          onVideoDisposed: () {
            debugPrint('视频已销毁');
          },
        ),
      ),
    );
  }
}

VideoNativeView参数

结合Controller控制

使用 VideoController 可以在外部控制视频播放:

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

  @override
  State<VideoPlayerPage> createState() => _VideoPlayerPageState();
}

class _VideoPlayerPageState extends State<VideoPlayerPage> {
  final _controller = VideoController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          VideoNativeView(
            controller: _controller,
            channelType: 3, // 推荐+关注双频道
            listener: VideoListener(
              onVideoReady: (videoId) {
                debugPrint('视频就绪: $videoId');
              },
            ),
          ),
          Positioned(
            bottom: 50,
            right: 20,
            child: Row(
              children: [
                FloatingActionButton(
                  mini: true,
                  onPressed: () => _controller.pause(),
                  child: const Icon(Icons.pause),
                ),
                const SizedBox(width: 10),
                FloatingActionButton(
                  mini: true,
                  onPressed: () => _controller.resume(),
                  child: const Icon(Icons.play_arrow),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

生命周期管理

VideoNativeView 自动管理视频生命周期:

• 创建: Widget initState 时自动创建原生视图
• 显示: Widget build 时自动显示
• 暂停/恢复: 自动监听应用生命周期(前后台切换)
• 销毁: Widget dispose 时自动销毁原生视图

🧭 方式二:API控制方式

适合需要精确控制视频生命周期的场景,如原生Activity/ViewController中展示。

完整生命周期演示

import 'package:flutter/material.dart';
import 'package:pangrowth_content/pangrowth_content.dart';

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

  @override
  State<VideoAPIDemo> createState() => _VideoAPIDemoState();
}

class _VideoAPIDemoState extends State<VideoAPIDemo> {
  String? _videoId;
  bool _isLoading = false;

  Future<void> _createAndShowVideo() async {
    setState(() {
      _isLoading = true;
    });

    try {
      // 1. 创建视频配置
      final config = VideoConfig(
        drawChannelType: 1,        // 推荐频道
        progressBarStyle: 1,        // 浅色进度条
        hideChannelName: false,     // 显示频道名称
        enableRefresh: true,        // 支持下拉刷新
      );

      // 2. 创建视频
      final result = await PangrowthContent.createVideo(config);

      if (result['success'] == true) {
        _videoId = result['videoId'] as String;
        debugPrint('创建成功: $_videoId');

        // 3. 展示视频
        await PangrowthContent.showVideo(
          _videoId!,
          // iOS专用:控制展示样式
          presentationStyle: 'fullScreen',  // fullScreen/pageSheet/formSheet
          // Android专用:指定容器ID
          // containerId: android.R.id.content,
        );

        debugPrint('展示成功');
      }
    } catch (e) {
      debugPrint('创建或展示失败: $e');
      _showSnackBar('操作失败: $e');
    } finally {
      setState(() {
        _isLoading = false;
      });
    }
  }

  Future<void> _pauseVideo() async {
    if (_videoId != null) {
      await PangrowthContent.pauseVideo(_videoId!);
      debugPrint('暂停成功');
    }
  }

  Future<void> _resumeVideo() async {
    if (_videoId != null) {
      await PangrowthContent.resumeVideo(_videoId!);
      debugPrint('恢复成功');
    }
  }

  Future<void> _refreshVideo() async {
    if (_videoId != null) {
      await PangrowthContent.refreshVideo(_videoId!);
      debugPrint('刷新成功');
    }
  }

  Future<void> _destroyVideo() async {
    if (_videoId != null) {
      await PangrowthContent.destroyVideo(_videoId!);
      debugPrint('销毁成功');
      setState(() {
        _videoId = null;
      });
    }
  }

  void _showSnackBar(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    );
  }

  @override
  void dispose() {
    // 清理资源
    if (_videoId != null) {
      PangrowthContent.destroyVideo(_videoId!);
    }
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('API方式演示')),
      body: Center(
        child: _isLoading
            ? const CircularProgressIndicator()
            : Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  ElevatedButton(
                    onPressed: _videoId == null ? _createAndShowVideo : null,
                    child: const Text('创建并显示'),
                  ),
                  const SizedBox(height: 10),
                  ElevatedButton(
                    onPressed: _videoId != null ? _pauseVideo : null,
                    child: const Text('暂停'),
                  ),
                  const SizedBox(height: 10),
                  ElevatedButton(
                    onPressed: _videoId != null ? _resumeVideo : null,
                    child: const Text('恢复'),
                  ),
                  const SizedBox(height: 10),
                  ElevatedButton(
                    onPressed: _videoId != null ? _refreshVideo : null,
                    child: const Text('刷新'),
                  ),
                  const SizedBox(height: 10),
                  ElevatedButton(
                    onPressed: _videoId != null ? _destroyVideo : null,
                    child: const Text('销毁'),
                  ),
                ],
              ),
      ),
    );
  }
}

API方法说明

核心方法

播放控制方法

高级控制方法

Android专用方法

iOS专用方法

🧩 VideoConfig配置参数

VideoConfig 基于官方SDK的 DPWidgetDrawParams(Android) 和 LCDDrawVideoVCConfig(iOS) 设计,提供43个配置参数。

通用参数

Android专用参数

iOS专用参数

一起看视频参数

配置示例

Android自定义样式

final config = VideoConfig(
  drawChannelType: 1,
  // Android专用配置
  isShowActionBar: true,
  actionBarBackgroundColor: '#FF6200EE',
  fontSize: 16,
  isBold: true,
  topMargin: 20,
  // 通用配置
  progressBarStyle: 1,
  enableRefresh: true,
);

iOS自定义样式

final config = VideoConfig(
  drawChannelType: 1,
  // iOS专用配置
  isShowNavigationBar: true,
  navigationBarBackgroundColor: '#FFFFFF',
  navigationBarTitleColor: '#000000',
  statusBarStyle: 'darkContent',
  allowPanBack: true,
  // 通用配置
  progressBarStyle: 2,
  enableRefresh: true,
);

一起看视频配置

// 主控端配置
final hostConfig = VideoConfig(
  drawChannelType: 1,
  watchTogetherRole: 'HOST',
  hostGroupId: 12345,
  customCategory: '一起看',
);

// 被控端配置
final userConfig = VideoConfig(
  drawChannelType: 1,
  watchTogetherRole: 'USER',
  hostGroupId: 12345,
  customCategory: '一起看',
);

📡 事件监听

使用VideoListener(NativeView方式)

VideoNativeView(
  listener: VideoListener(
    onVideoReady: (videoId) {
      debugPrint('✅ 视频就绪: $videoId');
    },
    onVideoDisposed: () {
      debugPrint('🗑️ 视频已销毁');
    },
    onVideoError: (error) {
      debugPrint('❌ 视频错误: $error');
    },
  ),
)

常见事件类型

💡 完整使用示例

1. 一起看视频实现

class WatchTogetherService {
  /// 主控端:启动一起看视频
  static Future<void> startAsHost(String roomId) async {
    final config = VideoConfig(
      watchTogetherRole: 'HOST',
      hostGroupId: int.parse(roomId),
      drawChannelType: 1,
      customCategory: '一起看',
      scene: 'watch_together',
    );

    final result = await PangrowthContent.createVideo(config);
    final videoId = result['videoId'];
    await PangrowthContent.showVideo(videoId);
  }

  /// 被控端:加入一起看视频
  static Future<void> joinAsUser(String roomId, String syncData) async {
    final config = VideoConfig(
      watchTogetherRole: 'USER',
      hostGroupId: int.parse(roomId),
      drawChannelType: 1,
      customCategory: '一起看',
      scene: 'watch_together',
    );

    final result = await PangrowthContent.createVideo(config);
    final videoId = result['videoId'];

    // 设置同步数据
    await PangrowthContent.setSyncData(videoId, syncData, 1);
    await PangrowthContent.showVideo(videoId);
  }

  /// 同步播放数据
  static Future<void> syncPlayback(String videoId, String syncData) async {
    await PangrowthContent.setSyncData(videoId, syncData, 2);
  }
}

2. 自定义主题配置

class VideoThemeConfig {
  /// 深色主题
  static VideoConfig get darkTheme => VideoConfig(
    progressBarStyle: 2,
    drawChannelType: 3,
    enableRefresh: true,
    hideFollow: false,
    // iOS
    navigationBarBackgroundColor: '#000000',
    navigationBarTitleColor: '#FFFFFF',
    statusBarStyle: 'lightContent',
    // Android
    actionBarBackgroundColor: '#1a1a1a',
    fontSize: 16,
  );

  /// 浅色主题
  static VideoConfig get lightTheme => VideoConfig(
    progressBarStyle: 1,
    drawChannelType: 3,
    enableRefresh: true,
    hideFollow: false,
    // iOS
    navigationBarBackgroundColor: '#FFFFFF',
    navigationBarTitleColor: '#000000',
    statusBarStyle: 'darkContent',
    // Android
    actionBarBackgroundColor: '#f5f5f5',
    fontSize: 16,
  );

  /// 简洁模式
  static VideoConfig get minimalistTheme => VideoConfig(
    hideClose: false,
    hideFollow: true,
    hideChannelName: true,
    progressBarStyle: 1,
    enableRefresh: false,
    drawChannelType: 1,
  );
}

3. TabBar场景暂停恢复

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

  @override
  State<VideoTabPage> createState() => _VideoTabPageState();
}

class _VideoTabPageState extends State<VideoTabPage>
    with SingleTickerProviderStateMixin {
  late TabController _tabController;
  final _videoController = VideoController();

  @override
  void initState() {
    super.initState();
    _tabController = TabController(length: 3, vsync: this);

    // 监听Tab切换,自动暂停/恢复
    _tabController.addListener(() {
      if (_tabController.index == 1) {
        _videoController.resume(); // 切换到视频Tab,恢复播放
      } else {
        _videoController.pause();  // 切换走,暂停播放
      }
    });
  }

  @override
  void dispose() {
    _videoController.dispose();
    _tabController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        bottom: TabBar(
          controller: _tabController,
          tabs: const [
            Tab(text: '首页'),
            Tab(text: '视频'), // 视频Tab
            Tab(text: '我的'),
          ],
        ),
      ),
      body: TabBarView(
        controller: _tabController,
        children: [
          const Center(child: Text('首页')),
          VideoNativeView(
            controller: _videoController,
            channelType: 3, // 推荐+关注双频道
            listener: VideoListener(
              onVideoReady: (videoId) {
                debugPrint('视频就绪: $videoId');
              },
            ),
          ),
          const Center(child: Text('我的')),
        ],
      ),
    );
  }
}

4. 完整的视频播放管理器

class VideoPlayerManager {
  String? _currentVideoId;

  Future<void> startVideo({VideoConfig? config}) async {
    try {
      // 如果已有视频在播放,先销毁
      if (_currentVideoId != null) {
        await stopVideo();
      }

      // 创建新视频
      final result = await PangrowthContent.createVideo(config ?? VideoConfig());
      if (result['success'] == true) {
        _currentVideoId = result['videoId'];
        await PangrowthContent.showVideo(_currentVideoId!);
      }
    } catch (e) {
      debugPrint('启动视频失败: $e');
      rethrow;
    }
  }

  Future<void> stopVideo() async {
    if (_currentVideoId != null) {
      try {
        await PangrowthContent.destroyVideo(_currentVideoId!);
      } catch (e) {
        debugPrint('销毁视频失败: $e');
      } finally {
        _currentVideoId = null;
      }
    }
  }

  Future<void> pauseVideo() async {
    if (_currentVideoId != null) {
      await PangrowthContent.pauseVideo(_currentVideoId!);
    }
  }

  Future<void> resumeVideo() async {
    if (_currentVideoId != null) {
      await PangrowthContent.resumeVideo(_currentVideoId!);
    }
  }

  Future<void> refreshVideo() async {
    if (_currentVideoId != null) {
      await PangrowthContent.refreshVideo(_currentVideoId!);
    }
  }

  bool get isPlaying => _currentVideoId != null;

  void dispose() {
    stopVideo();
  }
}

⚠️ 注意事项

1. 资源管理

• 必须在合适的时机调用 destroyVideo() 释放资源
• NativeView方式会自动销毁,API方式需要手动销毁
• 页面退出时务必销毁视频实例,避免内存泄漏

2. 网络要求

• 功能依赖网络连接,建议在网络环境良好时使用
• 考虑网络异常情况的处理

3. 权限配置

• 确保应用已获得网络访问权限
• Android需要网络状态权限
• iOS需要网络访问权限

4. 版本兼容

• 部分功能需要特定版本的原生SDK支持
• 一起看视频功能需要服务端配合

5. 平台差异

• Android和iOS的部分配置参数不同
• 某些方法仅在特定平台可用(已在文档中标注)
• iOS的展示样式通过presentationStyle控制,Android通过containerId控制容器

🔧 故障排除

常见问题

Q: 视频创建失败,提示"SDK_NOT_STARTED"

A: 确保在使用前已调用 PangrowthContent.initialize() 和 PangrowthContent.start(startVideo: true)

Q: iOS端展示异常

A: 检查 presentationStyle 参数设置,建议使用 fullScreen

Q: 一起看视频功能不生效

A: 确认 watchTogetherRole 和 hostGroupId 参数设置正确,主控端和被控端的 hostGroupId 必须一致

Q: 事件回调收不到

A: 确保已正确设置事件监听器:

• NativeView方式: 传入 VideoListener
• API方式: 调用 PangrowthContent.onEventListener()

Q: Android端容器显示异常

A: 检查 containerId 参数,或使用默认值(传入null)

Q: 视频自动暂停

A: NativeView会自动监听应用生命周期,切换到后台时会自动暂停,这是正常行为

调试建议

1. 开启日志输出: 在代码中使用 debugPrint 查看详细错误信息
2. 确认SDK版本: 确保SDK版本和文档版本匹配
3. 检查网络连接: 验证网络状态
4. 验证配置参数: 检查AppID和AppSecret配置
5. 测试基础功能: 先使用最简配置进行测试

🌍 平台差异说明

展示方式差异

平台专属方法

Android专属

• scrollToTop() - 滚动到顶部
• backRefresh() - 返回刷新(挽留用户)

iOS专属

• getCurrentIndex() - 获取当前位置
• scrollToIndex() - 滚动到指定位置
• pauseCurrentVideo() / playCurrentVideo() - 播放控制
• seekVideoToMSeconds() - 精确进度控制(毫秒)
• createReportContent() - 创建举报页面
• refreshVideoToStayUser() / showToastToStayUser() - 用户留存

配置参数平台支持

参见上文"VideoConfig配置参数"章节,已清晰标注每个参数的平台支持情况。

🔗 相关文档

• 宫格与双Feed小视频 - 宫格/双Feed布局的小视频
• 个人主页 - 用户个人主页组件
• 事件处理 - 完整的事件体系说明

💡 提示: 沉浸式小视频功能需要有效的内容源和网络连接。建议在正式使用前先进行测试,确保内容加载正常。一起看视频功能需要额外的服务端支持。