Flutter聊天列表展示插件lorien_chat_list的使用

lorien_chat_list 是一个用于构建类似Messenger或WhatsApp聊天页面的包。与其他包的主要区别在于滚动部分——当有新消息时会自动滚动到底部，或者如果用户已经向上滚动了一定距离，则保持当前滚动位置（您可以设置该阈值）。

开始使用

在 pubspec.yaml 文件中添加依赖：

dependencies:
  ...
  lorien_chat_list: ^0.0.1

基本用法

导入

import 'package:lorien_chat_list/lorien_chat_list.dart';

控制器

final ChatListController<int> _controller = ChatListController(
  initialItems: List.generate(10, (index) => index),
);

添加项目到列表底部：

_controller.addToBottom(100);

添加一系列项目到列表底部：

_controller.addRangeToBottom([100, 200]);

添加项目到列表顶部：

_controller.addToTop(-100);

添加一系列项目到列表顶部：

_controller.addRangeToTop([-100, -200]);

清除所有项目并重置控制器到初始状态：

_controller.clearAll();

小部件

ChatList(
  controller: _controller,
  itemBuilder: (item, properties) => Text(
    '${item.toString()} - ${properties.toString()}',
  ),
),

自定义（可选）

ChatList

• loadingMoreWidget - 在加载更多旧消息时（onLoadMoreCallback）可见的顶部小部件
• onLoadMoreCallback - 加载更多旧消息的函数。当达到列表顶部边缘时触发。应返回布尔值，true 表示还有更多的旧消息可以加载，否则 false 表示已加载完毕。
• scrollController - 滚动控制器
• scrollPhysics - 滚动物理特性
• padding - 列表填充
• spacing - 项目之间的垂直间距
• useJumpTo - 是否使用 jumpTo 而不是 animateTo 进行自动滚动
• animateToDuration - animateTo 的持续时间，默认为 300 毫秒
• fadeInDuration - 淡入持续时间，默认为 300 毫秒
• animateToCurve - animateTo 的曲线，默认为 Curves.easeInOut
• fadeInCurve - 淡入曲线，默认为 Curves.easeInOut
• bottomEdgeThreshold - 自动滚动到底部项目的阈值，默认为 0

示例代码

以下是一个完整的示例代码，展示了如何使用 lorien_chat_list 包来创建一个聊天列表页面：

import 'dart:math';

import 'package:flutter/material.dart';
import 'package:lorien_chat_list/lorien_chat_list.dart';

void main() {
  runApp(const LorienChatListExample());
}

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

  [@override](/user/override)
  State<LorienChatListExample> createState() => _LorienChatListExampleState();
}

class _LorienChatListExampleState extends State<LorienChatListExample> {
  late final ChatListController<_MessageModel> _chatController = ChatListController(
    initialItems: List.generate(10, (index) => -index)
        .map(
          (number) => _MessageModel(
            number: number,
            isMyMessage: _random.nextBool(),
            text: _tolkienQuotes[number % _tolkienQuotes.length],
          ),
        )
        .toList(),
  );

  int _nextTopNumber = -10;
  int _nextBottomNumber = 1;

  final _random = Random();
  final _scrollController = ScrollController();

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        backgroundColor: Colors.grey[200],
        appBar: AppBar(
          backgroundColor: Colors.black,
          title: const Text(
            'LORIEN.DEV Chat list',
            style: TextStyle(
              color: Colors.white,
            ),
          ),
          actions: [
            IconButton(
              tooltip: 'Add item to top',
              icon: const Icon(
                Icons.add_comment_outlined,
                color: Colors.white,
              ),
              onPressed: () => _chatController.addToTop(
                _MessageModel(
                  number: _nextTopNumber--,
                  isMyMessage: _random.nextBool(),
                  text: _tolkienQuotes[_nextTopNumber % _tolkienQuotes.length],
                ),
              ),
            ),
            IconButton(
              tooltip: 'Add item to bottom',
              icon: const Icon(
                Icons.add_comment,
                color: Colors.white,
              ),
              onPressed: () => _chatController.addToBottom(
                _MessageModel(
                  number: _nextBottomNumber++,
                  isMyMessage: _random.nextBool(),
                  text: _tolkienQuotes[_nextBottomNumber % _tolkienQuotes.length],
                ),
              ),
            ),
            IconButton(
              tooltip: 'Clear list',
              icon: const Icon(
                Icons.refresh,
                color: Colors.white,
              ),
              onPressed: () {
                _chatController.clearAll();
                _nextTopNumber = 0;
                _nextBottomNumber = 1;
              },
            ),
          ],
        ),
        body: ChatList(
          controller: _chatController,
          itemBuilder: (item, properties) => _MessageCard(
            type: item.isMyMessage
                ? _MessageType.outgoing
                : _MessageType.incoming,
            text: '${item.number}. ${item.text}',
          ),
          loadingMoreWidget: const Padding(
            padding: EdgeInsets.only(top: 16.0),
            child: Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                CircularProgressIndicator(),
              ],
            ),
          ),
          onLoadMoreCallback: _loadMoreOldMessages,
          scrollController: _scrollController,
          scrollPhysics: const ClampingScrollPhysics(),
          useJumpTo: false,
          animateToDuration: const Duration(milliseconds: 300),
          fadeInDuration: const Duration(milliseconds: 300),
          animateToCurve: Curves.easeInOut,
          fadeInCurve: Curves.easeInOut,
          bottomEdgeThreshold: 20.0,
          padding: const EdgeInsets.all(16.0),
          spacing: 4.0,
        ),
      ),
    );
  }

  /// 模拟加载更多旧消息。
  /// 返回 *true* 如果还有更多的旧消息可以加载
  /// 否则返回 *false* 如果已加载完毕。
  Future<bool> _loadMoreOldMessages() async {
    /// 模拟延迟3秒
    await Future.delayed(const Duration(seconds: 3));

    /// 获取10个更多的旧消息
    final newOldItems = List.generate(10, (index) => _nextTopNumber--)
        .map(
          (number) => _MessageModel(
            number: number,
            isMyMessage: _random.nextBool(),
            text: _tolkienQuotes[number % _tolkienQuotes.length],
          ),
        )
        .toList();

    /// 将新的旧消息添加到聊天列表的顶部
    _chatController.addRangeToTop(newOldItems);

    /// 返回是否有更多的旧消息可以加载
    return _nextTopNumber > -30;
  }
}

class _MessageCard extends StatelessWidget {
  const _MessageCard({
    required _MessageType type,
    required String text,
  })  : _type = type,
        _text = text;

  final _MessageType _type;
  final String _text;

  [@override](/user/override)
  Widget build(BuildContext context) {
    final isIncoming = _type == _MessageType.incoming;
    return Row(
      mainAxisAlignment:
          isIncoming ? MainAxisAlignment.start : MainAxisAlignment.end,
      children: [
        Flexible(
          child: ConstrainedBox(
            constraints: BoxConstraints(
              maxWidth: MediaQuery.of(context).size.width * 0.7,
            ),
            child: Card(
              color: isIncoming ? Colors.white : Colors.black,
              child: Padding(
                padding: const EdgeInsets.all(8.0),
                child: Text(
                  _text,
                  style: TextStyle(
                    color: isIncoming ? Colors.black : Colors.white,
                  ),
                  textAlign: isIncoming ? TextAlign.left : TextAlign.right,
                ),
              ),
            ),
          ),
        ),
      ],
    );
  }
}

class _MessageModel {
  const _MessageModel({
    required this.number,
    required this.isMyMessage,
    required this.text,
  });

  final int number;
  final bool isMyMessage;
  final String text;
}

enum _MessageType {
  incoming,
  outgoing,
}

const _tolkienQuotes = [
  "\"All we have to decide is what to do with the time that is given us.\" "
      "(The Fellowship of the Ring - J.R.R. Tolkien)",
  "\"Not all those who wander are lost.\" (The Fellowship of the Ring - J.R.R. Tolkien)",
  "\"Courage is found in unlikely places.\" (The Return of the King - J.R.R. Tolkien)",
  "\"Even the smallest person can change the course of the future.\" (The Fellowship of the Ring - J.R.R. Tolkien)",
  "\"It's a dangerous business, Frodo, going out your door. You step onto the road, "
      "and if you don't keep your feet, "
      "there's no knowing where you might be swept off to.\" (The Fellowship of the Ring - J.R.R. Tolkien)",
  "\"I will not say: do not weep; for not all tears are an evil.\" (The Return of the King - J.R.R. Tolkien)",
  "\"Far over the misty mountains cold, To dungeons deep and caverns old, We must away, ere break of day, To seek "
      "the pale enchanted gold.\" (The Hobbit - J.R.R. Tolkien)",
  "\"The world is indeed full of peril, and in it there are many dark places; but still there is much that is fair, "
      "and though in all lands love is now mingled with grief, it grows perhaps the greater.\" "
      "(The Fellowship of the Ring - J.R.R. Tolkien)",
  "\"War must be, while we defend our lives against a destroyer who would devour all; but I do not love the bright"
      " sword for its sharpness, nor the arrow for its swiftness, nor the warrior for his glory. I love only that"
      " which they defend.\" (The Two Towers - J.R.R. Tolkien)",
  "\"There are older and fouler things than Orcs in the deep places of the world.\" "
      "(The Fellowship of the Ring - J.R.R. Tolkien)"
];