MessageChain - 消息链

消息链是 EasyBot 中用于构建复杂消息的核心类，支持文本、图片、@用户、表情等多种消息片段的组合。

类定义

declare class MessageChain implements IList<Segment> {
    // 基础属性
    get Count(): number;         // 片段数量
    get IsReadOnly(): boolean;   // 是否只读
    
    // 索引访问
    get(index: number): Segment;
    set(index: number, value: Segment): void;
    
    // 集合操作
    Add(item: Segment): void;
    Clear(): void;
    Contains(item: Segment): boolean;
    Remove(item: Segment): boolean;
    RemoveAt(index: number): void;
    
    // 流式构建方法
    Text(...text: string[]): MessageChain;
    NextLine(): MessageChain;
    At(id: string): MessageChain;
    Image(uri: string): MessageChain;
    Face(id: number): MessageChain;
    Reply(messageId: string): MessageChain;
    Node(id: string, name: string, userId: string, chain: MessageChain): MessageChain;  // v0.4.0 新增
    
    // 输出方法
    AsString(): string;
}

属性

Count

• 类型: number
• 描述: 获取消息链中片段的数量
• 只读: 是

IsReadOnly

• 类型: boolean
• 描述: 指示消息链是否为只读（始终返回false）
• 只读: 是

索引访问方法

get(index)

获取指定索引处的消息片段。

语法: get(index: number): Segment

参数:

• index - 目标索引位置

返回值: 对应位置的消息片段

set(index, value)

设置指定索引处的消息片段。

语法: set(index: number, value: Segment): void

参数:

• index - 目标索引位置
• value - 要设置的消息片段

集合操作方法

Add(item)

向消息链末尾添加片段。

语法: Add(item: Segment): void

参数:

• item - 要添加的消息片段

Clear()

清空消息链中的所有片段。

语法: Clear(): void

Contains(item)

检查消息链是否包含指定片段。

语法: Contains(item: Segment): boolean

参数:

• item - 要查找的消息片段

返回值: 如果包含则返回true，否则返回false

Remove(item)

移除指定的消息片段。

语法: Remove(item: Segment): boolean

参数:

• item - 要移除的消息片段

返回值: 成功移除返回true，否则返回false

RemoveAt(index)

移除指定索引处的消息片段。

语法: RemoveAt(index: number): void

参数:

• index - 要移除的片段索引

流式构建方法

Text(...text)

添加文本片段（支持多个参数）。

语法: Text(...text: string[]): MessageChain

参数:

• text - 要添加的文本内容

返回值: 当前消息链实例（支持链式调用）

示例:

const chain = new MessageChain().Text("Hello", " ", "World");

NextLine()

添加换行符片段。

语法: NextLine(): MessageChain

返回值: 当前消息链实例（支持链式调用）

At(id)

添加@用户片段。

语法: At(id: string): MessageChain

参数:

• id - 目标用户ID

返回值: 当前消息链实例（支持链式调用）

Image(uri)

添加图片片段。

语法: Image(uri: string): MessageChain

参数:

• uri - 图片资源URI

返回值: 当前消息链实例（支持链式调用）

Face(id)

添加表情片段。

语法: Face(id: number): MessageChain

参数:

• id - 表情ID

返回值: 当前消息链实例（支持链式调用）

Reply(messageId)

添加回复引用片段。

语法: Reply(messageId: string): MessageChain

参数:

• messageId - 被回复的消息ID

返回值: 当前消息链实例（支持链式调用）

Node(id, name, userId, chain)

v0.4.0 新增

添加合并转发节点片段，用于构建合并转发消息。

语法: Node(id: string, name: string, userId: string, chain: MessageChain): MessageChain

参数:

• id - 节点唯一标识
• name - 发送者显示名称
• userId - 发送者用户ID
• chain - 该节点内包含的消息链

返回值: 当前消息链实例（支持链式调用）

示例:

const forwardChain = new MessageChain()
    .Node("node1", "用户A", "111", new MessageChain().Text("你好"))
    .Node("node2", "用户B", "222", new MessageChain().Text("大家好").Image("https://example.com/pic.jpg"));

Node(id, name, userId, chain)

v0.4.0 新增

添加合并转发节点片段，用于构建合并转发消息。

语法: Node(id: string, name: string, userId: string, chain: MessageChain): MessageChain

参数:

• id - 节点标识
• name - 发送者名称
• userId - 发送者用户ID
• chain - 节点内的消息链

返回值: 当前消息链实例（支持链式调用）

示例:

const chain = new MessageChain()
    .Node("node1", "用户A", "123456", new MessageChain().Text("第一段消息"))
    .Node("node2", "用户B", "789012", new MessageChain().Text("第二段消息").Image("https://example.com/pic.jpg"));

输出方法

AsString()

将整个消息链转换为字符串。

语法: AsString(): string

返回值: 所有片段拼接后的完整字符串

使用示例

基础文本消息

const chain = new MessageChain().Text("Hello World!");

复杂消息组合

const chain = new MessageChain()
    .Text("欢迎新成员 ")
    .At("123456789")
    .Text(" 加入群聊！")
    .NextLine()
    .Image("https://example.com/welcome.jpg")
    .Face(1);

回复消息

const chain = new MessageChain()
    .Reply("originalMessageId")
    .Text("这是一条回复消息");

集合操作

const chain = new MessageChain();
chain.Add(new TextSegment("Hello"));
chain.Add(new AtSegment("123456"));

logger.info(`消息链包含 ${chain.Count} 个片段`);
logger.info(chain.AsString());

注意事项

1. 链式调用: 流式构建方法都返回当前实例，支持链式调用
2. 类型安全: 所有方法都有明确的类型定义
3. 性能: 内部使用数组存储，操作效率高
4. 兼容性: 实现了 IList 接口，与 .NET 集合兼容