Update docs

2025-01-27 08:50:15 +08:00 · 2020-12-19 13:57:38 +08:00 · 2020-12-19 13:57:38 +08:00 · 59eea052be
commit 59eea052be
parent 6ef928f5ec
5 changed files with 256 additions and 7 deletions
--- a/docs/ConfiguringProjects.md
+++ b/docs/ConfiguringProjects.md
@ -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>
--- a/docs/Contacts.md
+++ b/docs/Contacts.md
@ -1 +1,10 @@
-# Mirai - Contacts
+# Mirai - Contacts
+
+[![](https://mermaid.ink/img/eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5cbmNsYXNzIEJvdCB7XG4gICAgK2ZyaWVuZHM6IENvbnRhY3RMaXN0XG4gICAgK2dyb3VwczogQ29udGFjdExpc3RcbiAgICArZ2V0RnJpZW5kKExvbmcpIEZyaWVuZD9cbiAgICArZ2V0RnJpZW5kT3JOdWxsKExvbmcpIEZyaWVuZFxuICAgICtnZXRHcm91cChMb25nKSBHcm91cD9cbiAgICArZ2V0R3JvdXBPckZhaWwoTG9uZykgR3JvdXBcbiAgICArbG9naW4oKVxuICAgICtjbG9zZSgpXG59XG5cbmNsYXNzIENvbnRhY3RPckJvdCB7XG4gICAgK2lkOiBJbnRcbn1cblxuY2xhc3MgVXNlck9yQm90IHtcbiAgICArbnVkZ2UoKSBOdWRnZVxufVxuXG5jbGFzcyBDb250YWN0IHtcbiAgICArYm90OiBCb3RcbiAgICArc2VuZE1lc3NhZ2UoTWVzc2FnZSkgTWVzc2FnZVJlY2VpcHRcbiAgICArc2VuZE1lc3NhZ2UoU3RyaW5nKSBNZXNzYWdlUmVjZWlwdFxuICAgICt1cGxvYWRJbWFnZShFeHRlcm5hbEltYWdlKSBJbWFnZVxufVxuXG5jbGFzcyBVc2VyIHtcbiAgICArbmljazogU3RyaW5nXG4gICAgK3JlbWFyazogU3RyaW5nXG4gICAgK2F2YXRhclVybDogU3RyaW5nXG59XG5cbmNsYXNzIEdyb3VwIHtcbiAgICArbWVtYmVyczogQ29udGFjdExpc3RcbiAgICArbmFtZTogU3RyaW5nXG4gICAgK3NldHRpbmdzOiBHcm91cFNldHRpbmdzXG4gICAgK293bmVyOiBOb3JtYWxNZW1iZXJcbiAgICArYm90TXV0ZVJlbWFpbmluZzogTG9uZ1xuICAgICtib3RQZXJtaXNzaW9uOiBNZW1iZXJQZXJtaXNzaW9uXG4gICAgK3F1aXQoKSBCb29sZWFuXG4gICAgK3VwbG9hZFZvaWNlKCkgVm9pY2Vcbn1cblxuY2xhc3MgTm9ybWFsTWVtYmVyIHtcbiAgICArbXV0ZSgpXG4gICAgK2tpY2soKVxufVxuXG5jbGFzcyBBbm9ueW1vdXNNZW1iZXIge1xuICAgICthbm9ueW1vdXNJZDogU3RyaW5nXG59XG5cbmNsYXNzIE1lbWJlciB7XG4gICAgK2dyb3VwOiBHcm91cFxufVxuXG5Db250YWN0T3JCb3Q8LS1Db250YWN0XG5Db250YWN0T3JCb3Q8LS1Vc2VyT3JCb3RcblxuVXNlck9yQm90PC0tQm90XG5Vc2VyT3JCb3Q8LS1Vc2VyXG5cbkNvbnRhY3Q8LS1Vc2VyXG5Db250YWN0PC0tR3JvdXBcblxuVXNlcjwtLU1lbWJlclxuVXNlcjwtLUZyaWVuZFxuXG5NZW1iZXI8LS1Ob3JtYWxNZW1iZXJcbk1lbWJlcjwtLUFub255bW91c01lbWJlciIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5cbmNsYXNzIEJvdCB7XG4gICAgK2ZyaWVuZHM6IENvbnRhY3RMaXN0XG4gICAgK2dyb3VwczogQ29udGFjdExpc3RcbiAgICArZ2V0RnJpZW5kKExvbmcpIEZyaWVuZD9cbiAgICArZ2V0RnJpZW5kT3JOdWxsKExvbmcpIEZyaWVuZFxuICAgICtnZXRHcm91cChMb25nKSBHcm91cD9cbiAgICArZ2V0R3JvdXBPckZhaWwoTG9uZykgR3JvdXBcbiAgICArbG9naW4oKVxuICAgICtjbG9zZSgpXG59XG5cbmNsYXNzIENvbnRhY3RPckJvdCB7XG4gICAgK2lkOiBJbnRcbn1cblxuY2xhc3MgVXNlck9yQm90IHtcbiAgICArbnVkZ2UoKSBOdWRnZVxufVxuXG5jbGFzcyBDb250YWN0IHtcbiAgICArYm90OiBCb3RcbiAgICArc2VuZE1lc3NhZ2UoTWVzc2FnZSkgTWVzc2FnZVJlY2VpcHRcbiAgICArc2VuZE1lc3NhZ2UoU3RyaW5nKSBNZXNzYWdlUmVjZWlwdFxuICAgICt1cGxvYWRJbWFnZShFeHRlcm5hbEltYWdlKSBJbWFnZVxufVxuXG5jbGFzcyBVc2VyIHtcbiAgICArbmljazogU3RyaW5nXG4gICAgK3JlbWFyazogU3RyaW5nXG4gICAgK2F2YXRhclVybDogU3RyaW5nXG59XG5cbmNsYXNzIEdyb3VwIHtcbiAgICArbWVtYmVyczogQ29udGFjdExpc3RcbiAgICArbmFtZTogU3RyaW5nXG4gICAgK3NldHRpbmdzOiBHcm91cFNldHRpbmdzXG4gICAgK293bmVyOiBOb3JtYWxNZW1iZXJcbiAgICArYm90TXV0ZVJlbWFpbmluZzogTG9uZ1xuICAgICtib3RQZXJtaXNzaW9uOiBNZW1iZXJQZXJtaXNzaW9uXG4gICAgK3F1aXQoKSBCb29sZWFuXG4gICAgK3VwbG9hZFZvaWNlKCkgVm9pY2Vcbn1cblxuY2xhc3MgTm9ybWFsTWVtYmVyIHtcbiAgICArbXV0ZSgpXG4gICAgK2tpY2soKVxufVxuXG5jbGFzcyBBbm9ueW1vdXNNZW1iZXIge1xuICAgICthbm9ueW1vdXNJZDogU3RyaW5nXG59XG5cbmNsYXNzIE1lbWJlciB7XG4gICAgK2dyb3VwOiBHcm91cFxufVxuXG5Db250YWN0T3JCb3Q8LS1Db250YWN0XG5Db250YWN0T3JCb3Q8LS1Vc2VyT3JCb3RcblxuVXNlck9yQm90PC0tQm90XG5Vc2VyT3JCb3Q8LS1Vc2VyXG5cbkNvbnRhY3Q8LS1Vc2VyXG5Db250YWN0PC0tR3JvdXBcblxuVXNlcjwtLU1lbWJlclxuVXNlcjwtLUZyaWVuZFxuXG5NZW1iZXI8LS1Ob3JtYWxNZW1iZXJcbk1lbWJlcjwtLUFub255bW91c01lbWJlciIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)
+
+要主动发送一条消息，调用 `Contact.sendMessage()` 即可。
+
+可通过 `Bot.getFriend` 或 `Bot.getGroup` 获取相关对象。
+
+> 下一步，[Events](Events.md)
+> [回到 Mirai 文档索引](README.md)
--- a/docs/Events.md
+++ b/docs/Events.md
@ -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#事件)
--- a/docs/src/Contacts.mermaid.md
+++ b/docs/src/Contacts.mermaid.md
@ -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
+```
--- a/mirai-core-api/src/commonMain/kotlin/event/events/README.md
+++ b/mirai-core-api/src/commonMain/kotlin/event/events/README.md
@ -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

 #### 群成员