Flutter页面滚动报错：PrimaryScrollController绑定多个滚动组件

问题场景 #

开发的分类餐单页面滚动时触发错误：

The PrimaryScrollController is currently attached to more than one Scrollable widget.

页面采用外层ScrollablePositionedList嵌套内层ListView的结构，每个分类下对应一个商品列表。

核心原因 #

Flutter的PrimaryScrollController会自动绑定到页面中的滚动组件，当页面存在多个滚动组件（外层ScrollablePositionedList + 多个内层ListView）时，它们会争抢同一个全局控制器，导致冲突报错。

修复方案 #

1. 禁用内层ListView的PrimaryScrollController绑定 #

在内层ListView中添加primary: false，明确告知Flutter该组件不使用全局的PrimaryScrollController，避免冲突。

2. 优化滚动逻辑（可选） #

如果希望整个页面仅由外层统一滚动，无需内层列表独立滚动，可以给内层ListView设置physics: const NeverScrollableScrollPhysics()，让它仅负责布局，不响应滚动事件。

修改后的核心代码 #

CupertinoScrollbar _buildBody() {
    return CupertinoScrollbar(
      child: ScrollablePositionedList.builder(
        physics: const BouncingScrollPhysics(),
        itemScrollController: _itemScrollController,
        itemPositionsListener: _itemPositionsListener,
        padding: EdgeInsets.zero,
        itemCount: Dummy.categories.length,
        itemBuilder: (context, index) {
          return Column(
            children: [
              CustomTextWidget(
                paddingTop: 16,
                paddingLeft: 16,
                paddingBottom: 16,
                alignment: Alignment.centerLeft,
                text: Text(
                  Dummy.categories.elementAt(index),
                  style: AppConstants.textStyle(
                      fontWeight: FontWeight.bold, fontSize: 28),
                ),
              ),
              ListView(
                shrinkWrap: true,
                primary: false, // 关键修复：禁用全局PrimaryScrollController绑定
                physics: const NeverScrollableScrollPhysics(), // 可选：让内层列表不独立滚动
                children: [
                  GestureDetector(
                      onTap: () {
                        setState(
                          () {
                            isExpanded = !isExpanded;
                          },
                        );
                      },
                      child:
                          isExpanded ? const ExpandedProductCard() : const ProductCard()),
                  const ProductCard(),
                  const ProductCard(),
                  const ProductCard(),
                  const ProductCard(),
                ],
              ),
              Container()
            ],
          );
        },
      ),
    );
  }

补充说明 #

• primary: false：必须添加，这是解决控制器冲突的核心，确保每个滚动组件使用独立的控制器或不绑定全局控制器。
• NeverScrollableScrollPhysics()：根据产品需求选择，如果需要内层列表可单独滚动，可保留原BouncingScrollPhysics()，但primary: false不能省略。

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