mirror of
https://github.com/mamoe/mirai.git
synced 2025-01-27 17:00:14 +08:00
Update docs
This commit is contained in:
Him188
parent
6ef928f5ec
commit
59eea052be
@ -4,7 +4,7 @@
|
||||
|
||||
mirai 使用纯 Kotlin 开发，最低要求 `JDK 1.8`，`Kotlin 1.4`。
|
||||
|
||||
如果你熟悉构建工具，只需要添加 `jcenter` 仓库和依赖 `net.mamoe:mirai-core:VERSION` 即可而不需要继续阅读。下文将详细解释这些步骤。
|
||||
如果你熟悉 Gradle，只需要添加 `jcenter` 仓库和依赖 `net.mamoe:mirai-core:VERSION` 即可而不需要继续阅读。下文将详细解释其他方法。
|
||||
|
||||
本文提供如下三种配置方法，但更推荐使用 Gradle 构建。
|
||||
|
||||
@ -86,7 +86,7 @@ dependencies {
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>net.mamoe</groupId>
|
||||
<artifactId>mirai-core</artifactId>
|
||||
<artifactId>mirai-core-jvm</artifactId>
|
||||
<version>1.3.3</version> <!-- 替换版本为你需要的版本 -->
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
@ -1 +1,10 @@
|
||||
# Mirai - Contacts
|
||||
|
||||
[](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5cbmNsYXNzIEJvdCB7XG4gICAgK2ZyaWVuZHM6IENvbnRhY3RMaXN0XG4gICAgK2dyb3VwczogQ29udGFjdExpc3RcbiAgICArZ2V0RnJpZW5kKExvbmcpIEZyaWVuZD9cbiAgICArZ2V0RnJpZW5kT3JOdWxsKExvbmcpIEZyaWVuZFxuICAgICtnZXRHcm91cChMb25nKSBHcm91cD9cbiAgICArZ2V0R3JvdXBPckZhaWwoTG9uZykgR3JvdXBcbiAgICArbG9naW4oKVxuICAgICtjbG9zZSgpXG59XG5cbmNsYXNzIENvbnRhY3RPckJvdCB7XG4gICAgK2lkOiBJbnRcbn1cblxuY2xhc3MgVXNlck9yQm90IHtcbiAgICArbnVkZ2UoKSBOdWRnZVxufVxuXG5jbGFzcyBDb250YWN0IHtcbiAgICArYm90OiBCb3RcbiAgICArc2VuZE1lc3NhZ2UoTWVzc2FnZSkgTWVzc2FnZVJlY2VpcHRcbiAgICArc2VuZE1lc3NhZ2UoU3RyaW5nKSBNZXNzYWdlUmVjZWlwdFxuICAgICt1cGxvYWRJbWFnZShFeHRlcm5hbEltYWdlKSBJbWFnZVxufVxuXG5jbGFzcyBVc2VyIHtcbiAgICArbmljazogU3RyaW5nXG4gICAgK3JlbWFyazogU3RyaW5nXG4gICAgK2F2YXRhclVybDogU3RyaW5nXG59XG5cbmNsYXNzIEdyb3VwIHtcbiAgICArbWVtYmVyczogQ29udGFjdExpc3RcbiAgICArbmFtZTogU3RyaW5nXG4gICAgK3NldHRpbmdzOiBHcm91cFNldHRpbmdzXG4gICAgK293bmVyOiBOb3JtYWxNZW1iZXJcbiAgICArYm90TXV0ZVJlbWFpbmluZzogTG9uZ1xuICAgICtib3RQZXJtaXNzaW9uOiBNZW1iZXJQZXJtaXNzaW9uXG4gICAgK3F1aXQoKSBCb29sZWFuXG4gICAgK3VwbG9hZFZvaWNlKCkgVm9pY2Vcbn1cblxuY2xhc3MgTm9ybWFsTWVtYmVyIHtcbiAgICArbXV0ZSgpXG4gICAgK2tpY2soKVxufVxuXG5jbGFzcyBBbm9ueW1vdXNNZW1iZXIge1xuICAgICthbm9ueW1vdXNJZDogU3RyaW5nXG59XG5cbmNsYXNzIE1lbWJlciB7XG4gICAgK2dyb3VwOiBHcm91cFxufVxuXG5Db250YWN0T3JCb3Q8LS1Db250YWN0XG5Db250YWN0T3JCb3Q8LS1Vc2VyT3JCb3RcblxuVXNlck9yQm90PC0tQm90XG5Vc2VyT3JCb3Q8LS1Vc2VyXG5cbkNvbnRhY3Q8LS1Vc2VyXG5Db250YWN0PC0tR3JvdXBcblxuVXNlcjwtLU1lbWJlclxuVXNlcjwtLUZyaWVuZFxuXG5NZW1iZXI8LS1Ob3JtYWxNZW1iZXJcbk1lbWJlcjwtLUFub255bW91c01lbWJlciIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)
|
||||
|
||||
要主动发送一条消息，调用 `Contact.sendMessage()` 即可。
|
||||
|
||||
可通过 `Bot.getFriend` 或 `Bot.getGroup` 获取相关对象。
|
||||
|
||||
> 下一步，[Events](Events.md)
|
||||
> [回到 Mirai 文档索引](README.md)
|
||||
162
docs/Events.md
Normal file
162
docs/Events.md
Normal file
@ -0,0 +1,162 @@
|
||||
# Mirai - Events
|
||||
|
||||
## 目录
|
||||
- [使用 `ListenerHost` 监听事件](#使用-listenerhost-监听事件)
|
||||
- [在 Kotlin 函数式监听](#在-kotlin-函数式监听)
|
||||
- [事件列表](#事件列表)
|
||||
|
||||
## 事件系统
|
||||
|
||||
Mirai 以事件驱动，使用者需要监听如 `收到消息`，`收到入群申请` 等事件。
|
||||
|
||||
有两种方法监听事件：
|
||||
- [使用 `ListenerHost` 监听事件](#使用-listenerhost-监听事件)
|
||||
- [在 Kotlin 函数式监听](#在-kotlin-函数式监听)
|
||||
|
||||
## 使用 `ListenerHost` 监听事件
|
||||
|
||||
标注一个函数（方法）为事件监听器。mirai 通过反射获取他们并为之注册事件。
|
||||
|
||||
> 详见 [EventHandler](../mirai-core-api/src/commonMain/kotlin/event/JvmMethodListeners.kt#L27-L168)
|
||||
|
||||
### Kotlin 函数
|
||||
|
||||
Kotlin 函数要求:
|
||||
- 接收者 (英 receiver) 和函数参数: 所标注的 Kotlin 函数必须至少拥有一个接收者或一个函数参数, 或二者都具有. 接收者和函数参数的类型必须相同 (如果二者都存在)
|
||||
接收者或函数参数的类型都必须为 `Event` 或其子类.
|
||||
- 返回值: 为 `Unit` 或不指定返回值时将注册为 `CoroutineScope.subscribeAlways`, 为 `ListeningStatus` 时将注册为 `CoroutineScope.subscribe`.
|
||||
任何其他类型的返回值将会在注册时抛出异常.
|
||||
|
||||
所有 Kotlin 非 `suspend` 的函数都将会在 `Dispatchers.IO` 中调用
|
||||
|
||||
支持的函数类型:
|
||||
```kotlin
|
||||
// 所有函数参数, 函数返回值都不允许标记为可空 (带有 '?' 符号)
|
||||
// T 表示任何 Event 类型.
|
||||
suspend fun T.onEvent(T)
|
||||
suspend fun T.onEvent(T): ListeningStatus
|
||||
suspend fun T.onEvent(T): Nothing
|
||||
suspend fun onEvent(T)
|
||||
suspend fun onEvent(T): ListeningStatus
|
||||
suspend fun onEvent(T): Nothing
|
||||
suspend fun T.onEvent()
|
||||
suspend fun T.onEvent(): ListeningStatus
|
||||
suspend fun T.onEvent(): Nothing
|
||||
fun T.onEvent(T)
|
||||
fun T.onEvent(T): ListeningStatus
|
||||
fun T.onEvent(T): Nothing
|
||||
fun onEvent(T)
|
||||
fun onEvent(T): ListeningStatus
|
||||
fun onEvent(T): Nothing
|
||||
fun T.onEvent()
|
||||
fun T.onEvent(): ListeningStatus
|
||||
fun T.onEvent(): Nothing
|
||||
```
|
||||
|
||||
Kotlin 使用示例:
|
||||
|
||||
- 独立 `CoroutineScope` 和 `ListenerHost`
|
||||
```kotlin
|
||||
object MyEvents : ListenerHost {
|
||||
override val coroutineContext = SupervisorJob()
|
||||
// 可以抛出任何异常, 将在 this.coroutineContext 或 registerEvents 时提供的 CoroutineScope.coroutineContext 中的 CoroutineExceptionHandler 处理.
|
||||
@EventHandler
|
||||
suspend fun MessageEvent.onMessage() {
|
||||
reply("received")
|
||||
}
|
||||
}
|
||||
myCoroutineScope.registerEvents(MyEvents)
|
||||
```
|
||||
`onMessage` 抛出的异常将会交给 `myCoroutineScope` 处理
|
||||
|
||||
- 合并 `CoroutineScope` 和 `ListenerHost`: 使用 `SimpleListenerHost`
|
||||
```kotlin
|
||||
object MyEvents : SimpleListenerHost( /* override coroutineContext here */ ) {
|
||||
override fun handleException(context: CoroutineContext, exception: Throwable) {
|
||||
// 处理 onMessage 中未捕获的异常
|
||||
}
|
||||
@EventHandler
|
||||
suspend fun MessageEvent.onMessage() { // 可以抛出任何异常, 将在 handleException 处理
|
||||
reply("received")
|
||||
// 无返回值 (或者返回 Unit), 表示一直监听事件.
|
||||
}
|
||||
@EventHandler
|
||||
suspend fun MessageEvent.onMessage(): ListeningStatus { // 可以抛出任何异常, 将在 handleException 处理
|
||||
reply("received")
|
||||
return ListeningStatus.LISTENING // 表示继续监听事件
|
||||
// return ListeningStatus.STOPPED // 表示停止监听事件
|
||||
}
|
||||
}
|
||||
MyEvents.registerEvents()
|
||||
```
|
||||
### Java 方法
|
||||
|
||||
所有 Java 方法都会在 `Dispatchers.IO` 中调用，因此在 Java 可以调用阻塞方法。
|
||||
|
||||
支持的方法类型：
|
||||
```
|
||||
// T 表示任何 Event 类型.
|
||||
void onEvent(T)
|
||||
Void onEvent(T)
|
||||
ListeningStatus onEvent(T) // 返回 null 时将抛出异常
|
||||
```
|
||||
|
||||
Java 使用示例:
|
||||
|
||||
```java
|
||||
public class MyEventHandlers extends SimpleListenerHost {
|
||||
@Override
|
||||
public void handleException(@NotNull CoroutineContext context, @NotNull Throwable exception){
|
||||
// 处理事件处理时抛出的异常
|
||||
}
|
||||
@EventHandler
|
||||
public void onMessage(@NotNull MessageEvent event) throws Exception { // 可以抛出任何异常, 将在 handleException 处理
|
||||
event.subject.sendMessage("received");
|
||||
// 无返回值, 表示一直监听事件.
|
||||
}
|
||||
@NotNull
|
||||
@EventHandler
|
||||
public ListeningStatus onMessage(@NotNull MessageEvent event) throws Exception { // 可以抛出任何异常, 将在 handleException 处理
|
||||
event.subject.sendMessage("received");
|
||||
return ListeningStatus.LISTENING; // 表示继续监听事件
|
||||
// return ListeningStatus.STOPPED; // 表示停止监听事件
|
||||
}
|
||||
}
|
||||
|
||||
// 注册：
|
||||
// Events.registerEvents(new MyEventHandlers())
|
||||
```
|
||||
|
||||
## 在 Kotlin 函数式监听
|
||||
[CoroutineScope.subscribe](../mirai-core-api/src/commonMain/kotlin/event/subscriber.kt#L137-L220)
|
||||
|
||||
用法示例：
|
||||
```kotlin
|
||||
object YourApplication : CoroutineScope by CoroutineScope(SupervisorJob())
|
||||
|
||||
// 启动事件监听器
|
||||
YourApplication.subscribeAlways<GroupMessageEvent> {
|
||||
// this: GroupMessageEvent
|
||||
// it: GroupMessageEvent
|
||||
// lambda 的 this 和参数都是 GroupMessageEvent
|
||||
|
||||
group.sendMessage(sender.at() + "Hello! ${sender.nick}")
|
||||
}
|
||||
|
||||
// YouApplication[Job]!!.cancel() //
|
||||
```
|
||||
|
||||
Mirai 也支持传递函数引用：
|
||||
```kotlin
|
||||
YourApplication.subscribeAlways<GroupMessageEvent> {
|
||||
// this: GroupMessageEvent
|
||||
// it: GroupMessageEvent
|
||||
// lambda 的 this 和参数都是 GroupMessageEvent
|
||||
|
||||
group.sendMessage(sender.at() + "Hello! ${sender.nick}")
|
||||
}
|
||||
```
|
||||
|
||||
## 事件列表
|
||||
|
||||
[事件列表](../mirai-core-api/src/commonMain/kotlin/event/events/README.md#事件)
|
||||
74
docs/src/Contacts.mermaid.md
Normal file
74
docs/src/Contacts.mermaid.md
Normal file
@ -0,0 +1,74 @@
|
||||
```mermaid
|
||||
classDiagram
|
||||
|
||||
class Bot {
|
||||
+friends: ContactList
|
||||
+groups: ContactList
|
||||
+getFriend(Long) Friend?
|
||||
+getFriendOrNull(Long) Friend
|
||||
+getGroup(Long) Group?
|
||||
+getGroupOrFail(Long) Group
|
||||
+login()
|
||||
+close()
|
||||
}
|
||||
|
||||
class ContactOrBot {
|
||||
+id: Int
|
||||
}
|
||||
|
||||
class UserOrBot {
|
||||
+nudge() Nudge
|
||||
}
|
||||
|
||||
class Contact {
|
||||
+bot: Bot
|
||||
+sendMessage(Message) MessageReceipt
|
||||
+sendMessage(String) MessageReceipt
|
||||
+uploadImage(ExternalImage) Image
|
||||
}
|
||||
|
||||
class User {
|
||||
+nick: String
|
||||
+remark: String
|
||||
+avatarUrl: String
|
||||
}
|
||||
|
||||
class Group {
|
||||
+members: ContactList
|
||||
+name: String
|
||||
+settings: GroupSettings
|
||||
+owner: NormalMember
|
||||
+botMuteRemaining: Long
|
||||
+botPermission: MemberPermission
|
||||
+quit() Boolean
|
||||
+uploadVoice() Voice
|
||||
}
|
||||
|
||||
class NormalMember {
|
||||
+mute()
|
||||
+kick()
|
||||
}
|
||||
|
||||
class AnonymousMember {
|
||||
+anonymousId: String
|
||||
}
|
||||
|
||||
class Member {
|
||||
+group: Group
|
||||
}
|
||||
|
||||
ContactOrBot<--Contact
|
||||
ContactOrBot<--UserOrBot
|
||||
|
||||
UserOrBot<--Bot
|
||||
UserOrBot<--User
|
||||
|
||||
Contact<--User
|
||||
Contact<--Group
|
||||
|
||||
User<--Member
|
||||
User<--Friend
|
||||
|
||||
Member<--NormalMember
|
||||
Member<--AnonymousMember
|
||||
```
|
||||
@ -25,9 +25,10 @@
|
||||
- (`1.3.0+`) Bot 被戳: BotNudgedEvent
|
||||
|
||||
### [消息](message.kt)
|
||||
- (`1.1.0-`) 主动发送消息: MessageSendEvent
|
||||
- 群消息: GroupMessageSendEvent
|
||||
- 好友消息: FriendMessageSendEvent
|
||||
- 被动收到消息：MessageEvent
|
||||
- 群消息：GroupMessageEvent
|
||||
- 好友消息：FriendMessageEvent
|
||||
- 群临时会话消息：TempMessageEvent
|
||||
- (`1.1.0+`) 主动发送消息前: MessagePreSendEvent
|
||||
- 群消息: GroupMessagePreSendEvent
|
||||
- 好友消息: FriendMessagePreSendEvent
|
||||
@ -44,6 +45,9 @@
|
||||
- 图片上传完成: ImageUploadEvent
|
||||
- 图片上传成功: Succeed
|
||||
- 图片上传失败: Failed
|
||||
- (`1.1.0-`) ~~主动发送消息: MessageSendEvent~~
|
||||
- ~~群消息: GroupMessageSendEvent~~
|
||||
- ~~好友消息: FriendMessageSendEvent~~
|
||||
|
||||
### [群](group.kt)
|
||||
- 机器人被踢出群或在其他客户端主动退出一个群: BotLeaveEvent
|
||||
@ -60,7 +64,7 @@
|
||||
- 入群公告改变: GroupEntranceAnnouncementChangeEvent
|
||||
- 全员禁言状态改变: GroupMuteAllEvent
|
||||
- 匿名聊天状态改变: GroupAllowAnonymousChatEvent
|
||||
- 坦白说状态改变: GroupAllowConfessTalkEvent
|
||||
- (`1.3.0-`) ~~坦白说状态改变: GroupAllowConfessTalkEvent~~
|
||||
- 允许群员邀请好友加群状态改变: GroupAllowMemberInviteEvent
|
||||
|
||||
#### 群成员
|
||||
|
||||
Loading…
Reference in New Issue
Block a user