Flutter中ListView内嵌YoutubePlayer滚动卡顿及自动加载问题

问题核心原因 #

1. 滚动卡顿：列表每一项初始化时就创建YoutubePlayerController并加载视频资源，大量并发的资源请求和渲染操作占用过多CPU与内存，导致滚动不流畅。
2. 自动加载：YoutubePlayerController在初始化阶段会自动请求视频元数据与基础资源，即使autoPlay设为false，也会触发加载行为。

一、解决滚动卡顿问题 #

方案1：先展示缩略图，点击再加载播放器 #

列表项默认仅显示YouTube视频的缩略图，用户点击后才初始化播放器并加载视频，从根源减少列表初始化时的资源消耗：

ListView.builder(
  itemCount: posts.length,
  itemBuilder: (_, i) => YoutubePlayerThumbnailWidget(
    videoUrl: posts[i].video!,
  ),
);

class YoutubePlayerThumbnailWidget extends StatefulWidget {
  final String videoUrl;

  const YoutubePlayerThumbnailWidget({super.key, required this.videoUrl});

  @override
  State<YoutubePlayerThumbnailWidget> createState() => _YoutubePlayerThumbnailWidgetState();
}

class _YoutubePlayerThumbnailWidgetState extends State<YoutubePlayerThumbnailWidget> {
  bool _showPlayer = false;
  String? get _videoId => YoutubePlayer.convertUrlToId(widget.videoUrl);

  @override
  Widget build(BuildContext context) {
    if (_showPlayer) {
      return YoutubePlayerWidget(videoUrl: widget.videoUrl);
    }

    return GestureDetector(
      onTap: () => setState(() => _showPlayer = true),
      child: Image.network(
        'https://img.youtube.com/vi/$_videoId/mqdefault.jpg',
        fit: BoxFit.cover,
        width: double.infinity,
        height: 200,
      ),
    );
  }
}

方案2：监听组件可见性，动态管理控制器生命周期 #

通过visibility_detector包监听组件是否处于视口内，仅当组件可见时初始化控制器，不可见时销毁控制器释放资源：

// 需在pubspec.yaml中添加visibility_detector依赖

class YoutubePlayerWidget extends StatefulWidget {
  final String? videoId;
  final String? videoUrl;

  const YoutubePlayerWidget({super.key, this.videoId, this.videoUrl});

  @override
  State<YoutubePlayerWidget> createState() => _YoutubePlayerWidgetState();
}

class _YoutubePlayerWidgetState extends State<YoutubePlayerWidget> with AutomaticKeepAliveClientMixin {
  YoutubePlayerController? _controller;
  String get _videoId => widget.videoId ?? YoutubePlayer.convertUrlToId(widget.videoUrl!)!;

  @override
  bool get wantKeepAlive => true;

  @override
  Widget build(BuildContext context) {
    super.build(context);
    return VisibilityDetector(
      key: Key('youtube-player-$_videoId'),
      onVisibilityChanged: (visibilityInfo) {
        final isVisible = visibilityInfo.visibleFraction > 0.5;
        if (isVisible && _controller == null) {
          _controller = YoutubePlayerController(
            initialVideoId: _videoId,
            flags: const YoutubePlayerFlags(
              autoPlay: false,
              mute: true,
              disableDragSeek: true,
            ),
          );
          setState(() {});
        } else if (!isVisible && _controller != null) {
          _controller?.dispose();
          _controller = null;
          setState(() {});
        }
      },
      child: _controller != null 
          ? YoutubePlayer(controller: _controller!)
          : Image.network(
              'https://img.youtube.com/vi/$_videoId/mqdefault.jpg',
              fit: BoxFit.cover,
              width: double.infinity,
              height: 200,
            ),
    );
  }

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

二、解决autoPlay为false仍自动加载的问题 #

原代码在initState中直接初始化控制器，导致资源提前加载。解决方式为：

1. 延迟控制器初始化：参考上述两种方案，仅在用户点击或组件可见时创建YoutubePlayerController，避免列表构建阶段触发资源请求。
2. 升级包版本：部分旧版youtube_player_flutter存在autoPlay参数不生效的问题，建议升级至最新稳定版。

内容的提问来源于stack exchange，提问作者Ahmed Usama