Flutter PageView调用setState后重置至第0页问题排查

我在初始显示的Page上方添加了提示用户左滑进入下一页的文本，通过userHasSlided布尔值控制该文本的显示与隐藏——在onPageChanged回调中设置userHasSlided = true并调用setState。但滑动到第1页时，调用setState后PageView会直接重置回第0页；移除该条件渲染的提示文本后，PageView滑动恢复正常。

完整示例代码：

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

void main() {
  runApp(PageViewTestScreen());
}

class PageViewTestScreen extends StatefulWidget {
  PageViewTestScreen({super.key});

  @override
  State<PageViewTestScreen> createState() => _PageViewTestScreenState();
}

class _PageViewTestScreenState extends State<PageViewTestScreen> {
  PageController pageController = PageController(initialPage: 0);
  bool lastPage = false;
  bool userHasSlided = false;
  int numberOfPages = 5;

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

  void onPageChanged(int index) {
    userHasSlided = true;

    lastPage = index == numberOfPages - 1; // 修正原代码未定义变量问题
    setState(() {});
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        floatingActionButton: lastPage
            ? FloatingActionButton(
                onPressed: () {},
                child: Icon(Icons.check),
              )
            : null,
        appBar: AppBar(
          foregroundColor: Colors.white,
          title: const Text("PageView bug?"),
        ),
        body: ListView(
          children: [
            const Text("Here are some pages"),
            const SizedBox(height: 6),
            if (!userHasSlided) const Text("Swipe left to continue."),
            SizedBox(
              height: 500,
              child: PageView(
                scrollBehavior: const ScrollBehavior().copyWith(dragDevices: {
                  PointerDeviceKind.touch,
                  PointerDeviceKind.mouse,
                  PointerDeviceKind.stylus,
                }),
                controller: pageController,
                onPageChanged: (int index) {
                  onPageChanged(index);
                },
                children: [
                  for (int i = 0; i < 5; i++) card(i),
                ],
              ),
            )
          ],
        ),
      ),
    );
  }

  Widget card(int index) {
    return Card(
      child: SizedBox(
          height: 500, width: 200, child: Center(child: Text("Page: $index"))),
    );
  }
}

原因分析 #

这不是Flutter的Bug，而是忽略了布局交互的关键细节：
当userHasSlided变为true，提示文本被移除，ListView的内容高度发生变化，ListView会自动滚动到顶部（因为可用内容高度减少）。这个滚动动作会干扰PageView的布局上下文，导致PageController的初始页面配置（initialPage: 0）被重新触发，从而将PageView重置回第0页。

解决方案 #

方案1：将PageView从ListView中移出 #

用Column+Expanded替代ListView，避免内容高度变化触发的滚动干扰PageView：

@override
Widget build(BuildContext context) {
  return MaterialApp(
    home: Scaffold(
      floatingActionButton: lastPage
          ? FloatingActionButton(
              onPressed: () {},
              child: Icon(Icons.check),
            )
          : null,
      appBar: AppBar(
        foregroundColor: Colors.white,
        title: const Text("PageView bug?"),
      ),
      body: Column(
        children: [
          const Text("Here are some pages"),
          const SizedBox(height: 6),
          if (!userHasSlided) const Text("Swipe left to continue."),
          const SizedBox(height: 6),
          Expanded(
            child: PageView(
              scrollBehavior: const ScrollBehavior().copyWith(dragDevices: {
                PointerDeviceKind.touch,
                PointerDeviceKind.mouse,
                PointerDeviceKind.stylus,
              }),
              controller: pageController,
              onPageChanged: (int index) {
                onPageChanged(index);
              },
              children: [
                for (int i = 0; i < 5; i++) card(i),
              ],
            ),
          )
        ],
      ),
    ),
  );
}

方案2：固定ListView的滚动位置 #

给ListView添加独立的ScrollController，避免内容变化时自动滚动：

class _PageViewTestScreenState extends State<PageViewTestScreen> {
  PageController pageController = PageController(initialPage: 0);
  ScrollController listController = ScrollController(); // 添加ListView控制器
  bool lastPage = false;
  bool userHasSlided = false;
  int numberOfPages = 5;

  // ... 其他代码不变

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        // ... 其他代码不变
        body: ListView(
          controller: listController, // 绑定控制器
          children: [
            // ... 子元素不变
          ],
        ),
      ),
    );
  }
}

方案3：延迟更新状态 #

用Future.delayed让PageView完成滑动后再更新userHasSlided，避免布局冲突：

void onPageChanged(int index) {
  lastPage = index == numberOfPages - 1;
  // 延迟100ms更新状态，让PageView完成滑动布局
  Future.delayed(const Duration(milliseconds: 100), () {
    if (mounted) {
      setState(() {
        userHasSlided = true;
      });
    }
  });
}

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