From 7b5cbfce5b3c1bd448d043b2457168b2979e9ea1 Mon Sep 17 00:00:00 2001 From: Him188 Date: Wed, 13 Jan 2021 16:07:02 +0800 Subject: [PATCH] Update docs --- docs/Bots.md | 2 +- docs/ConfiguringProjects.md | 21 +++++++++++++++++---- docs/Contacts.md | 21 +++++++++++++++++---- docs/Events.md | 4 +++- docs/Evolution.md | 4 +++- docs/KotlinAndJava.md | 7 ++++++- docs/Messages.md | 10 ++++++++-- docs/Preparations.md | 9 +++++++-- docs/README.md | 6 +++++- docs/mirai-ecology.md | 4 ++-- 10 files changed, 69 insertions(+), 19 deletions(-) diff --git a/docs/Bots.md b/docs/Bots.md index 34bd6bab0a5..b9d975450b7 100644 --- a/docs/Bots.md +++ b/docs/Bots.md @@ -179,4 +179,4 @@ setLoginSolver(new YourLoginSolver()) > 下一步，[Contacts](Contacts.md) > -> [回到 Mirai 文档索引](README.md) +> [回到 Mirai 文档索引](README.md#mirai-core-api-文档) diff --git a/docs/ConfiguringProjects.md b/docs/ConfiguringProjects.md index 7e401a9ee2c..44528d972c8 100644 --- a/docs/ConfiguringProjects.md +++ b/docs/ConfiguringProjects.md @@ -35,7 +35,7 @@ ```kotlin plugins { - kotlin("jvm") version "1.4.21" + kotlin("jvm") version "1.4.21" // 请确保添加 Kotlin，至少使用 1.4.0 版本 } repositories { @@ -47,7 +47,11 @@ dependencies { } ``` -注意，必须添加 Kotlin 插件才能正确获取 mirai 软件包。 +**注意，必须添加 Kotlin 插件才能正确获取 mirai 软件包。** + +> 依赖配置完成，请选择： +> - [分离 API 和实现（可选）](#分离-api-和实现可选) +> - [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发) ### Gradle Groovy DSL @@ -55,7 +59,7 @@ dependencies { ```groovy plugins { - id 'org.jetbrains.kotlin.jvm' version '1.4.21' + id 'org.jetbrains.kotlin.jvm' version '1.4.21' // 请确保添加 Kotlin，至少使用 1.4.0 版本 } repositories { @@ -67,9 +71,13 @@ dependencies { } ``` +> 依赖配置完成，请选择： +> - [分离 API 和实现（可选）](#分离-api-和实现可选) +> - [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发) + ### 分离 API 和实现（可选） -mirai 在开发时需要 `net.mamoe:mirai-core-api`, 在运行时需要 `net.mamoe:mirai-core`。可以在开发和编译时只依赖 `mirai-core-api`。 +mirai 在开发时需要 `net.mamoe:mirai-core-api`, 在运行时需要 `net.mamoe:mirai-core`。可以在开发和编译时只依赖 `mirai-core-api`，会减轻对 IDE 的负担。 ```kotlin dependencies { val miraiVersion = "2.0-RC" // 替换为你需要的版本号 @@ -126,8 +134,13 @@ dependencies { > 可以在 [Kotlin 官方文档](https://www.kotlincn=.net/docs/reference/using-maven.html) 获取更多有关配置 Kotlin 的信息。 + +> 依赖配置完成，[回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发) + ## C. 下载 JAR 包 非常不推荐这种方法，请尽可能使用构建工具。 在 [Jcenter](https://jcenter.bintray.com/net/mamoe/mirai-core-all/) 或 [阿里云代理仓库](https://maven.aliyun.com/repository/public/net/mamoe/mirai-core-all/) 下载指定版本的 `-all.jar` 文件，即包含 `mirai-core`，`mirai-core-api`，`mirai-core-utils` 和其他依赖。 + +> [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发) \ No newline at end of file diff --git a/docs/Contacts.md b/docs/Contacts.md index 20af0b5dd3d..728b607a29c 100644 --- a/docs/Contacts.md +++ b/docs/Contacts.md @@ -2,13 +2,26 @@ [![](https://mermaid.ink/img/eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5cbmNsYXNzIEJvdCB7XG4gICAgK2ZyaWVuZHM6IENvbnRhY3RMaXN0XG4gICAgK2dyb3VwczogQ29udGFjdExpc3RcbiAgICArZ2V0RnJpZW5kKExvbmcpIEZyaWVuZD9cbiAgICArZ2V0RnJpZW5kT3JOdWxsKExvbmcpIEZyaWVuZFxuICAgICtnZXRHcm91cChMb25nKSBHcm91cD9cbiAgICArZ2V0R3JvdXBPckZhaWwoTG9uZykgR3JvdXBcbiAgICArbG9naW4oKVxuICAgICtjbG9zZSgpXG59XG5cbmNsYXNzIENvbnRhY3RPckJvdCB7XG4gICAgK2lkOiBJbnRcbiAgICArYXZhdGFyVXJsOiBTdHJpbmdcbn1cblxuY2xhc3MgVXNlck9yQm90IHtcbiAgICArbnVkZ2UoKSBOdWRnZVxufVxuXG5jbGFzcyBDb250YWN0IHtcbiAgICArYm90OiBCb3RcbiAgICArc2VuZE1lc3NhZ2UoTWVzc2FnZSkgTWVzc2FnZVJlY2VpcHRcbiAgICArc2VuZE1lc3NhZ2UoU3RyaW5nKSBNZXNzYWdlUmVjZWlwdFxuICAgICt1cGxvYWRJbWFnZShFeHRlcm5hbEltYWdlKSBJbWFnZVxufVxuXG5jbGFzcyBVc2VyIHtcbiAgICArbmljazogU3RyaW5nXG4gICAgK3JlbWFyazogU3RyaW5nXG59XG5cbmNsYXNzIEdyb3VwIHtcbiAgICArbWVtYmVyczogQ29udGFjdExpc3RcbiAgICArbmFtZTogU3RyaW5nXG4gICAgK3NldHRpbmdzOiBHcm91cFNldHRpbmdzXG4gICAgK293bmVyOiBOb3JtYWxNZW1iZXJcbiAgICArYm90TXV0ZVJlbWFpbmluZzogTG9uZ1xuICAgICtib3RQZXJtaXNzaW9uOiBNZW1iZXJQZXJtaXNzaW9uXG4gICAgK3F1aXQoKSBCb29sZWFuXG4gICAgK3VwbG9hZFZvaWNlKCkgVm9pY2Vcbn1cblxuY2xhc3MgTm9ybWFsTWVtYmVyIHtcbiAgICArbXV0ZSgpXG4gICAgK2tpY2soKVxufVxuXG5jbGFzcyBBbm9ueW1vdXNNZW1iZXIge1xuICAgICthbm9ueW1vdXNJZDogU3RyaW5nXG59XG5cbmNsYXNzIE1lbWJlciB7XG4gICAgK2dyb3VwOiBHcm91cFxufVxuXG5Db250YWN0T3JCb3Q8fC0tQ29udGFjdFxuQ29udGFjdE9yQm90PHwtLVVzZXJPckJvdFxuXG5Vc2VyT3JCb3Q8fC0tQm90XG5Vc2VyT3JCb3Q8fC0tVXNlclxuXG5Db250YWN0PHwtLVVzZXJcbkNvbnRhY3Q8fC0tR3JvdXBcblxuVXNlcjx8LS1NZW1iZXJcblVzZXI8fC0tRnJpZW5kXG5cbk1lbWJlcjx8LS1Ob3JtYWxNZW1iZXJcbk1lbWJlcjx8LS1Bbm9ueW1vdXNNZW1iZXIiLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5cbmNsYXNzIEJvdCB7XG4gICAgK2ZyaWVuZHM6IENvbnRhY3RMaXN0XG4gICAgK2dyb3VwczogQ29udGFjdExpc3RcbiAgICArZ2V0RnJpZW5kKExvbmcpIEZyaWVuZD9cbiAgICArZ2V0RnJpZW5kT3JOdWxsKExvbmcpIEZyaWVuZFxuICAgICtnZXRHcm91cChMb25nKSBHcm91cD9cbiAgICArZ2V0R3JvdXBPckZhaWwoTG9uZykgR3JvdXBcbiAgICArbG9naW4oKVxuICAgICtjbG9zZSgpXG59XG5cbmNsYXNzIENvbnRhY3RPckJvdCB7XG4gICAgK2lkOiBJbnRcbiAgICArYXZhdGFyVXJsOiBTdHJpbmdcbn1cblxuY2xhc3MgVXNlck9yQm90IHtcbiAgICArbnVkZ2UoKSBOdWRnZVxufVxuXG5jbGFzcyBDb250YWN0IHtcbiAgICArYm90OiBCb3RcbiAgICArc2VuZE1lc3NhZ2UoTWVzc2FnZSkgTWVzc2FnZVJlY2VpcHRcbiAgICArc2VuZE1lc3NhZ2UoU3RyaW5nKSBNZXNzYWdlUmVjZWlwdFxuICAgICt1cGxvYWRJbWFnZShFeHRlcm5hbEltYWdlKSBJbWFnZVxufVxuXG5jbGFzcyBVc2VyIHtcbiAgICArbmljazogU3RyaW5nXG4gICAgK3JlbWFyazogU3RyaW5nXG59XG5cbmNsYXNzIEdyb3VwIHtcbiAgICArbWVtYmVyczogQ29udGFjdExpc3RcbiAgICArbmFtZTogU3RyaW5nXG4gICAgK3NldHRpbmdzOiBHcm91cFNldHRpbmdzXG4gICAgK293bmVyOiBOb3JtYWxNZW1iZXJcbiAgICArYm90TXV0ZVJlbWFpbmluZzogTG9uZ1xuICAgICtib3RQZXJtaXNzaW9uOiBNZW1iZXJQZXJtaXNzaW9uXG4gICAgK3F1aXQoKSBCb29sZWFuXG4gICAgK3VwbG9hZFZvaWNlKCkgVm9pY2Vcbn1cblxuY2xhc3MgTm9ybWFsTWVtYmVyIHtcbiAgICArbXV0ZSgpXG4gICAgK2tpY2soKVxufVxuXG5jbGFzcyBBbm9ueW1vdXNNZW1iZXIge1xuICAgICthbm9ueW1vdXNJZDogU3RyaW5nXG59XG5cbmNsYXNzIE1lbWJlciB7XG4gICAgK2dyb3VwOiBHcm91cFxufVxuXG5Db250YWN0T3JCb3Q8fC0tQ29udGFjdFxuQ29udGFjdE9yQm90PHwtLVVzZXJPckJvdFxuXG5Vc2VyT3JCb3Q8fC0tQm90XG5Vc2VyT3JCb3Q8fC0tVXNlclxuXG5Db250YWN0PHwtLVVzZXJcbkNvbnRhY3Q8fC0tR3JvdXBcblxuVXNlcjx8LS1NZW1iZXJcblVzZXI8fC0tRnJpZW5kXG5cbk1lbWJlcjx8LS1Ob3JtYWxNZW1iZXJcbk1lbWJlcjx8LS1Bbm9ueW1vdXNNZW1iZXIiLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ) +| 类型 | 描述 | 最低支持的版本 | +|:--------------:|:---------------------------------------------------|:-----------:| +| `ContactOrBot` | `Contact` 和 `Bot` 的公共接口 | 2.0 | +| `OtherClient` | Bot 的*其他客户端*, 如 "我的 iPad", "我的电脑" | 2.0 | +| `Bot` | 机器人对象 | 2.0 | +| `Contact` | 联系人对象, 即所有的群, 好友, 陌生人, 群成员等 | 2.0 | +| `Group` | 群对象 | 2.0 | +| `User` | 用户对象, 即 "个人". 包含好友, 陌生人, 群成员, 临时会话用户 | 2.0 | +| `Friend` | 好友对象 | 2.0 | +| `Stranger` | 陌生人对象 | 2.0 | +| `Member` | 群成员对象, 属于一个 `Group`. | 2.0 | -基于面向对象的设计，可直接获取 `Contact` 的属性如 `nick`，`permission`。 +基于面向对象的设计，可直接获取 `Contact` 的属性如 `nick`，`permission`。请在实践时在接口源码内查看更清晰的说明。 -要主动发送一条消息，调用 `Contact.sendMessage()` 即可*（后文介绍）*。 +要主动发送一条消息，总是调用 `Contact.sendMessage(message)`*（`message` 在后文介绍）*。 -可通过 `Bot.getFriend` 或 `Bot.getGroup` 获取相关对象，也可以通过事件获取*（后文介绍）*。 +可通过 `Bot.getFriend`， `Bot.getGroup`，`Bot.getStranger` 获取相关对象，也可以通过事件获取 *（事件在后文介绍）*。 + +---- > 下一步，[Events](Events.md) > -> [回到 Mirai 文档索引](README.md) \ No newline at end of file +> [回到 Mirai 文档索引](README.md#mirai-core-api-文档) \ No newline at end of file diff --git a/docs/Events.md b/docs/Events.md index 66db503c313..bdbb2a6d882 100644 --- a/docs/Events.md +++ b/docs/Events.md @@ -462,6 +462,8 @@ reply("复读模式结束") ###### 　 +---- + > 下一步，[Messages](Messages.md) > -> [回到 Mirai 文档索引](README.md) +> [回到 Mirai 文档索引](README.md#mirai-core-api-文档) diff --git a/docs/Evolution.md b/docs/Evolution.md index ed6f55b3226..eb3a82a5080 100644 --- a/docs/Evolution.md +++ b/docs/Evolution.md @@ -47,4 +47,6 @@ Mirai 的版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/# -> [回到 Mirai 文档索引](README.md) \ No newline at end of file +---- + +> [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发) \ No newline at end of file diff --git a/docs/KotlinAndJava.md b/docs/KotlinAndJava.md index 19f687d3385..0a51a170b39 100644 --- a/docs/KotlinAndJava.md +++ b/docs/KotlinAndJava.md @@ -300,4 +300,9 @@ public final class A { } ``` -Java 使用者可以认为 `@JvmBlockingBridge suspend fun getValue(): String` 相当于 `fun getValue(): String`。 \ No newline at end of file +Java 使用者可以认为 `@JvmBlockingBridge suspend fun getValue(): String` 相当于 `fun getValue(): String`。 + + +---- + +> [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发) \ No newline at end of file diff --git a/docs/Messages.md b/docs/Messages.md index cebe70baa2d..01bb8cc73e1 100644 --- a/docs/Messages.md +++ b/docs/Messages.md @@ -309,9 +309,15 @@ val chain = "[mirai:atall]".deserializeMiraiCode() MessageChain chain = MiraiCode.deserializeFromMiraiCode("[mirai:atall]"); ``` -> 回到 [目录](#目录) +--------- + +到这里，你已经完成了 Mirai 所有文档的阅读。现在你已经熟悉了 Mirai，并可以开始使用了。 + +你可以首先构造 Bot，登录，然后从监听事件起开始创建你的机器人，或从 Bot 获取到指定群主动发送消息。在使用中遇到问题可以参考 Mirai 源码内注释，该注释会包含更多实践上的帮助。 + +如果你仍然对 Mirai 架构有不明确的地方，欢迎在 [#848](https://github.com/mamoe/mirai/discussions/848) 提出建议，或者直接在 PR 提交你的修改。 > 回到 [目录](#目录) > -> [回到 Mirai 文档索引](README.md) +> [回到 Mirai 文档索引](README.md#mirai-core-api-文档) diff --git a/docs/Preparations.md b/docs/Preparations.md index 58138867b26..2245056afe7 100644 --- a/docs/Preparations.md +++ b/docs/Preparations.md @@ -29,10 +29,15 @@ *如果你不知道这俩是什么，都安装就对了。* -## 前置知识 +### Kotlin Kotlin 是[让开发人员更快乐的一门现代编程语言](https://www.kotlincn.net/)，由 [IntelliJ IDEA](https://www.jetbrains.com/idea/) 的开发公司 [JetBrains](https://www.jetbrains.com/) 维护，被 Google 推举为 Android 首选编程语言。 使用 Mirai 是一个不错的学习 Kotlin 机会，使用者有兴趣可以在 [官方中文文档](https://www.kotlincn.net/docs/reference/) 学习 Kotlin。 -Java 开发者如果只希望使用 Mirai 而不学习 Kotlin，也请阅读 [Kotlin 定义对应的 Java 定义](KotlinAndJava.md)（5 分钟）。 \ No newline at end of file +Java 开发者如果只希望使用 Mirai 而不学习 Kotlin，也请阅读 [Kotlin 定义对应的 Java 定义](KotlinAndJava.md)（5 分钟）。 + + +---- + +> [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index f1d8499ec0c..70736cc7f23 100644 --- a/docs/README.md +++ b/docs/README.md @@ -59,7 +59,7 @@ **Mirai 文档没有废话，请务必仔细阅读每一个字。仔细阅读文档花费的 1 分钟可能相当于不阅读文档而自己摸索解决办法的 1 小时。** 1. [JVM 环境和开发准备工作（2 分钟）](Preparations.md#mirai---preparations) -2. 配置项目依赖 +2. **配置项目依赖** - 要把 mirai-core 嵌入一个应用使用，请阅读 [配置项目依赖](ConfiguringProjects.md)。 - 要为 [`mirai-console`] 框架开发插件，请阅读 [mirai-console 的配置插件项目](https://github.com/mamoe/mirai-console/blob/master/docs/ConfiguringProjects.md)。 3. 阅读 API 文档（见下文） @@ -71,7 +71,11 @@ ### mirai-core API 文档 +> *适用于 2.x 版本* + - [Bots](Bots.md) - [Contacts](Contacts.md) - [Events](Events.md) - [Messages](Messages.md) + +> 希望改进文档? 请在 [#848](https://github.com/mamoe/mirai/discussions/848) 提出建议 \ No newline at end of file diff --git a/docs/mirai-ecology.md b/docs/mirai-ecology.md index f836fde30f0..2d8b63a9748 100644 --- a/docs/mirai-ecology.md +++ b/docs/mirai-ecology.md @@ -129,8 +129,8 @@ mirai-console-loader 应运而生，它的工作就是简化 console 启动流 ------ -以上就是整个 Mirai 生态的概览，如有疏漏或错误，欢迎提出 Issue 修正。 +本文作者 [@StageGuard](https://github.com/StageGuard)。如有疏漏或错误，欢迎[提出 Issue](https://github.com/mamoe/mirai/issues/new) 修正。 实体关系图采用 [Mermaid](https://github.com/mermaid-js/mermaid) 绘制。 -> [回到 Mirai 文档索引](README.md) \ No newline at end of file +> [回到 Mirai 文档索引](README.md#mirai-core-api-文档) \ No newline at end of file