[PageView] 向上滚动时BouncingScrollPhysics未生效问题排查与修复

问题描述 #

使用Flutter的PageView组件搭配BouncingScrollPhysics时，遇到垂直滚动并锁定特定页面后滚动物理效果异常的问题，重现步骤如下：

• 滚动至第6页
• 点击锁定按钮激活锁定状态
• 向上滚动页面

观察到的行为 #

• 页面索引变化为：7 → 6 → 10
• 索引直接跳至10，未被BouncingScrollPhysics阻止

预期行为 #

• 顺序滚动（如0 → 1 → 2 → 3 → 4 → 5）时，BouncingScrollPhysics应正常阻止滚动并回弹
• 无论滚动方向或锁定状态如何，滚动物理效果保持一致

代码示例 #

最小可复现代码：

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  bool lock = false;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Random Color PageView',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Random Color PageView'),
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () {
            setState(() {
              lock = !lock;
            });
          },
          child: const Icon(Icons.lock),
        ),
        body: RandomColorPageView(
          lock: lock,
        ),
      ),
    );
  }
}

class RandomColorPageView extends StatelessWidget {
  final Random _random = Random();

  RandomColorPageView({super.key, required this.lock});
  final bool lock;

  @override
  Widget build(BuildContext context) {
    return PageView.builder(
      physics: const BouncingScrollPhysics(),
      scrollDirection: Axis.vertical,
      itemBuilder: (context, index) {
        final Color randomColor = Color.fromARGB(
          255,
          _random.nextInt(256),
          _random.nextInt(256),
          _random.nextInt(256),
        );
        if (index == 5 && lock) {
          return null;
        }

        Widget child = Container(
          width: double.infinity,
          height: double.infinity,
          color: randomColor,
          child: Center(
            child: Text(
              'Page $index',
              style: const TextStyle(
                fontSize: 48,
                color: Colors.white,
                fontWeight: FontWeight.bold,
              ),
            ),
          ),
        );

        if (lock) {
          child = ColoredBox(
            color: Colors.red,
            child: Padding(
              padding: const EdgeInsets.all(8),
              child: child,
            ),
          );
        }

        return child;
      },
    );
  }
}

问题根源 #

当lock为true时，itemBuilder对index == 5返回了null，这会破坏PageView的正常逻辑：

• PageView的滚动物理效果依赖于对页面序列的准确识别，返回null会让PageView认为该位置无有效页面，进而跳过该索引查找后续页面，直接导致滚动索引跳变
• BouncingScrollPhysics的回弹效果基于页面首尾边界触发，页面序列被null打断后，边界判断逻辑失效，无法正常触发回弹

修复方案 #

核心思路：禁止在itemBuilder中返回null，改为通过自定义滚动逻辑实现锁定效果。

修改后的完整代码：

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  bool lock = false;
  final PageController _pageController = PageController();

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Random Color PageView',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Random Color PageView'),
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () {
            setState(() {
              lock = !lock;
              // 锁定时若当前在第5页，自动跳转到第6页
              if (lock && _pageController.page?.floor() == 5) {
                _pageController.jumpToPage(6);
              }
            });
          },
          child: Icon(lock ? Icons.lock_open : Icons.lock),
        ),
        body: RandomColorPageView(
          lock: lock,
          pageController: _pageController,
        ),
      ),
    );
  }
}

class RandomColorPageView extends StatelessWidget {
  final Random _random = Random();
  final bool lock;
  final PageController pageController;

  RandomColorPageView({super.key, required this.lock, required this.pageController});

  @override
  Widget build(BuildContext context) {
    return PageView.builder(
      controller: pageController,
      // 锁定时使用自定义物理效果，否则保持原Bouncing效果
      physics: lock ? _LockedScrollPhysics(parent: const BouncingScrollPhysics()) : const BouncingScrollPhysics(),
      scrollDirection: Axis.vertical,
      itemBuilder: (context, index) {
        final Color randomColor = Color.fromARGB(
          255,
          _random.nextInt(256),
          _random.nextInt(256),
          _random.nextInt(256),
        );

        Widget child = Container(
          width: double.infinity,
          height: double.infinity,
          color: randomColor,
          child: Center(
            child: Text(
              'Page $index',
              style: const TextStyle(
                fontSize: 48,
                color: Colors.white,
                fontWeight: FontWeight.bold,
              ),
            ),
          ),
        );

        if (lock) {
          child = ColoredBox(
            color: Colors.red,
            child: Padding(
              padding: const EdgeInsets.all(8),
              child: child,
            ),
          );
        }

        return child;
      },
    );
  }
}

// 自定义滚动物理，锁定时阻止滚动到第5页及以下
class _LockedScrollPhysics extends ScrollPhysics {
  const _LockedScrollPhysics({super.parent});

  @override
  _LockedScrollPhysics applyTo(ScrollPhysics? ancestor) {
    return _LockedScrollPhysics(parent: buildParent(ancestor));
  }

  @override
  double applyBoundaryConditions(ScrollMetrics position, double value) {
    // 计算第5页对应的滚动位置（假设每页高度等于视口高度）
    final double maxScrollBelow = position.viewportDimension * 5;
    // 试图向上滚动到第5页及以下时，触发回弹
    if (value < maxScrollBelow && position.pixels >= maxScrollBelow) {
      return value - maxScrollBelow;
    }
    return super.applyBoundaryConditions(position, value);
  }
}

修复说明 #

1. 移除null返回：确保所有索引都返回有效页面，让PageView能正确计算滚动边界
2. 自定义ScrollPhysics：继承BouncingScrollPhysics，重写边界判断逻辑，锁定状态下阻止滚动到第5页及以下，保留正常回弹效果
3. PageController控制：切换锁定状态时，自动将页面跳转到第6页（若当前在第5页），避免停留在被限制的页面

修改后，锁定状态下向上滚动会触发正常的Bouncing回弹效果，不会出现索引跳变，同时保留原有的锁定视觉标记。

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