# ChatList 气泡聊天列表

`AntdUI.Chat.ChatList` 用于显示聊天气泡消息，支持左右消息、头像/昵称、时间、加载状态、图片消息、滚动到底部等能力。文本消息使用 `TextChatItem`，图片消息使用 `ImageChatItem`。

> 当前 DLL 已确认存在：`AntdUI.Chat.ChatList`、`TextChatItem`、`ImageChatItem`、`IChatItem`、`ChatItemCollection`。

## 最小示例

```aardio
import win.ui;
import dotNet.AntdUI;
import System.Drawing;

var winform = win.form(text="ChatList 示例";right=640;bottom=460);
winform.add(host={cls="custom";left=0;top=0;right=640;bottom=460;z=1});

var chatList = AntdUI.Chat.ChatList(winform.host);
chatList.Dock = System.Windows.Forms.DockStyle.Fill;
chatList.ItemGap = 10;
chatList.BubbleGap = 8;
chatList.ShowTimeFocused = true;

var left = AntdUI.Chat.TextChatItem("你好，我是张三");
left.SetName("张三").SetTime("09:30");
chatList.Items.Add(left);

var right = AntdUI.Chat.TextChatItem("你好，我是当前用户");
right.SetName("我").SetMe(true).SetTime("09:31");
chatList.AddToBottom(right,true);

var loading = AntdUI.Chat.TextChatItem("正在生成回复...");
loading.SetName("机器人").SetLoading(true);
chatList.AddToBottom(loading,true);

winform.show();
win.loopMessage();
```

## 文本消息 TextChatItem

常用构造与链式方法：

```aardio
var msg = AntdUI.Chat.TextChatItem("消息文本");
msg.SetName("张三");
msg.SetTime("刚刚");
msg.SetMe(true);      // 右侧/当前用户消息
msg.SetLoading(false);
msg.SetID("m1001");
msg.SetTag({type="text"});
```

常用属性：

- `Text`：消息文本。
- `Name`：发送者名称。
- `Time`：时间文本。
- `Me`：是否当前用户消息，通常显示在右侧。
- `Loading`：加载动画状态，适合流式回复占位。
- `Icon`：头像图片。
- `ID`、`Tag`：业务标识与用户数据。
- `SelectionStart`、`SelectionLength`：文本选择相关。

## 图片消息 ImageChatItem

```aardio
var imgItem = AntdUI.Chat.ImageChatItem(160,100);
imgItem.SetName("图片消息");
imgItem.SetMe(true);
imgItem.SetLoading(false);
chatList.Items.Add(imgItem);
```

常用属性/方法：

- `Image`：消息图片。
- `Width`、`Height`：图片显示尺寸。
- `IsGIF`：是否 GIF。
- `SetImage(image)`、`SetSize(w,h)`、`SetSizeRatio(ratio)`。
- `SetMe(true)`、`SetName(name)`、`SetIcon(img)`。

## ChatList 常用属性与方法

- `Items`：消息集合，添加 `TextChatItem`、`ImageChatItem` 等 `IChatItem` 派生对象。
- `AddToBottom(item, force=false)`：添加消息并根据滚动位置决定是否到底部；`force=true` 强制到底部。
- `ToBottom()`：滚动到底部。
- `IsBottom`：当前是否已经滚动到底部。
- `ScrollLine(i, force=false)`：滚动指定行。
- `FocusedChatItem`：当前聚焦消息项。
- `EnabledClickImage`：允许点击图片。
- `IconLess`：隐藏头像区域。
- `ItemGap`：消息项间距。
- `BubbleGap`：气泡与头像/边缘的间距。
- `EmojiFont`、`EmojiRatio`：emoji 显示相关。
- `BackBubble`、`BackBubbleMe`、`ForeBubble`、`ForeBubbleMe`：左右消息气泡颜色。
- `SelectionColor`、`SelectionColorMe`：文本选区颜色。

## 常用事件

- `ItemClick(sender,e)`：点击消息项，常用 `e.Item`。
- `ItemIconClick(sender,e)`：点击头像。
- `ItemImageClick(sender,e)`：点击图片消息，图片事件参数含 `ClickImage`、`ImageUpdated`。

```aardio
chatList.ItemClick = function(sender,e){
    var it = e.Item;
    if(it) winform.text = "点击消息：" + (it.Text : "");
}

chatList.ItemImageClick = function(sender,e){
    // e.ClickImage 为被点击图片；可在这里调用 Preview 或自定义图片查看器
}
```

## 模拟流式回复

```aardio
var reply = AntdUI.Chat.TextChatItem("");
reply.SetName("机器人").SetLoading(true);
chatList.AddToBottom(reply,true);

// 实际项目可在异步回调中逐步更新 Text
reply.Loading = false;
reply.Text = "这是最终回复内容";
if(chatList.IsBottom) chatList.ToBottom();
```

## 注意事项

- `TextChatItem.SetMe(true)` 常用于当前用户消息，默认消息显示在对侧。
- `AddToBottom(item,true)` 比直接 `Items.Add(item)` 更适合聊天流追加消息。
- 图片点击、头像点击等事件只在对应内容区域命中时触发。
- 如需实现完整聊天界面，可结合左侧 `MsgList` 与底部 `Input`/`Button` 自行组织布局。