Flutter中ListView自动向上滚动问题的修复方案

滚动位置跳回顶部的核心原因是列表数据更新时的状态不一致和列表项未设置唯一Key导致组件重建，以下是具体修复步骤：

1. 修复数据更新逻辑，避免错误重置列表 #

原代码在Query的builder中错误地在每次数据更新时重置allPosts，同时在fetchMore的updateQuery中直接修改状态变量，导致状态不一致。修改如下：

• 移除无用的currentPostCount变量
• 在updateQuery中仅负责合并缓存数据，不直接修改allPosts
• 在builder中根据Query缓存的最新数据更新allPosts

2. 给列表项设置唯一Key #

确保Flutter能正确复用列表项，避免因数据更新导致整个列表重建，滚动位置丢失。

3. 添加加载状态锁，防止重复请求 #

避免滚动到底部时多次触发fetchMore，导致数据重复或状态混乱。

修改后的完整代码 #

import 'package:flutter/foundation.dart'; // 导入listEquals用于列表比较
import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

class PostsScreen extends StatefulWidget {
  final String categoryId;

  const PostsScreen({super.key, required this.categoryId});

  @override
  State<PostsScreen> createState() => _PostsScreenState();
}

class _PostsScreenState extends State<PostsScreen> {
  int postsPerPage = 5;
  List<Map<String, dynamic>> allPosts = [];
  final ScrollController _scrollController = ScrollController();
  FetchMore? _fetchMore;
  bool _isLoading = false; // 加载状态锁

  @override
  void initState() {
    super.initState();
    _scrollController.addListener(_onScroll);
  }

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

  void _onScroll() {
    if (_fetchMore == null || _isLoading) return;

    // 滚动到接近底部（90%位置）时触发加载，提升用户体验
    if (_scrollController.position.pixels >= _scrollController.position.maxScrollExtent * 0.9) {
      _isLoading = true;
      final FetchMoreOptions fetchMoreOpts = FetchMoreOptions(
        variables: {'offset': allPosts.length},
        updateQuery: (previousResultData, fetchMoreResultData) {
          final List<dynamic> previousPosts = previousResultData?['viewPosts'] ?? [];
          final List<dynamic> fetchedPosts = fetchMoreResultData?['viewPosts'] ?? [];
          // 合并新旧数据，更新Query缓存
          final List<dynamic> combinedPosts = [...previousPosts, ...fetchedPosts];
          return {
            ...previousResultData!,
            'viewPosts': combinedPosts,
          };
        },
      );

      // 请求完成后释放加载锁
      _fetchMore!(fetchMoreOpts).then((_) {
        setState(() => _isLoading = false);
      }).catchError((_) {
        setState(() => _isLoading = false);
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Query(
      options: QueryOptions(
        document: viewPostsQuery,
        variables: {
          "categoryId": widget.categoryId,
          "take": postsPerPage,
          "offset": 0, // 初始offset固定为0
        },
      ),
      builder: (QueryResult result, {VoidCallback? refetch, FetchMore? fetchMore}) {
        _fetchMore = fetchMore;

        // 加载中且无数据时显示加载指示器
        if (result.isLoading && allPosts.isEmpty) {
          return const Center(child: CircularProgressIndicator());
        }

        // 数据更新时同步allPosts，避免重复赋值
        if (result.data != null) {
          final posts = result.data!['viewPosts'] as List<dynamic>?;
          if (posts != null) {
            final List<Map<String, dynamic>> newPosts = posts.map((post) => post as Map<String, dynamic>).toList();
            if (!listEquals(allPosts, newPosts)) {
              setState(() => allPosts = newPosts);
            }
          }
        }

        return _buildListView();
      },
    );
  }

  Widget _buildListView() {
    return ListView.builder(
      controller: _scrollController,
      itemCount: allPosts.length,
      itemBuilder: ((context, index) {
        final post = allPosts[index];
        // 给每个列表项设置唯一Key，确保组件复用
        return Post(
          key: ValueKey(post['id']), // 替换成你的post唯一标识字段
          post: post,
        );
      }),
    );
  }
}

// 假设的Post组件
class Post extends StatelessWidget {
  final Map<String, dynamic> post;

  const Post({super.key, required this.post});

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(16),
      margin: const EdgeInsets.symmetric(vertical: 8, horizontal: 16),
      decoration: BoxDecoration(border: Border.all()),
      child: Text(post['title'] ?? 'No Title'),
    );
  }
}

// 假设的查询语句
const viewPostsQuery = gql('''
  query ViewPosts(\$categoryId: String!, \$take: Int!, \$offset: Int!) {
    viewPosts(categoryId: \$categoryId, take: \$take, offset: \$offset) {
      id
      title
      images
      # 其他字段
    }
  }
''');

关键修复点说明 #

1. 数据更新逻辑：updateQuery仅负责合并Query缓存数据，allPosts的更新由builder根据缓存数据同步，避免状态不一致。
2. 唯一Key：通过ValueKey(post['id'])为每个列表项设置唯一标识，Flutter会复用已存在的组件，不会重建整个列表。
3. 加载锁：_isLoading变量防止滚动时多次触发请求，避免数据重复和状态混乱。
4. 滚动触发时机：改为滚动到90%位置时触发加载，比滚动到底部更流畅，提升用户体验。

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