Flutter中FutureBuilder嵌套PageView.Builder报错问题咨询

问题场景 #

我是Flutter新手，编写了CardCarousel组件，使用FutureBuilder调用_initImages方法加载本地图片路径列表，运行时抛出异常，想确认问题是因空值导致还是需要添加更多条件渲染。

组件代码 #

class CardCarousel extends Stateful Widget {
  const CardCarousel({super.key});

  @override
  State<CardCarousel> createState() => _CardCarouselState();
}

class _CardCarouselState extends State<CardCarousel> {
  List<String> imagePaths = [];

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

  Future<List<String>> _initImages() async {
    final manifestContent = await rootBundle.loadString('AssetManifest.json');
    final Map<String, dynamic> manifestMap = json.decode(manifestContent);
    List<String> imagePaths = manifestMap.keys
        .where((String key) => key.contains('assets/images/png/'))
        .where((String key) => key.contains('.png'))
        .toList();

    return imagePaths;
  }

  @override
  Widget build(BuildContext context) {
    final PageController controller = PageController();
    return FutureBuilder(
        future: _initImages(),
        builder: (context, AsyncSnapshot<List<String>> snapshot) {
          switch (snapshot.connectionState) {
            case ConnectionState.done:
              if (snapshot.data == null) {
                return Text('NO IMAGES');
              } else {
                setState(() {
                  imagePaths = snapshot.data!;
                });
              }
              break;
            case ConnectionState.none:
              print('NONE');
              break;
            case ConnectionState.waiting:
              print('WAITING');
              break;
            case ConnectionState.active:
              print('active');
              break;
          }

          return PageView.builder(
              controller: controller,
              itemCount: imagePaths.length,
              itemBuilder: (_, int index) {
                return CustomCard(imageURL: imagePaths[index]);
              });
        });
  }
}

抛出错误 #

This CardCarousel widget cannot be marked as needing to build because the framework is already in the process of building widgets. A widget can be marked as needing to be built during the build phase only if one of its ancestors is currently building. This exception is allowed because the framework builds parent widgets before children, which means a dirty descendant will always be built. Otherwise, the framework might not visit this widget during this build phase.

问题原因 #

这个错误既不是空值导致，也不是条件渲染不足的问题，核心原因是：

1. 在FutureBuilder的builder方法中调用了setState()——builder本身就是Flutter构建UI的阶段，此时调用setState会触发组件重新构建，违反了Flutter的构建流程，导致框架抛出异常。
2. 额外问题：每次执行build方法都会重新调用_initImages()，导致重复发起异步请求，浪费资源。

解决方案 #

方案一：直接使用FutureBuilder的快照数据（推荐） #

不需要将数据存在组件状态中，直接利用FutureBuilder的snapshot数据渲染UI，同时将异步请求的结果缓存起来，避免重复执行：

class CardCarousel extends Stateful Widget {
  const CardCarousel({super.key});

  @override
  State<CardCarousel> createState() => _CardCarouselState();
}

class _CardCarouselState extends State<CardCarousel> {
  // 缓存异步请求结果，避免每次build重新执行
  late final Future<List<String>> _imageFuture;

  @override
  void initState() {
    super.initState();
    _imageFuture = _initImages();
  }

  Future<List<String>> _initImages() async {
    final manifestContent = await rootBundle.loadString('AssetManifest.json');
    final Map<String, dynamic> manifestMap = json.decode(manifestContent);
    return manifestMap.keys
        .where((key) => key.contains('assets/images/png/') && key.endsWith('.png'))
        .toList();
  }

  @override
  Widget build(BuildContext context) {
    final PageController controller = PageController();
    return FutureBuilder(
        future: _imageFuture,
        builder: (context, AsyncSnapshot<List<String>> snapshot) {
          // 加载中状态
          if (snapshot.connectionState == ConnectionState.waiting) {
            return const Center(child: CircularProgressIndicator());
          }
          // 错误状态
          if (snapshot.hasError) {
            return Text('加载失败: ${snapshot.error}');
          }
          // 空数据状态
          if (!snapshot.hasData || snapshot.data!.isEmpty) {
            return const Text('NO IMAGES');
          }
          // 成功加载，直接使用快照数据
          return PageView.builder(
              controller: controller,
              itemCount: snapshot.data!.length,
              itemBuilder: (_, int index) {
                return CustomCard(imageURL: snapshot.data![index]);
              });
        });
  }
}

方案二：在initState中处理异步请求，更新状态 #

如果确实需要将数据存在组件状态中，可以在initState里启动异步加载，通过setState更新状态，再根据状态渲染UI：

class CardCarousel extends Stateful Widget {
  const CardCarousel({super.key});

  @override
  State<CardCarousel> createState() => _CardCarouselState();
}

class _CardCarouselState extends State<CardCarousel> {
  List<String> imagePaths = [];
  bool isLoading = true;
  String? errorMessage;

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

  Future<void> _loadImages() async {
    try {
      final manifestContent = await rootBundle.loadString('AssetManifest.json');
      final Map<String, dynamic> manifestMap = json.decode(manifestContent);
      final paths = manifestMap.keys
          .where((key) => key.contains('assets/images/png/') && key.endsWith('.png'))
          .toList();
      
      setState(() {
        imagePaths = paths;
        isLoading = false;
      });
    } catch (e) {
      setState(() {
        errorMessage = e.toString();
        isLoading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    final PageController controller = PageController();
    
    // 加载中
    if (isLoading) {
      return const Center(child: CircularProgressIndicator());
    }
    
    // 加载错误
    if (errorMessage != null) {
      return Text('加载失败: $errorMessage');
    }
    
    // 无图片
    if (imagePaths.isEmpty) {
      return const Text('NO IMAGES');
    }

    // 渲染轮播
    return PageView.builder(
        controller: controller,
        itemCount: imagePaths.length,
        itemBuilder: (_, int index) {
          return CustomCard(imageURL: imagePaths[index]);
        });
  }
}

总结 #

你的错误核心是在UI构建阶段调用了setState，和空值、条件渲染无关，按照上述任意一种方案修正即可解决问题。

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