Bot

Bot, 一个机器人。simbot 作为一个Bot风格的事件调度框架, Bot 是一个很常见也很关键的类型。

注册/创建

一个 Bot 通常由某个 Bot管理器注册创建。有关于注册 Bot 的相关说明你可以前往组件与插件-Bot管理器章节查看。

启动

一个被注册出来的 Bot 是尚未启动的, 你需要在适当的地方启动它, 它才会开始运作（例如开始接收事件）。

val bot = botManager.register(...)
bot.start() // 启动它

var bot = botManager.register(...);
var future = bot.startAsync(); // 异步中启动它
// ...

var bot = botManager.register(...);
bot.startBlocking(); // 启动它

基本信息与能力

你可以在 Bot 中获取到一些基本的信息, 以及 Bot 会提供一些针对其生命周期的基本能力。

name

Bot 的名称。通常只有满足某些条件后（比如在 start 了之后）才能获取。

id

Bot 的 ID。但是此ID通常是注册 Bot 时使用的某种 ID（比如 APPID, 而这个 ID 并不一定就是 Bot 作为用户的 ID。

component

Bot 所属的组件的组件标识。

isMe(...)

提供一个 ID, 用于判断这个 ID 是否代表当前 Bot。

isStarted

判断当前 Bot 是否已经启动过至少一次。

isActive

判断当前 Bot 是否处于活跃状态。

isCompleted

判断当前 Bot 是否处于已完成状态。

join(...)

挂起 Bot, 直到它被关闭。

cancel(...)

关闭 Bot。

guildRelation

GuildRelation? 类型, 如果不为 null 则说明其支持与频道进行交互、获取信息。

其他详细内容下文会介绍。

groupRelation

GroupRelation? 类型, 如果不为 null 则说明其支持与聊天群进行交互、获取信息。

其他详细内容下文会介绍。

contactRelation

ContactRelation? 类型, 如果不为 null 则说明其支持与联系人进行交互、获取信息。

其他详细内容下文会介绍。

messageFromId(ID)

根据一个消息ID 获取它对应地源消息。

如果实现者尚未实现此功能则会抛出 UnsupportedOperationException。
如果存在消息ID、但对应平台明确由于各种原因无法根据ID查询源消息时会抛出 UnsupportedOperationException。
如果存在消息ID、但无法仅通过一个 ID 来进行查询时 (例如需要其他附加的复合信息查询) 会抛出 UnsupportedOperationException 。此时实现者应当提供另外可供使用的专属API。
否则，将根据 ID 查询并得到其对应地 MessageContent。

messageFromReference(MessageReference)

根据一个消息引用 (MessageReference) 查询或获取它对应地源消息。

如果实现者尚未实现此功能则会抛出 UnsupportedOperationException。
如果实现的对应平台明确存在引用的概念、但由于各种原因无法查询引用源消息时，将会抛出 UnsupportedOperationException。
如果实现的对应平台明确存在引用的概念、但消息引用无法使用 MessageReference 进行表达时，将会抛出 UnsupportedOperationException。 (如果是此原因，则实现者应当提供另外可供使用的专属API。)
否则，将根据具体地引用信息查询并得到其对应地 MessageContent。

如果一个消息引用等同于一个消息的ID，那么 messageFromReference 的效果等同于 messageFromId。

行为对象交互

GuildRelation

与频道的关系交互类型, 其中包含了一些获取 Guild 相关信息的 API。

guild(...): 根据 ID 寻找指定的 Guild 目标。
guilds: 获取 Bot 所在的所有 Guild 的集。
guildCount(): 获取 Bot 所在的所有 Guild 的数量。不支持的情况下可能会返回 -1 或直接通过拉取列表计数。

GroupRelation

与聊天群的关系交互类型, 其中包含了一些获取 ChatGroup 相关信息的 API。

group(...): 根据 ID 寻找指定的 ChatGroup 目标。
groups: 获取 Bot 所在的所有 ChatGroup 的集。
groupCount(): 获取 Bot 所在的所有 ChatGroup 的数量。不支持的情况下可能会返回 -1 或直接通过拉取列表计数。

ContactRelation

与联系人的关系交互类型, 其中包含了一些获取 Contact 相关信息的 API。

contact(...): 根据 ID 寻找指定的 Contact 目标。
contacts: 获取 Bot 所在的所有 Contact 的集。
contactCount(): 获取 Bot 所在的所有 Contact 的数量。不支持的情况下可能会返回 -1 或直接通过拉取列表计数。

额外扩展

Bot 的具体实现可能会根据平台的实际情况提供更多额外的、专属的API。

Last modified: 19 September 2024