使用CupertinoTabScaffold切换标签时dispose函数未触发的问题

问题背景 #

使用CupertinoTabScaffold和CupertinoTabBar开发时，切换标签页时自定义组件CustumPageViewBuilder的dispose函数不会执行，导致内部通过Timer.periodic实现的自动切换逻辑无法被取消，持续占用资源。

问题原因 #

CupertinoTabScaffold默认会缓存所有标签页的State实例，切换标签时不会销毁页面组件，因此组件的dispose生命周期方法不会被触发。

解决方案 #

方案一：禁用页面状态缓存 #

给承载CustumPageViewBuilder的标签页页面添加AutomaticKeepAliveClientMixin，并返回false，让页面在切换时自动销毁State，触发dispose。

示例代码：

class WordTabPage extends StatefulWidget {
  const WordTabPage({super.key, required this.words});
  final List words;

  @override
  State<WordTabPage> createState() => _WordTabPageState();
}

class _WordTabPageState extends State<WordTabPage> with AutomaticKeepAliveClientMixin {
  @override
  bool get wantKeepAlive => false; // 关闭状态缓存

  @override
  Widget build(BuildContext context) {
    super.build(context); // 必须调用super.build
    return CustumPageViewBuilder(words: widget.words);
  }
}

方案二：手动控制Timer启停 #

通过CupertinoTabController监听标签页切换事件，在页面切换时主动控制Timer的启动与取消，适合需要保留页面状态的场景。

步骤1：修改CustumPageViewBuilder，暴露Timer控制方法

class CustumPageViewBuilder extends StatefulWidget {
  const CustumPageViewBuilder({
    super.key,
    required this.words,
  });

  final List words;

  @override
  State<CustumPageViewBuilder> createState() => _CustumPageViewBuilderState();
}

class _CustumPageViewBuilderState extends State<CustumPageViewBuilder> {
  late final PageController ctrlPageView;
  Timer? timer;
  int currentIndex = 0;

  @override
  void initState() {
    super.initState();
    ctrlPageView = PageController(initialPage: 0);
    _startTimer();
  }

  // 启动Timer
  void _startTimer() {
    timer = Timer.periodic(
      const Duration(seconds: 2),
      (timer) {
        if (currentIndex == 10) currentIndex = 0;
        ctrlPageView.animateToPage(
          currentIndex++,
          duration: const Duration(milliseconds: 800),
          curve: Curves.easeIn,
        );
      },
    );
  }

  // 取消Timer
  void stopTimer() {
    timer?.cancel();
    timer = null;
  }

  @override
  void dispose() {
    stopTimer();
    ctrlPageView.dispose(); // 别忘了销毁PageController
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return PageView.builder(
      controller: ctrlPageView,
      itemCount: widget.words.length,
      itemBuilder: (context, index) {
        return Column(
          mainAxisAlignment: MainAxisAlignment.spaceAround,
          children: [
            Text(
              widget.words[index]["true"]!,
              style: const TextStyle(fontSize: 18),
            ),
            const Center(
              child: Icon(
                CupertinoIcons.arrow_2_circlepath,
                color: CupertinoColors.systemPink,
                size: 30,
              ),
            ),
            Text(
              widget.words[index]["false"]!,
              style: const TextStyle(fontSize: 18),
            ),
          ],
        );
      },
    );
  }
}

步骤2：在父组件中监听标签切换，控制Timer

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

  @override
  State<MainTabScaffold> createState() => _MainTabScaffoldState();
}

class _MainTabScaffoldState extends State<MainTabScaffold> {
  late final CupertinoTabController _tabController;
  _CustumPageViewBuilderState? _pageViewState;

  @override
  void initState() {
    super.initState();
    _tabController = CupertinoTabController();
    _tabController.addListener(_onTabChanged);
  }

  void _onTabChanged() {
    // 假设自定义组件在索引0的标签页
    if (_tabController.index == 0) {
      _pageViewState?._startTimer();
    } else {
      _pageViewState?.stopTimer();
    }
  }

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

  @override
  Widget build(BuildContext context) {
    return CupertinoTabScaffold(
      controller: _tabController,
      tabBar: CupertinoTabBar(
        items: const [
          BottomNavigationBarItem(icon: Icon(CupertinoIcons.book), label: "单词"),
          BottomNavigationBarItem(icon: Icon(CupertinoIcons.settings), label: "设置"),
        ],
      ),
      tabBuilder: (context, index) {
        switch (index) {
          case 0:
            return CupertinoTabView(
              builder: (context) => Builder(
                builder: (context) {
                  return CustumPageViewBuilder(
                    words: [], // 传入你的数据
                    key: GlobalKey(debugLabel: "pageViewKey"),
                  );
                },
              ),
            );
          case 1:
            return CupertinoTabView(builder: (context) => const SettingsPage());
          default:
            return const SizedBox();
        }
      },
    );
  }
}

注意事项 #

• 方案一适合不需要保留页面状态的场景，切换后页面会重新初始化；
• 方案二需要通过GlobalKey或其他方式获取组件State实例，实现更灵活的状态控制；
• 无论哪种方案，都要确保在dispose中销毁PageController和Timer，避免内存泄漏。

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