Flutter ListView.builder设置Axis.horizontal触发box.dart报错

Flutter开发中为ListView.builder配置scrollDirection: Axis.horizontal属性实现水平滚动列表时，代码运行触发异常，自动跳转至框架内置的box.dart页面抛出布局约束相关错误。即使尝试过为列表外层包裹Expanded组件、声明固定高度等常见修复方案，仍会复现相同报错。

水平滚动的ListView在布局时，要求垂直交叉轴方向必须拿到明确的有界约束，常规方案失效基本都是踩了以下几个容易忽略的坑：

• 只给ListView本身设置高度，没有检查中间嵌套组件：如果ListView和固定高度容器之间夹了Row、嵌套的其他滚动视图（ListView/SingleChildScrollView）、Flexible/Expanded这类会透传无界约束的组件，固定高度的设置会直接失效
• 列表子项错误设置了相对约束：比如给水平列表的子项设置了double.infinity高度、百分比高度，或者子项外层套了Align/Center/Positioned这类会重新调整约束的组件，会导致列表无法计算交叉轴尺寸
• 外层Column/Row的约束传递逻辑冲突：如果在Column里嵌套水平列表，给列表外层同时套SizedBox（固定高度）和Expanded，会导致垂直方向约束被改成无界

// Column嵌套水平列表的标准无错写法
Column(
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    // 其余业务组件
    SizedBox(
      // 必须在水平列表的最近一层父组件指定明确高度，不要额外套Flex类组件
      height: 110,
      child: ListView.builder(
        padding: const EdgeInsets.symmetric(horizontal: 12),
        scrollDirection: Axis.horizontal,
        itemCount: 8,
        itemBuilder: (context, index) {
          return Container(
            width: 100,
            // 子项不要设置无界高度，默认占满父容器给定高度即可
            margin: const EdgeInsets.only(right: 12),
            decoration: BoxDecoration(
              color: Colors.grey[200],
              borderRadius: BorderRadius.circular(8),
            ),
          );
        },
      ),
    ),
    // 其余业务组件
  ],
)

如果上述方案仍未解决问题，直接在box.dart的报错断言处查看调用栈，找到距离异常最近的你自己编写的业务组件位置，检查该位置父组件传递的约束：只要水平ListView的垂直方向maxHeight不是无限值，就不会触发该类布局报错。

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