Flutter FutureBuilder分块渲染数组及布局报错解决

报错核心原因 #

你遇到的RenderBox was not laid out: RenderRepaintBoundary#xxx NEEDS-PAINT、Failed assertion: 'hasSize'布局错误，本质是嵌套可滚动组件的约束冲突：

• 外层SingleChildScrollView作为全页纵向滚动容器，子节点的纵向布局约束是无界的，内部嵌套的纵向ListView.builder本身也是可滚动组件，仅设置shrinkWrap: true但未禁用自身滚动时，会和父容器争抢布局高度，无法完成尺寸测量
• 横向滚动的ListView.builder在Column布局中没有明确高度约束时，会在无界高度下无法计算自身尺寸
• 纯shrinkWrap嵌套列表会一次性渲染所有子项，长数据场景下不仅性能差，还容易触发布局时序异常

最小改动修复方案 #

保持你现有StatefulWidget+FutureBuilder的架构不变，仅调整列表属性配置即可解决报错：

• 所有纵向ListView.builder除shrinkWrap: true外，必须添加physics: const NeverScrollableScrollPhysics()，禁用子列表自身的滚动响应，将滚动控制权完全交给外层SingleChildScrollView
• 对应one数组的横向ListView.builder，外层必须包裹固定高度的SizedBox或ConstrainedBox，给横向列表明确的高度约束
• 加载态、错误态组件外层包裹Center，避免组件在无界约束下无法计算尺寸
• 提前在状态类中存储接口请求的Future对象，避免页面rebuild时重复触发接口请求

核心实现代码参考：

// 状态类中提前存储请求Future，避免rebuild重复触发请求
late Future<HomeResponseModel> _homeFuture;

@override
void initState() {
  super.initState();
  _homeFuture = getHome();
}

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SafeArea(
      child: FutureBuilder<HomeResponseModel>(
        future: _homeFuture,
        builder: (context, snapshot) {
          // 加载态
          if (snapshot.connectionState != ConnectionState.done) {
            return const Center(child: CircularProgressIndicator());
          }
          // 错误态
          if (snapshot.hasError) {
            return Center(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Text('数据加载失败：${snapshot.error}'),
              ),
            );
          }
          // 数据渲染
          final homeData = snapshot.data!;
          return SingleChildScrollView(
            padding: const EdgeInsets.all(16),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                // one数组 横向滚动区块
                const Text('精选', style: TextStyle(fontSize: 18, fontWeight: FontWeight.w600)),
                const SizedBox(height: 12),
                SizedBox(
                  height: 160, // 按你的卡片设计调整高度
                  child: ListView.builder(
                    scrollDirection: Axis.horizontal,
                    itemCount: homeData.one.length,
                    itemBuilder: (context, index) => OneItemCard(data: homeData.one[index]),
                  ),
                ),
                const SizedBox(height: 28),

                // two数组 纵向区块
                const Text('热门推荐', style: TextStyle(fontSize: 18, fontWeight: FontWeight.w600)),
                const SizedBox(height: 12),
                ListView.builder(
                  shrinkWrap: true,
                  physics: const NeverScrollableScrollPhysics(), // *关键配置
                  itemCount: homeData.two.length,
                  itemBuilder: (context, index) => TwoItemCard(data: homeData.two[index]),
                ),
                const SizedBox(height: 28),

                // three数组 纵向区块
                const Text('最新内容', style: TextStyle(fontSize: 18, fontWeight: FontWeight.w600)),
                const SizedBox(height: 12),
                ListView.builder(
                  shrinkWrap: true,
                  physics: const NeverScrollableScrollPhysics(), // *关键配置
                  itemCount: homeData.three.length,
                  itemBuilder: (context, index) => ThreeItemCard(data: homeData.three[index]),
                ),
                const SizedBox(height: 28),

                // four数组 纵向区块
                const Text('分类专区', style: TextStyle(fontSize: 18, fontWeight: FontWeight.w600)),
                const SizedBox(height: 12),
                ListView.builder(
                  shrinkWrap: true,
                  physics: const NeverScrollableScrollPhysics(), // *关键配置
                  itemCount: homeData.four.length,
                  itemBuilder: (context, index) => FourItemCard(data: homeData.four[index]),
                ),
                const SizedBox(height: 28),

                // five数组 纵向区块
                const Text('更多服务', style: TextStyle(fontSize: 18, fontWeight: FontWeight.w600)),
                const SizedBox(height: 12),
                ListView.builder(
                  shrinkWrap: true,
                  physics: const NeverScrollableScrollPhysics(), // *关键配置
                  itemCount: homeData.five.length,
                  itemBuilder: (context, index) => FiveItemCard(data: homeData.five[index]),
                ),
              ],
            ),
          );
        },
      ),
    ),
  );
}

性能优化方案 #

如果你的各数组数据量较大，shrinkWrap嵌套列表会一次性渲染所有子项，丢失列表懒加载能力，建议替换为CustomScrollView统一管理滚动：

• 用SliverToBoxAdapter包裹区块标题、横向滚动列表这类固定高度的组件
• 各纵向数组区块直接使用SliverList实现懒加载渲染，不需要设置shrinkWrap，也不存在滚动冲突问题，长列表场景下帧率表现更好
• 后续如果要加吸顶区块、下拉刷新、上拉加载能力，基于Sliver体系扩展成本极低

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