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 小时前
Flutter 框架跨平台鸿蒙开发 - 从零打造一款精美天气App
flutter·华为·harmonyos
独自破碎E2 小时前
包含min函数的栈
android·java·开发语言·leetcode
m0_748254662 小时前
Vue.js 模板语法基础
前端·vue.js·flutter
毕设源码-邱学长2 小时前
【开题答辩全过程】以 基于Android的健康码系统架构为例，包含答辩的问题和答案
android·系统架构
AiFlutter2 小时前
五、交互行为（06）：滑杆
flutter·低代码·低代码平台·aiflutter·aiflutter低代码
冬奇Lab2 小时前
稳定性性能系列之十五——系统稳定性监控体系建设:从指标到预警的完整方案
android·性能优化·debug
沈千秋.2 小时前
简单文件包含案例
android·ide·android studio·文件包含
冬奇Lab2 小时前
【Kotlin系列06】面向对象进阶：从接口到多态，设计灵活可扩展的代码
android·kotlin·编程语言
kirk_wang3 小时前
Flutter `share_plus` 库在鸿蒙 OHOS 平台的分享功能适配实践
flutter·移动开发·跨平台·arkts·鸿蒙
热门推荐
01GitHub 镜像站点02Linux下V2Ray安装配置指南03Labelme从安装到标注：零基础完整指南04Claude Code Skills 实用使用手册05AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南06网站改了域名，如何查找？07UV安装并设置国内源08安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）09百度网盘偷偷给电脑“降频”？102025年大语言模型技术全景报告