Flutter ListView 列表组件完全指南

—Qeyser2026-01-16 10:50

什么是 ListView？

ListView 是 Flutter 中用于显示可滚动列表的组件，类似于 HTML 中的滚动容器。

用途：

  • 显示长列表
  • 聊天消息列表
  • 商品列表
  • 新闻列表
  • 任何需要滚动的内容

ListView 的类型

1. ListView - 基础列表

dart 复制代码 
ListView(
  children: [
    ListTile(title: Text('项目 1')),
    ListTile(title: Text('项目 2')),
    ListTile(title: Text('项目 3')),
  ],
)

2. ListView.builder - 动态列表（推荐）

dart 复制代码 
ListView.builder(
  itemCount: 100,
  itemBuilder: (context, index) {
    return ListTile(
      title: Text('项目 $index'),
    );
  },
)

3. ListView.separated - 带分隔符的列表

dart 复制代码 
ListView.separated(
  itemCount: 20,
  itemBuilder: (context, index) {
    return ListTile(
      title: Text('项目 $index'),
    );
  },
  separatorBuilder: (context, index) {
    return Divider();  // 分隔线
  },
)

4. ListView.custom - 自定义列表

dart 复制代码 
ListView.custom(
  childrenDelegate: SliverChildBuilderDelegate(
    (context, index) {
      return ListTile(title: Text('项目 $index'));
    },
    childCount: 20,
  ),
)

常用属性

1. 滚动方向 scrollDirection

dart 复制代码 
// 垂直滚动（默认）
ListView(
  scrollDirection: Axis.vertical,
  children: [...],
)

// 水平滚动
ListView(
  scrollDirection: Axis.horizontal,
  children: [...],
)

2. 反向滚动 reverse

dart 复制代码 
ListView(
  reverse: true,  // 从底部开始
  children: [...],
)

3. 内边距 padding

dart 复制代码 
ListView(
  padding: EdgeInsets.all(10),
  children: [...],
)

4. 物理效果 physics

dart 复制代码 
// 总是可滚动
ListView(
  physics: AlwaysScrollableScrollPhysics(),
  children: [...],
)

// 永不滚动
ListView(
  physics: NeverScrollableScrollPhysics(),
  children: [...],
)

// 弹性滚动（iOS 风格）
ListView(
  physics: BouncingScrollPhysics(),
  children: [...],
)

// 夹紧滚动（Android 风格）
ListView(
  physics: ClampingScrollPhysics(),
  children: [...],
)

ListTile 列表项

基础用法

dart 复制代码 
ListTile(
  leading: Icon(Icons.person),      // 左侧图标
  title: Text('标题'),               // 标题
  subtitle: Text('副标题'),          // 副标题
  trailing: Icon(Icons.chevron_right),  // 右侧图标
  onTap: () {
    print('点击了列表项');
  },
)

完整属性

dart 复制代码 
ListTile(
  leading: CircleAvatar(
    child: Icon(Icons.person),
  ),
  title: Text('张三'),
  subtitle: Text('Flutter 开发工程师'),
  trailing: Icon(Icons.chevron_right),
  isThreeLine: false,  // 是否三行
  dense: false,        // 是否紧凑
  enabled: true,       // 是否启用
  selected: false,     // 是否选中
  onTap: () {},
  onLongPress: () {},
)

实战案例

案例1：简单列表

dart 复制代码 
ListView.builder(
  itemCount: 20,
  itemBuilder: (context, index) {
    return ListTile(
      leading: CircleAvatar(
        child: Text('${index + 1}'),
      ),
      title: Text('列表项 ${index + 1}'),
      subtitle: Text('这是副标题'),
      trailing: Icon(Icons.chevron_right),
      onTap: () {
        print('点击了第 ${index + 1} 项');
      },
    );
  },
)

案例2：联系人列表

dart 复制代码 
class Contact {
  final String name;
  final String phone;
  final String avatar;

  Contact({required this.name, required this.phone, required this.avatar});
}

class ContactList extends StatelessWidget {
  final List<Contact> contacts = [
    Contact(name: '张三', phone: '138****0001', avatar: 'https://example.com/1.jpg'),
    Contact(name: '李四', phone: '138****0002', avatar: 'https://example.com/2.jpg'),
    Contact(name: '王五', phone: '138****0003', avatar: 'https://example.com/3.jpg'),
  ];

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: contacts.length,
      itemBuilder: (context, index) {
        final contact = contacts[index];
        return ListTile(
          leading: CircleAvatar(
            backgroundImage: NetworkImage(contact.avatar),
          ),
          title: Text(contact.name),
          subtitle: Text(contact.phone),
          trailing: IconButton(
            icon: Icon(Icons.phone),
            onPressed: () {
              print('拨打 ${contact.phone}');
            },
          ),
          onTap: () {
            print('查看 ${contact.name} 的详情');
          },
        );
      },
    );
  }
}

案例3：聊天列表

dart 复制代码 
class ChatItem {
  final String name;
  final String message;
  final String time;
  final int unread;

  ChatItem({
    required this.name,
    required this.message,
    required this.time,
    this.unread = 0,
  });
}

class ChatList extends StatelessWidget {
  final List<ChatItem> chats = [
    ChatItem(name: '张三', message: '你好啊', time: '10:30', unread: 2),
    ChatItem(name: '李四', message: '在吗？', time: '09:15', unread: 0),
    ChatItem(name: '王五', message: '晚上一起吃饭', time: '昨天', unread: 1),
  ];

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: chats.length,
      itemBuilder: (context, index) {
        final chat = chats[index];
        return ListTile(
          leading: CircleAvatar(
            child: Text(chat.name[0]),
          ),
          title: Row(
            children: [
              Expanded(child: Text(chat.name)),
              Text(
                chat.time,
                style: TextStyle(fontSize: 12, color: Colors.grey),
              ),
            ],
          ),
          subtitle: Row(
            children: [
              Expanded(
                child: Text(
                  chat.message,
                  maxLines: 1,
                  overflow: TextOverflow.ellipsis,
                ),
              ),
              if (chat.unread > 0)
                Container(
                  padding: EdgeInsets.all(4),
                  decoration: BoxDecoration(
                    color: Colors.red,
                    shape: BoxShape.circle,
                  ),
                  constraints: BoxConstraints(minWidth: 20, minHeight: 20),
                  child: Center(
                    child: Text(
                      '${chat.unread}',
                      style: TextStyle(color: Colors.white, fontSize: 12),
                    ),
                  ),
                ),
            ],
          ),
          onTap: () {
            print('打开与 ${chat.name} 的聊天');
          },
        );
      },
    );
  }
}

案例4：商品列表

dart 复制代码 
class Product {
  final String name;
  final String image;
  final double price;
  final String description;

  Product({
    required this.name,
    required this.image,
    required this.price,
    required this.description,
  });
}

class ProductList extends StatelessWidget {
  final List<Product> products = [
    Product(
      name: 'iPhone 15 Pro',
      image: 'https://example.com/iphone.jpg',
      price: 7999,
      description: '最新款 iPhone',
    ),
    // 更多商品...
  ];

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: products.length,
      itemBuilder: (context, index) {
        final product = products[index];
        return Card(
          margin: EdgeInsets.all(10),
          child: Padding(
            padding: EdgeInsets.all(10),
            child: Row(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                ClipRRect(
                  borderRadius: BorderRadius.circular(8),
                  child: Image.network(
                    product.image,
                    width: 100,
                    height: 100,
                    fit: BoxFit.cover,
                  ),
                ),
                SizedBox(width: 10),
                Expanded(
                  child: Column(
                    crossAxisAlignment: CrossAxisAlignment.start,
                    children: [
                      Text(
                        product.name,
                        style: TextStyle(
                          fontSize: 16,
                          fontWeight: FontWeight.bold,
                        ),
                      ),
                      SizedBox(height: 5),
                      Text(
                        product.description,
                        style: TextStyle(color: Colors.grey),
                        maxLines: 2,
                        overflow: TextOverflow.ellipsis,
                      ),
                      SizedBox(height: 10),
                      Row(
                        children: [
                          Text(
                            '¥${product.price}',
                            style: TextStyle(
                              fontSize: 20,
                              fontWeight: FontWeight.bold,
                              color: Colors.red,
                            ),
                          ),
                          Spacer(),
                          ElevatedButton(
                            onPressed: () {},
                            child: Text('购买'),
                          ),
                        ],
                      ),
                    ],
                  ),
                ),
              ],
            ),
          ),
        );
      },
    );
  }
}

案例5：水平滚动列表

dart 复制代码 
Container(
  height: 200,
  child: ListView.builder(
    scrollDirection: Axis.horizontal,
    itemCount: 10,
    itemBuilder: (context, index) {
      return Container(
        width: 150,
        margin: EdgeInsets.all(10),
        decoration: BoxDecoration(
          color: Colors.blue,
          borderRadius: BorderRadius.circular(10),
        ),
        child: Center(
          child: Text(
            '卡片 $index',
            style: TextStyle(color: Colors.white, fontSize: 18),
          ),
        ),
      );
    },
  ),
)

案例6：分组列表

dart 复制代码 
class GroupedList extends StatelessWidget {
  final Map<String, List<String>> groups = {
    'A': ['Alice', 'Amy', 'Andrew'],
    'B': ['Bob', 'Betty', 'Brian'],
    'C': ['Charlie', 'Cathy'],
  };

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: _getTotalCount(),
      itemBuilder: (context, index) {
        final item = _getItem(index);
        if (item['type'] == 'header') {
          return Container(
            padding: EdgeInsets.all(10),
            color: Colors.grey[300],
            child: Text(
              item['data'],
              style: TextStyle(
                fontWeight: FontWeight.bold,
                fontSize: 16,
              ),
            ),
          );
        } else {
          return ListTile(
            title: Text(item['data']),
          );
        }
      },
    );
  }

  int _getTotalCount() {
    int count = 0;
    groups.forEach((key, value) {
      count += 1 + value.length;  // 1 个标题 + n 个项目
    });
    return count;
  }

  Map<String, dynamic> _getItem(int index) {
    int currentIndex = 0;
    for (var entry in groups.entries) {
      if (currentIndex == index) {
        return {'type': 'header', 'data': entry.key};
      }
      currentIndex++;
      
      for (var item in entry.value) {
        if (currentIndex == index) {
          return {'type': 'item', 'data': item};
        }
        currentIndex++;
      }
    }
    return {'type': 'item', 'data': ''};
  }
}

案例7：下拉刷新

dart 复制代码 
class RefreshableList extends StatefulWidget {
  @override
  _RefreshableListState createState() => _RefreshableListState();
}

class _RefreshableListState extends State<RefreshableList> {
  List<String> items = List.generate(20, (index) => '项目 $index');

  Future<void> _onRefresh() async {
    await Future.delayed(Duration(seconds: 2));
    setState(() {
      items = List.generate(20, (index) => '新项目 $index');
    });
  }

  @override
  Widget build(BuildContext context) {
    return RefreshIndicator(
      onRefresh: _onRefresh,
      child: ListView.builder(
        itemCount: items.length,
        itemBuilder: (context, index) {
          return ListTile(
            title: Text(items[index]),
          );
        },
      ),
    );
  }
}

案例8：滑动删除

dart 复制代码 
class DismissibleList extends StatefulWidget {
  @override
  _DismissibleListState createState() => _DismissibleListState();
}

class _DismissibleListState extends State<DismissibleList> {
  List<String> items = List.generate(20, (index) => '项目 $index');

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: items.length,
      itemBuilder: (context, index) {
        final item = items[index];
        return Dismissible(
          key: Key(item),
          background: Container(
            color: Colors.red,
            alignment: Alignment.centerRight,
            padding: EdgeInsets.only(right: 20),
            child: Icon(Icons.delete, color: Colors.white),
          ),
          direction: DismissDirection.endToStart,
          onDismissed: (direction) {
            setState(() {
              items.removeAt(index);
            });
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(content: Text('$item 已删除')),
            );
          },
          child: ListTile(
            title: Text(item),
          ),
        );
      },
    );
  }
}

案例9：加载更多

dart 复制代码 
class LoadMoreList extends StatefulWidget {
  @override
  _LoadMoreListState createState() => _LoadMoreListState();
}

class _LoadMoreListState extends State<LoadMoreList> {
  List<String> items = List.generate(20, (index) => '项目 $index');
  bool isLoading = false;
  ScrollController _scrollController = ScrollController();

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

  void _onScroll() {
    if (_scrollController.position.pixels ==
        _scrollController.position.maxScrollExtent) {
      _loadMore();
    }
  }

  Future<void> _loadMore() async {
    if (isLoading) return;
    
    setState(() {
      isLoading = true;
    });

    await Future.delayed(Duration(seconds: 2));

    setState(() {
      int currentLength = items.length;
      items.addAll(
        List.generate(10, (index) => '项目 ${currentLength + index}'),
      );
      isLoading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      controller: _scrollController,
      itemCount: items.length + 1,
      itemBuilder: (context, index) {
        if (index == items.length) {
          return isLoading
              ? Center(
                  child: Padding(
                    padding: EdgeInsets.all(20),
                    child: CircularProgressIndicator(),
                  ),
                )
              : SizedBox.shrink();
        }
        return ListTile(
          title: Text(items[index]),
        );
      },
    );
  }

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

案例10：搜索列表

dart 复制代码 
class SearchableList extends StatefulWidget {
  @override
  _SearchableListState createState() => _SearchableListState();
}

class _SearchableListState extends State<SearchableList> {
  List<String> allItems = List.generate(100, (index) => '项目 $index');
  List<String> filteredItems = [];
  TextEditingController _searchController = TextEditingController();

  @override
  void initState() {
    super.initState();
    filteredItems = allItems;
    _searchController.addListener(_onSearchChanged);
  }

  void _onSearchChanged() {
    setState(() {
      filteredItems = allItems
          .where((item) =>
              item.toLowerCase().contains(_searchController.text.toLowerCase()))
          .toList();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Padding(
          padding: EdgeInsets.all(10),
          child: TextField(
            controller: _searchController,
            decoration: InputDecoration(
              hintText: '搜索...',
              prefixIcon: Icon(Icons.search),
              border: OutlineInputBorder(
                borderRadius: BorderRadius.circular(10),
              ),
            ),
          ),
        ),
        Expanded(
          child: ListView.builder(
            itemCount: filteredItems.length,
            itemBuilder: (context, index) {
              return ListTile(
                title: Text(filteredItems[index]),
              );
            },
          ),
        ),
      ],
    );
  }

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

完整示例

dart 复制代码 
import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: ListViewDemo(),
    );
  }
}

class ListViewDemo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('ListView 示例')),
      body: ListView.separated(
        itemCount: 20,
        itemBuilder: (context, index) {
          return ListTile(
            leading: CircleAvatar(
              child: Text('${index + 1}'),
            ),
            title: Text('列表项 ${index + 1}'),
            subtitle: Text('这是副标题'),
            trailing: Icon(Icons.chevron_right),
            onTap: () {
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('点击了第 ${index + 1} 项')),
              );
            },
          );
        },
        separatorBuilder: (context, index) {
          return Divider(height: 1);
        },
      ),
    );
  }
}

常见问题

1. ListView 在 Column 中不显示？

dart 复制代码 
// ❌ 错误
Column(
  children: [
    ListView(...),  // 会报错
  ],
)

// ✅ 解决1：使用 Expanded
Column(
  children: [
    Expanded(
      child: ListView(...),
    ),
  ],
)

// ✅ 解决2：使用 shrinkWrap
Column(
  children: [
    ListView(
      shrinkWrap: true,
      physics: NeverScrollableScrollPhysics(),
      children: [...],
    ),
  ],
)

2. 如何监听滚动？

dart 复制代码 
ScrollController _controller = ScrollController();

@override
void initState() {
  super.initState();
  _controller.addListener(() {
    print('滚动位置: ${_controller.position.pixels}');
  });
}

ListView(
  controller: _controller,
  children: [...],
)

3. 如何滚动到指定位置？

dart 复制代码 
_controller.animateTo(
  100.0,
  duration: Duration(milliseconds: 500),
  curve: Curves.easeInOut,
);

属性速查表

属性 说明
children 子组件列表
scrollDirection 滚动方向
reverse 是否反向
controller 滚动控制器
physics 滚动物理效果
padding 内边距
shrinkWrap 是否根据子组件调整大小

ListView.builder 参数

参数 说明
itemCount 项目数量
itemBuilder 项目构建器

ListTile 属性

属性 说明
leading 左侧组件
title 标题
subtitle 副标题
trailing 右侧组件
onTap 点击回调
onLongPress 长按回调

总结

ListView 的核心要点：

  1. ListView.builder 适合大量数据
  2. ListView.separated 自动添加分隔符
  3. 使用 ScrollController 控制滚动
  4. RefreshIndicator 实现下拉刷新
  5. Dismissible 实现滑动删除

记住：

  • 大量数据用 ListView.builder
  • 在 Column 中使用需要 Expanded 或 shrinkWrap
  • 使用 ListTile 快速构建列表项
  • 善用 ScrollController 监听和控制滚动

ListView 是最常用的滚动组件，掌握它能构建各种列表界面！

相关推荐
花花鱼2 分钟前
android studio 图标的使用及处理
android·ide·android studio
JJay.12 分钟前
什么时候该用 BLE，什么时候该用 SPP？很多 Android 项目一开始就做错了
android
山峰哥24 分钟前
SQL性能飙升秘籍：从索引策略到查询优化全解析
android
MonkeyKing715524 分钟前
Flutter列表性能极致优化：从卡顿到丝滑
flutter
黄林晴41 分钟前
稳定性全面升级！Compose Multiplatform 1.11 RC 正式推送
android
恋猫de小郭41 分钟前
实用性 Max ，新 Flutter & Dart Agent Skills 深度解读
android·前端·flutter
重生之小比特1 小时前
【MySQL 数据库】表的约束
android·数据库·mysql
Kapaseker1 小时前
Android 中的 MVVM 是如何构建起来的
android·kotlin
_李小白1 小时前
【android opencv学习笔记】Day 9: 颜色检测算法
android·opencv·学习
三少爷的鞋2 小时前
Repository 一定需要 DataSource 吗？一篇讲透的架构思考
android
热门推荐
01GitHub 镜像站点02要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法03Codex 接入 DeepSeek API 完整配置文档04零基础教你claude code 接入 deepseek V405Linux 核弹级高危漏洞 CVE-2026-31431 完整修复指南06CVE-2026-31431 (Copy Fail) 漏洞复现与验证记录07CC-Switch & Claude 基于 Linux 服务器安装使用指南082026 年 AI 辅助编程工具全景对比：Copilot、Cursor、Claude Code 与 Codex 深度解析09【AI】2026 年具身智能模型和世界模型总结10裂开！ChatGPT 居然开始要手机号验证，附详细解决方法