145 lines
5.2 KiB
Markdown
145 lines
5.2 KiB
Markdown
# 【Demo】ListView 列表（懒加载 / 刷新 / 触底加载 / 回顶）
|
||
|
||
> 源文件：`lib/pages/demo/list_demo.dart` ｜ 分类：基础布局
|
||
> 一句话：列表是 App 的骨架 —— 本页把列表的"基础、分隔、下拉刷新、上拉加载、回到顶部"一次讲透。
|
||
|
||
---
|
||
|
||
## 一、这个 Demo 解决什么问题
|
||
|
||
列表占了移动 App 80% 的页面形态。本 Demo 演示列表开发的全套基础：
|
||
1. `ListView(children)` vs `ListView.builder` 的区别（重点！）；
|
||
2. `ListView.separated` 自动分隔线；
|
||
3. `RefreshIndicator` 下拉刷新；
|
||
4. `ScrollController` 监听触底 → 上拉加载更多；
|
||
5. 滚动超过 200px 显示"回到顶部"悬浮按钮。
|
||
|
||
---
|
||
|
||
## 二、怎么运行 / 演示内容
|
||
|
||
```dart
|
||
runApp(const MaterialApp(home: ListDemoPage()));
|
||
```
|
||
|
||
- Demo1：一次性渲染的 ListView（公告 + ListTile + for 循环混装）；
|
||
- Demo2：可下拉刷新、可触底加载更多、带回到顶部按钮的完整列表。
|
||
|
||
---
|
||
|
||
## 三、核心知识点（新手向）
|
||
|
||
### 1. 最核心的区别（面试常问）
|
||
| 写法 | 行为 | 适用 |
|
||
|---|---|---|
|
||
| `ListView(children: [...])` | **一次性创建并渲染全部** item | 少量（<30）或异类组件混装 |
|
||
| `ListView.builder` | **懒加载**，只渲染可见项，滚到才创建 | 大量数据（聊天记录、长列表） |
|
||
|
||
```dart
|
||
ListView.builder(
|
||
itemCount: _items.length, // 数据总条数（决定滚动范围）
|
||
itemBuilder: (context, index) => ListTile(...), // 按下标生成每一行
|
||
)
|
||
```
|
||
|
||
### 2. 同族 API
|
||
- `ListView.builder`：纯列表，没有分隔线；
|
||
- `ListView.separated`：自动插分隔线，多一个 `separatorBuilder`（比在 item 里手动加 Divider 规范）。
|
||
|
||
### 3. 下拉刷新三件套
|
||
```dart
|
||
RefreshIndicator(
|
||
onRefresh: _onRefresh, // 必须返回 Future（转圈直到 Future 完成）
|
||
child: ListView.separated(
|
||
physics: const AlwaysScrollableScrollPhysics(), // 内容不满一屏也能下拉！
|
||
...
|
||
),
|
||
)
|
||
```
|
||
|
||
### 4. 触底加载的原理
|
||
`ScrollController.addListener` 监听滚动位置：
|
||
```dart
|
||
if (pos.pixels >= pos.maxScrollExtent - 200) {
|
||
_loadMore(); // 距底部 200px 时预加载
|
||
}
|
||
```
|
||
- `pos.pixels`：当前滚了多少；
|
||
- `pos.maxScrollExtent`：总共能滚多少；
|
||
- `hasClients`：控制器是否已挂载到滚动组件上（没挂载就访问会崩）。
|
||
|
||
### 5. Dart 3 记录类型（顺带学会）
|
||
```dart
|
||
List<(int, String)> _items = []; // (编号, 来源标签) 元组
|
||
final (num, tag) = _items[index]; // 解构
|
||
final newStart = _items.first.$1 + 100; // $1 取第一个字段
|
||
```
|
||
|
||
---
|
||
|
||
## 四、关键代码剖析
|
||
|
||
### 防重入的 _loadMore
|
||
```dart
|
||
Future<void> _loadMore() async {
|
||
if (_isLoadingMore || !_hasMore) return; // 防重入：滚动事件会高频触发
|
||
_isLoadingMore = true;
|
||
setState(() {}); // 先刷新，显示底部 loading
|
||
|
||
await Future.delayed(const Duration(milliseconds: 800)); // 模拟网络
|
||
if (!mounted) return; // 异步后必须判 mounted
|
||
|
||
setState(() {
|
||
_items = [..._items, ...List.generate(10, (i) => (start + i, '加载更多'))];
|
||
_page++;
|
||
_hasMore = _page < 5; // 模拟：到第 5 页后没有更多
|
||
});
|
||
_isLoadingMore = false;
|
||
}
|
||
```
|
||
|
||
### 回到顶部按钮（Stack + AnimatedOpacity + IgnorePointer）
|
||
```dart
|
||
Positioned(
|
||
right: 8,
|
||
bottom: 8,
|
||
child: AnimatedOpacity(
|
||
opacity: _showBackToTop ? 1 : 0,
|
||
duration: const Duration(milliseconds: 200),
|
||
child: IgnorePointer(
|
||
// opacity: 0 的按钮还能被点到！必须 IgnorePointer 禁用点击
|
||
ignoring: !_showBackToTop,
|
||
child: FloatingActionButton.small(
|
||
heroTag: null, // 避免多个 FAB 的 Hero 动画冲突
|
||
onPressed: _scrollToTop,
|
||
child: const Icon(Icons.arrow_upward, color: Colors.white),
|
||
),
|
||
),
|
||
),
|
||
)
|
||
```
|
||
`_scrollToTop` = `_scrollController.animateTo(0, duration: 300ms, curve: Curves.easeOut)`。
|
||
|
||
> 显隐判断用 `if (shouldShow != _showBackToTop)` 而不是直接 setState —— 滚动事件每像素都触发，
|
||
> 只有状态真的变了才重建，避免性能浪费。
|
||
|
||
---
|
||
|
||
## 五、踩坑记录
|
||
|
||
1. **ListView 放进 Column/Row 必须给固定高度（SizedBox）或 Expanded**，否则报
|
||
`Vertical viewport was given unbounded height` —— 列表是"无限高"的，放在"无限高"的 Column 里矛盾。
|
||
2. **RefreshIndicator 必须配 `AlwaysScrollableScrollPhysics()`**，否则内容不满一屏时拉不动。
|
||
3. **`ScrollController` 必须在 dispose 释放**（与 TextEditingController 同理，防内存泄漏）。
|
||
4. **异步后 setState 前必须 `if (!mounted) return`**——await 期间用户可能已切走页面。
|
||
5. 触底判断用 `maxScrollExtent - 200` 提前量，不然在底部"刚好"才加载会有白屏等待感。
|
||
|
||
---
|
||
|
||
## 六、扩展思考
|
||
|
||
- **性能红线**：长列表用 builder，不要用 children + for；1000 条数据一次性渲染会掉帧；
|
||
- 数据源接 Riverpod 后，`_items` 换成 `ref.watch(xxxProvider)`，刷新逻辑交给 provider（见 exam 系列）；
|
||
- 分页的通用模式：`page` 页码 + `hasMore` 标记 + `_isLoadingMore` 防重入，三件套缺一不可；
|
||
- 想整页只滚一次（AppBar 折叠 + 列表混排）→ 升级到 [sliver_demo.md](sliver_demo.md) 的 CustomScrollView。
|