From cc8856ed1ae1c77568f1b1bf9ef4f324cb6bbbf3 Mon Sep 17 00:00:00 2001 From: Him188 Date: Sat, 19 Dec 2020 11:15:57 +0800 Subject: [PATCH] Update docs --- CHANGELOG.md | 0 docs/ConfiguringProjects.md | 131 ++++++++++++ docs/Contacts.md | 1 + docs/CreatingBots.md | 40 ++++ docs/Evolution.md | 50 +++++ ...fication.md => MiraiCodeSepecification.md} | 4 +- docs/README.md | 19 ++ docs/guide_build_for_mirai.md | 186 ------------------ docs/guide_getting_started.md | 131 ------------ docs/guide_quick_start.md | 103 ---------- docs/guide_subscribe_events.md | 111 ----------- docs/mirai.md | 2 +- .../kotlin/message/code/CodableMessage.kt | 2 +- 13 files changed, 244 insertions(+), 536 deletions(-) delete mode 100644 CHANGELOG.md create mode 100644 docs/ConfiguringProjects.md create mode 100644 docs/Contacts.md create mode 100644 docs/CreatingBots.md create mode 100644 docs/Evolution.md rename docs/{mirai-code-specification.md => MiraiCodeSepecification.md} (95%) create mode 100644 docs/README.md delete mode 100644 docs/guide_build_for_mirai.md delete mode 100644 docs/guide_getting_started.md delete mode 100644 docs/guide_quick_start.md delete mode 100644 docs/guide_subscribe_events.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/ConfiguringProjects.md b/docs/ConfiguringProjects.md new file mode 100644 index 000000000..4880d1b4f --- /dev/null +++ b/docs/ConfiguringProjects.md @@ -0,0 +1,131 @@ +# Mirai - Configuring Projects + +本文介绍如何在一个项目中使用 mirai。 + +mirai 使用纯 Kotlin 开发，最低要求 `JDK 1.8`，`Kotlin 1.4`。 + +如果你熟悉构建工具，只需要添加 `jcenter` 仓库和依赖 `net.mamoe:mirai-core:VERSION` 即可而不需要继续阅读。下文将详细解释这些步骤。 + +本文提供如下三种配置方法，但更推荐使用 Gradle 构建。 + +- [A. 使用 Gradle](#a-使用-gradle) +- [B. 使用 Maven](#b-使用-maven) +- [C. 使用 IntelliJ](#c-使用-intellij) + +### 选择版本 +有关各类版本的区别，参考 [版本规范](Evolution.md#版本规范) + +[Version]: https://api.bintray.com/packages/him188moe/mirai/mirai-core/images/download.svg? +[Bintray Download]: https://bintray.com/him188moe/mirai/mirai-core/ + +| 版本类型 | 版本号 | +|:------:|:------------------------------:| +| 稳定 | 1.3.3 | +| 预览 | 2.0-M1 | +| 开发 | [![Version]][Bintray Download] | + + +## A. 使用 Gradle + +### Gradle Kotlin DSL + +在 `build.gradle.kts` 添加： + +```kotlin +plugins { + kotlin("jvm") version "1.4.21" +} + +repositories { + jcenter() +} + +dependencies { + api("net.mamoe", "mirai-core", "1.3.3") // 替换为你需要的版本号 +} +``` + +注意，必须添加 Kotlin 插件才能正确获取 mirai 软件包。 + +### Gradle Groovy DSL + +在 `build.gradle` 添加 + +```groovy +plugins { + id 'org.jetbrains.kotlin.jvm' version '1.4.21' +} + +repositories { + jcenter() +} + +dependencies { + api('net.mamoe', 'mirai-core', '1.3.3') // 替换为你需要的版本号 +} +``` + + +## B. 使用 Maven + +在 `pom.xml` 中： + +### 1. 添加 jcenter 仓库 +```xml + + + jcenter + https://jcenter.bintray.com/ + + +``` + +### 2. 添加 mirai 依赖 + +```xml + + + net.mamoe + mirai-core + 1.3.3 + + +``` + +### 3. 添加 Kotlin 依赖 + +通常 mirai 可以直接使用。但 mirai 使用的 Kotlin 1.4 可能与你的项目使用的其他库依赖的 Kotlin 版本冲突，Maven 无法正确处理这种冲突。此时请手动添加 Kotlin 标准库依赖。 + +```xml + + 1.4.20 + +``` +```xml + + + org.jetbrains.kotlin + kotlin-stdlib-jdk8 + ${kotlin.version} + + +``` + +> 可以在 [Kotlin 官方文档](https://www.kotlincn=.net/docs/reference/using-maven.html) 获取更多有关配置 Kotlin 的信息。 + +## C. 使用 IntelliJ + +### 1. 创建项目 + +使用现有项目，或创建一个新项目（`File->New->Project`）或新模块（`File->New->Module`）。 + +### 2. 添加依赖 + +1. 进入 `Project Structure`（`File->Project Structure`，`Ctrl+Alt+Shift+S`） +2. 进入 `Libraries` +3. 找到 `+` 按钮，点击 `From Maven` +4. 输入 `net.mamoe:mirai-core:1.3.3`，勾选 `Sources` +5. 确认并等待下载 + + +> [回到 Mirai 文档索引](README.md) \ No newline at end of file diff --git a/docs/Contacts.md b/docs/Contacts.md new file mode 100644 index 000000000..ce0c6707f --- /dev/null +++ b/docs/Contacts.md @@ -0,0 +1 @@ +# Mirai - Contacts \ No newline at end of file diff --git a/docs/CreatingBots.md b/docs/CreatingBots.md new file mode 100644 index 000000000..6e5f29252 --- /dev/null +++ b/docs/CreatingBots.md @@ -0,0 +1,40 @@ +# Mirai - Creating Bots + +## 获取 `Bot` 实例 + +一个机器人被以 `Bot` 对象描述。mirai 的交互入口点是 `Bot`。`Bot` 只可通过 [`BotFactory`](../mirai-core-api/src/commonMain/kotlin/BotFactory.kt#L22-L87) 内的 `newBot` 方法获得： + +```kotlin +interface BotFactory { + fun newBot(qq: Long, password: String, configuration: BotConfiguration): Bot + fun newBot(qq: Long, password: String): Bot = newBot(qq, password, BotConfiguration.Default) + fun newBot(qq: Long, passwordMd5: ByteArray, configuration: BotConfiguration): Bot + fun newBot(qq: Long, passwordMd5: ByteArray): Bot = newBot(qq, passwordMd5, BotConfiguration.Default) + + companion object : BotFactory by BotFactoryImpl +} +``` + +通常的调用方法为： +``` +// Kotlin +val bot = BotFactory.newBot( ) + +// Java +Bot bot = BotFactory.INSTANCE.newBot( ); +``` + +### 获取当前所有 `Bot` 实例 +在登录后，`Bot` 实例会被自动记录。可在 `Bot.instances` 获取到当前在线的所有 `Bot` 列表。当 `Bot` 离线，其实例就会被删除。 + +## 登录 + +创建 `Bot` 后不会自动登录，需要手动调用其 `login()` 方法。在 Kotlin 还可以使用 `Bot.alsoLogin()` 扩展，相当于 `bot.apply { login() }` + +### 重新登录 + +可以再次调用 `Bot.login()` 以重新登录 `Bot`。这一般没有必要——`Bot` 运行时会自动与服务器同步事件（如群成员变化，好友数量变化）。 + + +> 下一步，[Contacts](Contacts.md) +> [回到 Mirai 文档索引](README.md) diff --git a/docs/Evolution.md b/docs/Evolution.md new file mode 100644 index 000000000..3f5aaaf8a --- /dev/null +++ b/docs/Evolution.md @@ -0,0 +1,50 @@ +# Mirai - Evolution + +### Mirai 演进 + +Mirai 是不断前进的库，将来必定会发生 API 弃用和重构。 +维护者会严谨地推进每一项修改，并提供迁移周期（至少 2 个次版本）。 + +### 版本规范 + +Mirai 的版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/#spec-item-9) 规范。 + +在日常开发中, Mirai 会以 `-dev-1`，`-dev-2` 等版本后缀发布开发预览版本。这些版本仅用于兼容性测试等目的，无稳定性保证。 + +在大版本开发过程中，Mirai 会以 `-M1`, `-M2` 等版本后缀发布里程碑预览版本。代表一系列功能的完成，但还不稳定。 +这些版本里新增的 API 仍可能还会在下一个 Milestone 版本变化，因此请按需使用。 + +在大版本即将发布前，Mirai 会以 `-RC` 版本后缀发布最终的预览版本。 +`RC` 表示新版本 API 已经确定，离稳定版发布只差最后的一些内部优化或 bug 修复。 + +### 版本选择 + +**稳定性**：稳定 (`x.y.z`) > 发布预览 (`-RC`) > 里程碑预览 (`-M`) > 开发 (`-dev`)。 + +| 目的 | 推荐至少更新到版本 | +|:------------------:|:--------------:| +| 生产环境 | `x.y.z` | +| 希望尽早体验稳定新特性 | `-RC` | +| 无论如何都想体验新特性 | `-M` | +| 为 Mirai 提交 PR | `-dev` | + +## 更新兼容性 + +对于 `x.y.z` 版本号: +- 当 `z` 增加时，只会有 bug 修复，和必要的新函数添加（为了解决某一个问题），不会有破坏性变化。 +- 当 `y` 增加时，可能有新 API 的引入，和旧 API 的弃用。但这些弃用会经过一个弃用周期后才被删除（隐藏）。向下兼容得到保证。 +- 当 `x` 增加时，任何 API 都可能会有变化。无兼容性保证。 + +## 弃用周期 + +一个计划被删除的 API，将会在下一个次版本开始经历弃用周期。 + +如一个 API 在 `1.1.0` 起被弃用，它首先会是 `WARNING` (使用时会得到一个编译警告）弃用级别。 +在 `1.2.0` 上升为 `ERROR`（使用时会得到一个编译错误）； +在 `1.3.0` 上升为 `HIDDEN`（使用者无法看到这些 API)。 + +`HIDDEN` 的 API 仍然会保留在代码中并正常编译，以提供二进制兼容性，直到下一个主版本更新。 + + + +> [回到 Mirai 文档索引](README.md) \ No newline at end of file diff --git a/docs/mirai-code-specification.md b/docs/MiraiCodeSepecification.md similarity index 95% rename from docs/mirai-code-specification.md rename to docs/MiraiCodeSepecification.md index 7cc07f7e6..db3e87d09 100644 --- a/docs/mirai-code-specification.md +++ b/docs/MiraiCodeSepecification.md @@ -4,12 +4,10 @@ ## mirai 码 mirai 的部分 [消息](../mirai-core-api/src/commonMain/kotlin/message/data/Message.kt) 可以表示为形如 `[mirai:atall]` 的字符串. -模块 `mirai-core` 包含消息到 mirai 码的单向转换; 模块 `mirai-serialization` 提供 mirai 码的解析. - -运行时: [mirai-serialization](../mirai-serialization/) ## 变更记录 - `1.1.0`: 引入 mirai 码于 `mirai-serialization` 模块 +- `1.2.0`: mirai 码集成到 mirai-core。不再需要 `mirai-serialization` 模块。 ## 格式 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..3ce271f80 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,19 @@ +# Mirai + +欢迎来到 mirai 文档。 + +## 生态 + +[Mirai 生态概览](mirai-ecology.md) + +## 配置项目 + +> 可以首先体验让机器人发送消息：在 IDE 克隆 [mirai-hello-world](https://github.com/project-mirai/mirai-hello-world) 并运行其中入口点。 + +要把 mirai 作为一个依赖库使用，请参考 [Configuring Projects](ConfiguringProjects.md)。 + +要使用 mirai-console 框架，请前往 [mirai-console](https://github.com/mamoe/mirai-console)。 + +## 开发 + +- [创建 Bot](CreatingBots.md) diff --git a/docs/guide_build_for_mirai.md b/docs/guide_build_for_mirai.md deleted file mode 100644 index 23a60607d..000000000 --- a/docs/guide_build_for_mirai.md +++ /dev/null @@ -1,186 +0,0 @@ -# Mirai Guide - Build For Mirai - -由于Mirai项目在快速推进中，因此内容时有变动，本文档的最后更新日期为```2020-02-29```，对应版本```0.23.0``` - -本页面采用Kotlin作为开发语言，**若你希望使用 Java 开发**, 请参阅: [mirai-japt](https://github.com/mamoe/mirai-japt) - -本页面是[Mirai Guide - Subscribe Events](/docs/guide_subscribe_events.md)的后续Guide - -## build.gradle - -我们首先来看一下完整的```build.gradle```文件 - -```groovy -plugins { - id 'java' - id 'org.jetbrains.kotlin.jvm' version '1.3.61' -} - -group 'test' -version '1.0-SNAPSHOT' - -sourceCompatibility = 1.8 - -repositories { - mavenCentral() - jcenter() -} - -dependencies { - implementation 'net.mamoe:mirai-core-qqandroid:0.19.1' - implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8" - testCompile group: 'junit', name: 'junit', version: '4.12' -} - -compileKotlin { - kotlinOptions.jvmTarget = "1.8" -} -compileTestKotlin { - kotlinOptions.jvmTarget = "1.8" -} -``` - -使用gradle直接打包，不会将依赖也打包进去 - -因此，我们引入一些插件进行打包 - -### ShadowJar - -shadowJar支持将依赖也打包到Jar内，下面介绍用法。 - -#### 1.buildscript - -首先声明buildScript - -```groovy -buildscript { - repositories { - jcenter() - } - dependencies { - classpath 'com.github.jengelman.gradle.plugins:shadow:5.2.0' - } -} -``` - -在plugin前加入以上语句 - - - -#### 2.在plugins中进行插件的使用 - -将原本的plugins - -```groovy -plugins { - id 'java' - id 'org.jetbrains.kotlin.jvm' version '1.3.61' -} -``` - -覆盖为 - -```groovy -plugins { - id 'java' - id 'org.jetbrains.kotlin.jvm' version '1.3.61' - id 'com.github.johnrengelman.shadow' version '5.2.0'//使用shadow对依赖进行打包 -} - -apply plugin: 'com.github.johnrengelman.shadow' -apply plugin: 'java' -``` - - - -#### 3.添加shadowJar - -在文件底部添加 - -```groovy -shadowJar { - // 生成包的命名规则： baseName-version-classifier.jar - manifest { - attributes( - 'Main-Class': 'net.mamoe.mirai.simpleloader.MyLoaderKt'//入口点 - ) - } - - // 将 build.gradle 打入到 jar 中, 方便查看依赖包版本 - from("./"){ - include 'build.gradle' - } -} -``` - - - -#### 4.运行build - -在IDEA中点击```ShadowJar```左侧的run按钮(绿色小三角)，build完成后在```build\libs```中找到jar - - - -至此，build.gradle内的内容是 - -```groovy -buildscript { - repositories { - jcenter() - } - dependencies { - classpath 'com.github.jengelman.gradle.plugins:shadow:5.2.0' - } -} - - -plugins { - id 'java' - id 'org.jetbrains.kotlin.jvm' version '1.3.61' - id 'com.github.johnrengelman.shadow' version '5.2.0'//使用shadow对依赖进行打包 -} - -apply plugin: 'com.github.johnrengelman.shadow' -apply plugin: 'java' - -group 'test' -version '1.0-SNAPSHOT' - -sourceCompatibility = 1.8 - - -repositories { - mavenCentral() - jcenter() -} - -dependencies { - implementation 'net.mamoe:mirai-core-qqandroid:0.23.0' - implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8" - testCompile group: 'junit', name: 'junit', version: '4.12' -} - - -compileKotlin { - kotlinOptions.jvmTarget = "1.8" -} -compileTestKotlin { - kotlinOptions.jvmTarget = "1.8" -} - -shadowJar { - // 生成包的命名规则： baseName-version-classifier.jar - manifest { - attributes( - 'Main-Class': 'net.mamoe.mirai.simpleloader.MyLoaderKt' - ) - } - - // 将 build.gradle 打入到 jar 中, 方便查看依赖包版本 - from("./"){ - include 'build.gradle' - } -} - -``` - diff --git a/docs/guide_getting_started.md b/docs/guide_getting_started.md deleted file mode 100644 index 3d07ef82f..000000000 --- a/docs/guide_getting_started.md +++ /dev/null @@ -1,131 +0,0 @@ -# Mirai Guide - Getting Started - -由于Mirai项目在快速推进中，因此内容时有变动，本文档的最后更新日期为```2020-04-01```，对应版本```0.31.4``` - -假如仅仅使用Mirai，不需要对整个项目进行Clone，只需在项目内添加Gradle Dependency或使用即可。 - -下面介绍详细的入门步骤。 - -本页采用Kotlin作为开发语言，**若你希望使用 Java 开发**, 请参阅: [mirai-japt](https://github.com/mamoe/mirai-japt) - - - -## 起步步骤 -通过编写Kotlin程序，以第三方库的形式调用```mirai-core```，并定义你的Mirai Bot行为。 - -假如已经对Gradle有一定了解，可跳过1，2 - -### 1 安装IDEA与JDK - -- JDK 要求6以上 - -### 2 新建Gradle项目 - -*使用gradle项目可能需要代理，在IDEA的```settings```->```proxy settings```中可以设置 - -- 在```File->new project```中选择```Gradle``` -- 在面板中的```Additional Libraries and Frameworks```中勾选```Java```以及```Kotlin/JVM``` -- 点击```next```，填入```GroupId```与```ArtifactId```(对于测试项目来说，可随意填写) -- 点击```next```，点击```Use default gradle wrapper(recommended)``` -- 创建项目完成 - -### 3 添加依赖 - -- 打开项目的```Project```面板，点击编辑```build.gradle``` - -- 首先添加repositories - - ```groovy - //添加jcenter仓库 - /* - repositories { - maven { url 'https://dl.bintray.com/kotlin/kotlin-eap' } - mavenCentral() - } - 原文内容，更新为下文 - */ - - repositories { - maven { url 'https://dl.bintray.com/kotlin/kotlin-eap' } - mavenCentral() - jcenter() - } - ``` - -- 添加依赖，将dependencies部分覆盖。 `mirai-core` 的最新版本为: [![Download](https://api.bintray.com/packages/him188moe/mirai/mirai-core/images/download.svg)](https://bintray.com/him188moe/mirai/mirai-core/) - - ```groovy - dependencies { - implementation 'net.mamoe:mirai-core-qqandroid:1.1-EA'//此处版本应替换为当前最新 - implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8" - testCompile group: 'junit', name: 'junit', version: '4.12' - } - ``` - -- 打开右侧Gradle面板，点击刷新按钮 -- 至此，依赖添加完成 - -### 4 Try Bot - -- 在src/main文件夹下新建文件夹，命名为```kotlin``` -- 在```kotlin```下新建包(在```kotlin```文件夹上右键-```New```-```Package```) 包名为```net.mamoe.mirai.simpleloader``` - -- 在包下新建kotlin文件```MyLoader.kt``` - -```kotlin -package net.mamoe.mirai.simpleloader - -import kotlinx.coroutines.* -import net.mamoe.mirai.Bot -import net.mamoe.mirai.alsoLogin -import net.mamoe.mirai.join -import net.mamoe.mirai.message.data.At -import net.mamoe.mirai.contact.Member -import net.mamoe.mirai.event.subscribeMessages - -suspend fun main() { - val qqId = 10000L//Bot的QQ号，需为Long类型，在结尾处添加大写L - val password = "your_password"//Bot的密码 - val miraiBot = Bot(qqId, password).alsoLogin()//新建Bot并登录 - miraiBot.subscribeMessages { - "你好" reply "你好!" - case("at me") { - reply(At(sender as Member) + " 给爷爬 ") - } - - (contains("舔") or contains("刘老板")) { - reply("刘老板太强了") - } - } - miraiBot.join() // 等待 Bot 离线, 避免主线程退出 -} -``` - -- 单击编辑器内第8行(```suspend fun main```)左侧的run按钮(绿色三角)，等待，MiraiBot成功登录。 -- 本例的功能中，在任意群内任意成员发送包含“舔”字或“刘老板”字样的消息，MiraiBot会回复“刘老板太强了” - - -至此，简单的入门已经结束，下面可根据不同的需求参阅wiki进行功能的添加。 - -下面，可以尝试对不同事件进行监听[Mirai Guide - Subscribe Events](/docs/guide_subscribe_events.md) - -### 此外，还可以使用Maven作为包管理工具 -本项目推荐使用gradle，因此不提供详细入门指导 - -```xml - - - jcenter - https://jcenter.bintray.com/ - - -``` -```xml - - - net.mamoe - mirai-core-qqandroid - 0.23.0 - - -``` diff --git a/docs/guide_quick_start.md b/docs/guide_quick_start.md deleted file mode 100644 index cc44d19ce..000000000 --- a/docs/guide_quick_start.md +++ /dev/null @@ -1,103 +0,0 @@ -# Mirai Guide - Quick Start - -由于 mirai 项目在快速推进中，因此内容时有变动，本文档的最后更新日期为```2020/6/22```，对应版本```1.0.2``` - -本文适用于对 Kotlin 较熟悉的开发者, -使用 mirai 作为第三方依赖库引用到任意一个 Kotlin, Java 或其他 JVM 平台的项目 - -**若你希望一份更基础的教程**, 请参阅: [mirai-guide-getting-started](guide_getting_started.md) - -## 构建需求 - -- JDK 6 或更高 - -## 获取 Demo -可在 [mirai-demos](https://github.com/mamoe/mirai-demos) 中获取已经配置好依赖的示例项目. - -## Quick Start - -请将 `VERSION` 替换为 `mirai-core` 的最新版本号(如 `1.0.4`): -[![Download](https://api.bintray.com/packages/him188moe/mirai/mirai-core/images/download.svg)](https://bintray.com/him188moe/mirai/mirai-core/) - -### 添加依赖 -可通过以下三种方法之一添加 mirai 依赖. - -#### Maven - -```xml - - - jcenter - https://jcenter.bintray.com/ - - -``` - -```xml - - - net.mamoe - mirai-core-qqandroid - 0.23.0 - - -``` - -#### Gradle (推荐) - -Mirai 只发布在 `jcenter`, 因此请确保添加 `jcenter()` 仓库： - -```kotlin -repositories{ - jcenter() -} -``` - -**注意：** -Mirai 核心由 API 模块（`mirai-core`）和协议模块组成。依赖协议模块时会自动依赖相应版本的 API 模块。 -请参照下文选择目标平台的依赖添加。 - -如果你只用 Java / Kotlin 或其他语言开发 JVM 平台应用，只需要添加下文第一条。 -如果你只开发 Android 应用，只需添加下文第三条。 - -**jvm** (JVM 平台源集) - -```kotlin -implementation("net.mamoe:mirai-core-qqandroid:VERSION") -``` - -**common** (Kotlin 多平台项目的通用源集) - -```kotlin -implementation("net.mamoe:mirai-core-qqandroid-common:VERSION") -``` - -**android** (Android 平台源集) -**注意**: 在 [KT-37152](https://youtrack.jetbrains.com/issue/KT-37152) 修复前, mirai 无法支持 Android 平台目标. -```kotlin -implementation("net.mamoe:mirai-core-qqandroid-android:VERSION") -``` - -#### 直接导入jar包 (不推荐) -下载已经编译好的 Jar 包, 并添加 Jar 依赖: -- [mirai-core](https://github.com/mamoe/mirai-repo/tree/master/shadow/mirai-core) -- [mirai-qqandroid](https://github.com/mamoe/mirai-repo/tree/master/shadow/mirai-core-qqandroid) - - -### 开始使用 - -```kotlin -val bot = Bot(qqId, password).alsoLogin() -bot.subscribeAlways { event -> - if (event.message.content.contains("你好")) { - reply("你好!") - } else if (event.message.content.contains("你好")) { - File("C:\\image.png").sendAsImage() - } -} - -bot.subscribeAlways { event -> - if (event.kind == BECOME_OPERATOR) - reply("${event.member.id} 成为了管理员") -} -``` diff --git a/docs/guide_subscribe_events.md b/docs/guide_subscribe_events.md deleted file mode 100644 index 40f8587a3..000000000 --- a/docs/guide_subscribe_events.md +++ /dev/null @@ -1,111 +0,0 @@ -# Mirai Guide - Subscribe Events - -由于Mirai项目在快速推进中，因此内容时有变动，本文档的最后更新日期为`2020-04-01`，对应版本`0.31.4` - -本页面采用Kotlin作为开发语言，**若你希望使用 Java 开发**, 请参阅: [mirai-japt](https://github.com/mamoe/mirai-japt) - -本页面是[Mirai Guide - Getting Started](/docs/guide_getting_started.md)的后续Guide - -## 消息事件-Message Event - -首先我们来回顾上一个Guide的源码 - -```kotlin -suspend fun main() { - val qqId = 10000L//Bot的QQ号，需为Long类型，在结尾处添加大写L - val password = "your_password"//Bot的密码 - val miraiBot = Bot(qqId, password).alsoLogin()//新建Bot并登录 - miraiBot.subscribeMessages { - "你好" reply "你好!" - case("at me") { - reply(sender.at() + " 给爷爬 ") - } - - (contains("舔") or contains("刘老板")) { - "刘老板太强了".reply() - } - } - miraiBot.join() // 等待 Bot 离线, 避免主线程退出 -} -``` - -在本例中，`miraiBot`是一个Bot对象，让其登录，然后对`Message Event`进行了监听。 - -对于`Message Event`，`Mirai`提供了较其他Event更强大的[MessageSubscribersBuilder](https://github.com/mamoe/mirai/wiki/mirai-core-api/src/commonMain/kotlin/event/MessageSubscribers.kt#L140)，本例也采用了[MessageSubscribersBuilder](https://github.com/mamoe/mirai/wiki/mirai-core-api/src/commonMain/kotlin/event/MessageSubscribers.kt#L140)。其他具体使用方法可以参考[Wiki:Message Event](https://github.com/mamoe/mirai/wiki/Development-Guide---Kotlin#Message-Event)部分。 - -## 事件-Event - -上一节中提到的`Message Event`仅仅是众多`Event`的这一种，其他`Event`有：群员加入群，离开群，私聊等等... - -具体事件文档暂不提供，可翻阅源码[**BotEvents.kt**](https://github.com/mamoe/mirai/blob/master/mirai-core-api/src/commonMain/kotlin/event/events/BotEvents.kt)，查看注释。当前事件仍在扩充中，可能有一定不足。 - -下面我们开始示例对一些事件进行监听。 - -## 尝试监听事件-Try Subscribing Events - -### 监听加群事件 - -在代码中的`miraiBot.join()`前添加 - -```kotlin -miraiBot.subscribeAlways { - it.group.sendMessage(PlainText("欢迎 ${it.member.nameCardOrNick} 加入本群！")) -} -``` - -本段语句监听了加入群的事件。 - -### 监听禁言事件 - -在代码中添加 - -```kotlin -miraiBot.subscribeAlways { - it.group.sendMessage(PlainText("恭喜老哥 ${it.member.nameCardOrNick} 喜提禁言套餐一份")) -} -``` - -在被禁言后，Bot将发送恭喜语句。 - -### 添加后的可执行代码 - -至此，当前的代码为 - -```kotlin -package net.mamoe.mirai.simpleloader - -import kotlinx.coroutines.* -import net.mamoe.mirai.Bot -import net.mamoe.mirai.alsoLogin -import net.mamoe.mirai.contact.nameCardOrNick -import net.mamoe.mirai.event.events.MemberJoinEvent -import net.mamoe.mirai.event.events.MemberMuteEvent -import net.mamoe.mirai.event.subscribeAlways -import net.mamoe.mirai.event.subscribeMessages -import net.mamoe.mirai.message.data.PlainText - -suspend fun main() { - val qqId = 10000L//Bot的QQ号，需为Long类型，在结尾处添加大写L - val password = "your_password"//Bot的密码 - val miraiBot = Bot(qqId, password).alsoLogin()//新建Bot并登录 - miraiBot.subscribeMessages { - "你好" reply "你好!" - case("at me") { - reply(sender.at() + " 给爷爬 ") - } - - (contains("舔") or contains("刘老板")) { - "刘老板太强了".reply() - } - } - miraiBot.subscribeAlways { - it.group.sendMessage(PlainText("欢迎 ${it.member.nameCardOrNick} 加入本群！")) - } - miraiBot.subscribeAlways { - it.group.sendMessage(PlainText("恭喜老哥 ${it.member.nameCardOrNick} 喜提禁言套餐一份")) - } - miraiBot.join() // 等待 Bot 离线, 避免主线程退出 -} -``` - -下面可以参阅[Mirai Guide - Build For Mirai](/docs/guide_build_for_mirai.md)，对你的Mirai应用进行打包 diff --git a/docs/mirai.md b/docs/mirai.md index 80691a490..5f174b869 100644 --- a/docs/mirai.md +++ b/docs/mirai.md @@ -26,7 +26,7 @@ mirai 项目整体由 核心 (`mirai-core`) 与 控制台(`mirai-console`) 组 `mirai-core` 设计为一个 **`支持库`**, 意味着它可以被独立依赖, 在任意项目中使用. 详见下文. -- `mirai-serialization` 依赖 `mirai-core`, 是 mirai-core 的序列化支持模块. 提供 `Message` 类型的序列化支持与相关 [mirai 码](mirai-code-specification.md) 支持. +- `mirai-serialization` 依赖 `mirai-core`, 是 mirai-core 的序列化支持模块. 提供 `Message` 类型的序列化支持与相关 [mirai 码](MiraiCodeSepecification.md) 支持. 此模块自 mirai `1.1.0` 起可用, 引用方法同 `mirai-core`. - [`mirai-console`](https://github.com/mamoe/mirai-console) 是基于 `mirai-core` 的, 支持插件加载, 指令系统, 和配置等的**控制台框架**. diff --git a/mirai-core-api/src/commonMain/kotlin/message/code/CodableMessage.kt b/mirai-core-api/src/commonMain/kotlin/message/code/CodableMessage.kt index b6acd2bef..3353f824e 100644 --- a/mirai-core-api/src/commonMain/kotlin/message/code/CodableMessage.kt +++ b/mirai-core-api/src/commonMain/kotlin/message/code/CodableMessage.kt @@ -18,7 +18,7 @@ import net.mamoe.mirai.message.data.* * 使用 `mirai-serialization` 中 `String.parseMiraiCode()` 转回 [Message]. * * ## 规范 - * 可在 [mirai-code-specification.md](https://github.com/mamoe/mirai/blob/dev/docs/mirai-code-specification.md) 查看 mirai 码规范. + * 可在 [MiraiCodeSepecification.md](https://github.com/mamoe/mirai/blob/dev/docs/MiraiCodeSepecification.md) 查看 mirai 码规范. * * @suppress 警告: 此 API 可能在任何时刻被改变 *