mirai/docs/ConciseAPI.md

Mirai - Concise API

注:

• 本章节展示关于 mirai-core-api 比较常用的 API 示例
• 请配合 mirai-core-api 源码查看
• 本章仅提供 API 粗略介绍

---

Bots

BotFactory

BotFactory 用于创建一个新的 Bot, 详情请看 Bots.md

val bot = BotFactory.newBot(/*....*/)

// Java
Bot bot = BotFactory.INSTANCE.newBot(/*....*/);
Bot bot = Mirai.getInstance().getBotFactory().newBot(/*....*/);

Misc utils

Logger

Mirai 全部的日志都通过 MiraiLogger 输出, 查看 MiraiLogger 源码注释获得更多信息

ExternalResource

ExternalResource 代表一个外部文件, 可用于 文件上传, 图片发送, etc.

构造 ExternalResource 可以通过以下方法构造

// kotlin
File("foo.txt").toExternalResource()

// java
ExternalResource.create(new File("foo.txt"))

ExternalResource.create() 内置支持的数据类型有 java.io.File, java.io.RandomAccessFile, byte[], java.io.InputStream

注:

• ExternalResource 和 java.io.InputStream 等资源一样, 需要手动关闭 close()
• 使用 java.io.InputStream 构造 ExternalResource 时, 需要关闭 java.io.InputStream
• 使用 java.io.RandomAccessFile 构造 ExternalResource 时, 请不要关闭 RandomAccessFile, 否则会间接关闭 ExternalResource

// Example

// kotlin
val inputStream: InputStream = TODO()
val resource = inputStream.use { it.toExternalResource() }

// java
ExternalResource resource;
try (InputStream inputStream = TODO()) {
    resource = ExternalResource.create(inputStream);
} catch (IOException exception) {
    // on Exception catch
    throw new RuntimeException("Can't create a new external resource", exception);
}

自行实现 ExternalResource

从 2.9.0 开始，可以很容易实现自定义 ExternalResource

@see AbstractExternalResource 源码注释

Contact & Message

Send Image

Origin send image

最原始的发送图片的方法，就是先 uploadImage 然后 sendMessage

Kotlin 可以使用自动补全得到相关方法

contact.uploadImage // IDEA 补全

Java 可以使用 contact.uploadImage(ExternalResource) 来得到一个图片对象 (这也是为啥 ExternalResource 在前面) 也可以使用 Contact 内的静态方法

Image i = Contact.uploadImage(/*....*/);
Image i = ExternalResource.uploadAsImage(/*...*/);

sendImage

sendImage 相当于先进行 uploadImage 然后再 sendMessage

Kotlin 可以使用自动补全得到相关方法

contact.sendImage // IDEA 补全

由于 sendImage 是 Contact 和 ExternalResource 内的静态方法, Java 可以使用下述方法调用

Contact.sendImage(/**/);
ExternalResource.sendAsImage(/*...*/);

Send Audio

发送语音与发送图片的区别不大，都是先 upload 然后 send

• 在 2.7.0 之前，只有群聊 (Group) 支持语音（使用 Voice）, 2.7.0 之后支持私聊语音（使用 Audio）
• 每次发送新语音前最好重新 upload, 避免复用 Audio 对象
• 只支持 amr 和 silk 格式

要得到一个语音对象, 需要先 uploadAudio

Kotlin 可以使用自动补全得到相关方法

contact.uploadAudio // IDEA 补全

Java 可以使用 contact.uploadAudio(ExternalResource) 来得到一个语音对象 (这也是为啥 ExternalResource 在前面) 也可以使用 ExternalResource 定义的扩展方法：

contact.sendMessage(ExternalResource.uploadAsAudio(/*...*/));

Members

Member 对象分为 NormalMember(正常的群成员) 和 AnonymousMember(匿名)

对 Member 操作时需要具体操作时应该先判断是否为 NormalMember 然后强转

// kotlin
if (member is NormalMember) { // kotlin smart cast
}

// java
if (member instanceof NormalMember) {
    NormalMember nMember = (NormalMember) member;
}

Recall Message

撤回信息可以通过 MessageChain 或者 MessageSource 撤回。

subscribeAlways<MessageEvent> {// this: MessageEvent
    this.message.recall()

    this.message.source.recall()
    
    // Java
    MessageSource.recall(event.getMessage());
    MessageSource.recall(event.getMessage().getOrFail(MessageSource.Key));
}

Events

常用事件

Name	Desc
MessageEvent	Bot 收到一条新消息
NewFriendRequestEvent	你有一条新的好友申请
MemberJoinEvent	有新群成员加入群
MemberLeaveEvent	群成员离开群聊
BotInvitedJoinGroupRequestEvent	Bot 收到了一个加群邀请
BotJoinGroupEvent	Bot 加入了一个群聊
MemberJoinRequestEvent	新的入群申请

MessageEvent

当直接监听 MessageEvent 时，可以考虑排除 Bot 信息同步事件 MessageSyncEvent

MessageSyncEvent 是 Bot 账号在其他客户端发送消息时同步到 mirai 的事件

eventChannel.subscribeAlways<MessageEvent> { // this: MessageEvent
    if (this is MessageSyncEvent) return@subscribeAlways
}

IMirai

Mirai API 接口. 是 Mirai API 与 Mirai 协议实现对接的接口.

IMirai 内定义的接口都是较底层的 API, 如果无必要, 尽量避免使用 IMirai 相关的方法

最底层的方法位于 LowLevelApiAccessor 内, 其方法都使用 @LowLeveApi 标注, IMirai 接口继承 LowLevelApiAccessor

使用 IMirai 的标准 API 有稳定性保障, 但是由 @LowLevelApi 标注的方法无保障