Flutter列表中多不同GIF播放同步异常问题求助

问题场景 #

训练列表页面用ListView.builder展示带不同GIF的训练项，每个GIF时长2秒，但播放逻辑异常：第一个GIF播放1秒后暂停，需等列表中所有其他GIF完成第1秒播放，才继续播放第一个GIF的第2秒，循环往复。尝试cached_network_image、Image.memory、Image.file三种加载方式均存在该问题，仅当所有GIF相同时播放正常。

核心原因 #

Flutter默认GIF渲染逻辑中，不同ImageProvider会共享全局帧调度，多个不同GIF同时加载时，帧更新被串行化，导致播放不同步。

解决方案 #

为每个GIF分配独立的播放生命周期，避免全局调度冲突，以下是两种可行实现方式：

方案1：自定义独立GIF播放器 #

手动解码GIF帧并为每个实例创建独立动画控制器，彻底隔离播放逻辑：

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

class IndependentGifPlayer extends StatefulWidget {
  final Uint8List gifBytes;
  final double width;
  final double height;
  final BoxFit fit;

  const IndependentGifPlayer({
    Key? key,
    required this.gifBytes,
    required this.width,
    required this.height,
    this.fit = BoxFit.fill,
  }) : super(key: key);

  @override
  State<IndependentGifPlayer> createState() => _IndependentGifPlayerState();
}

class _IndependentGifPlayerState extends State<IndependentGifPlayer> with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Uint8List _gifBytes;
  List<FrameInfo> _frames = [];
  bool _isInitialized = false;

  @override
  void initState() {
    super.initState();
    _gifBytes = widget.gifBytes;
    _initGifFrames();
  }

  @override
  void didUpdateWidget(covariant IndependentGifPlayer oldWidget) {
    if (oldWidget.gifBytes != widget.gifBytes) {
      _gifBytes = widget.gifBytes;
      _initGifFrames();
    }
    super.didUpdateWidget(oldWidget);
  }

  void _initGifFrames() async {
    _frames = await _decodeGifFrames(_gifBytes);
    if (_frames.isEmpty) return;

    final totalDuration = _frames.fold(Duration.zero, (sum, frame) => sum + frame.duration);
    _controller = AnimationController(
      vsync: this,
      duration: totalDuration,
    )..repeat();

    setState(() => _isInitialized = true);
  }

  Future<List<FrameInfo>> _decodeGifFrames(Uint8List bytes) async {
    final codec = await PaintingBinding.instance.instantiateImageCodec(bytes);
    final frames = <FrameInfo>[];
    while (true) {
      final frame = await codec.getNextFrame();
      if (frame.frame == null) break;
      frames.add(FrameInfo(frame.image, frame.duration));
    }
    return frames;
  }

  @override
  void dispose() {
    _controller.dispose();
    for (var frame in _frames) frame.image.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    if (!_isInitialized || _frames.isEmpty) {
      return const Center(child: CircularProgressIndicator());
    }

    return AnimatedBuilder(
      animation: _controller,
      builder: (context, child) {
        final elapsed = _controller.value * _controller.duration!.inMicroseconds;
        int currentIndex = 0;
        Duration accumulated = Duration.zero;
        for (var i = 0; i < _frames.length; i++) {
          accumulated += _frames[i].duration;
          if (accumulated.inMicroseconds >= elapsed) {
            currentIndex = i;
            break;
          }
        }
        return Image(
          image: MemoryImage(_frames[currentIndex].image.toByteData()!.buffer.asUint8List()),
          width: widget.width,
          height: widget.height,
          fit: widget.fit,
        );
      },
    );
  }
}

class FrameInfo {
  final Image image;
  final Duration duration;

  FrameInfo(this.image, this.duration);
}

修改ImageLoader使用自定义播放器：

import 'package:http/http.dart' as http;
// ... 其他导入

class ImageLoader extends StatelessWidget {
  // ... 原有参数

  @override
  Widget build(BuildContext context) {
    return ClipRRect(
      borderRadius: borderRadius ?? BorderRadius.circular(10),
      child: FutureBuilder<Uint8List>(
        future: _downloadGif(imageUrl),
        builder: (context, snapshot) {
          if (snapshot.connectionState == ConnectionState.waiting) {
            return const Spinkit();
          } else if (snapshot.hasError) {
            return Center(
              child: Icon(Icons.error, color: Colors.red.withOpacity(0.7), size: 30),
            );
          } else if (snapshot.hasData) {
            return IndependentGifPlayer(
              gifBytes: snapshot.data!,
              width: width,
              height: height,
              fit: fit ?? BoxFit.fill,
            );
          }
          return const SizedBox();
        },
      ),
    );
  }

  Future<Uint8List> _downloadGif(String url) async {
    final response = await http.get(Uri.parse(url));
    if (response.statusCode == 200) return response.bodyBytes;
    throw Exception('GIF下载失败');
  }
}

方案2：使用第三方库flutter_gif #

借助成熟库快速实现独立播放控制：

1. 添加依赖到pubspec.yaml：

dependencies:
  flutter_gif: ^1.2.0

2. 重写ImageLoader为状态组件：

import 'package:flutter_gif/flutter_gif.dart';
import 'package:http/http.dart' as http;
// ... 其他导入

class ImageLoader extends StatefulWidget {
  const ImageLoader({
    Key? key,
    required this.imageUrl,
    // ... 原有参数
  }) : super(key: key);

  // ... 原有参数

  @override
  State<ImageLoader> createState() => _ImageLoaderState();
}

class _ImageLoaderState extends State<ImageLoader> with SingleTickerProviderStateMixin {
  late FlutterGifController _controller;
  Uint8List? _gifBytes;
  bool _isLoaded = false;

  @override
  void initState() {
    super.initState();
    _controller = FlutterGifController(vsync: this);
    _loadGif();
  }

  @override
  void didUpdateWidget(covariant ImageLoader oldWidget) {
    if (oldWidget.imageUrl != widget.imageUrl) _loadGif();
    super.didUpdateWidget(oldWidget);
  }

  void _loadGif() async {
    final response = await http.get(Uri.parse(widget.imageUrl));
    if (response.statusCode == 200) {
      setState(() {
        _gifBytes = response.bodyBytes;
        _isLoaded = true;
      });
      final codec = PaintingBinding.instance.instantiateImageCodecSync(_gifBytes!);
      _controller.repeat(
        min: 0,
        max: codec.frameCount - 1,
        period: const Duration(seconds: 2),
      );
    }
  }

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

  @override
  Widget build(BuildContext context) {
    return ClipRRect(
      borderRadius: widget.borderRadius ?? BorderRadius.circular(10),
      child: _isLoaded && _gifBytes != null
          ? GifImage(
              controller: _controller,
              image: MemoryImage(_gifBytes!),
              width: widget.width,
              height: widget.height,
              fit: widget.fit ?? BoxFit.fill,
            )
          : _isLoaded
              ? Center(child: Icon(Icons.error, color: Colors.red.withOpacity(0.7), size: 30))
              : const Spinkit(),
    );
  }
}

关键说明 #

两种方案核心都是为每个GIF分配独立的播放控制器，避免Flutter默认全局帧调度的串行化限制。方案1无需依赖第三方库，适合需要自定义逻辑的场景；方案2更简洁，适合快速落地。

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