mirror of
https://github.com/mamoe/mirai.git
synced 2024-12-28 17:40:09 +08:00
c03155af6d
* Review docs and improve readability * Update docs/Bots.md Co-authored-by: Karlatemp <karlatemp@vip.qq.com> * Update docs/Bots.md Co-authored-by: Karlatemp <karlatemp@vip.qq.com> * Update docs/Bots.md Co-authored-by: Karlatemp <karlatemp@vip.qq.com> * Fix doc * Fix doc * Clarify AnonymousMember and NormalMember * Fix typo * Add language type Co-authored-by: Karlatemp <karlatemp@vip.qq.com>
80 lines
7.7 KiB
Markdown
80 lines
7.7 KiB
Markdown
# Mirai - Contacts
|
||
|
||
[](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5cbmNsYXNzIEJvdCB7XG4gICAgK2ZyaWVuZHM6IENvbnRhY3RMaXN0XG4gICAgK2dyb3VwczogQ29udGFjdExpc3RcbiAgICArZ2V0RnJpZW5kKExvbmcpIEZyaWVuZD9cbiAgICArZ2V0RnJpZW5kT3JOdWxsKExvbmcpIEZyaWVuZFxuICAgICtnZXRHcm91cChMb25nKSBHcm91cD9cbiAgICArZ2V0R3JvdXBPckZhaWwoTG9uZykgR3JvdXBcbiAgICArbG9naW4oKVxuICAgICtjbG9zZSgpXG59XG5cbmNsYXNzIENvbnRhY3RPckJvdCB7XG4gICAgK2lkOiBJbnRcbiAgICArYXZhdGFyVXJsOiBTdHJpbmdcbn1cblxuY2xhc3MgVXNlck9yQm90IHtcbiAgICArbnVkZ2UoKSBOdWRnZVxufVxuXG5jbGFzcyBDb250YWN0IHtcbiAgICArYm90OiBCb3RcbiAgICArc2VuZE1lc3NhZ2UoTWVzc2FnZSkgTWVzc2FnZVJlY2VpcHRcbiAgICArc2VuZE1lc3NhZ2UoU3RyaW5nKSBNZXNzYWdlUmVjZWlwdFxuICAgICt1cGxvYWRJbWFnZShFeHRlcm5hbEltYWdlKSBJbWFnZVxufVxuXG5jbGFzcyBVc2VyIHtcbiAgICArbmljazogU3RyaW5nXG4gICAgK3JlbWFyazogU3RyaW5nXG4gICAgK3F1ZXJ5UHJvZmlsZSgpIFVzZXJQcm9maWxlXG59XG5cbmNsYXNzIEdyb3VwIHtcbiAgICArbWVtYmVyczogQ29udGFjdExpc3RcbiAgICArbmFtZTogU3RyaW5nXG4gICAgK3NldHRpbmdzOiBHcm91cFNldHRpbmdzXG4gICAgK293bmVyOiBOb3JtYWxNZW1iZXJcbiAgICArYm90TXV0ZVJlbWFpbmluZzogTG9uZ1xuICAgICtib3RQZXJtaXNzaW9uOiBNZW1iZXJQZXJtaXNzaW9uXG4gICAgK3F1aXQoKSBCb29sZWFuXG4gICAgK3VwbG9hZFZvaWNlKCkgVm9pY2Vcbn1cblxuY2xhc3MgTm9ybWFsTWVtYmVyIHtcbiAgICArbXV0ZSgpXG4gICAgK2tpY2soKVxufVxuXG5jbGFzcyBBbm9ueW1vdXNNZW1iZXIge1xuICAgICthbm9ueW1vdXNJZDogU3RyaW5nXG59XG5cbmNsYXNzIE1lbWJlciB7XG4gICAgK2dyb3VwOiBHcm91cFxufVxuXG5jbGFzcyBPdGhlckNsaWVudCB7XG4gICAgK2luZm9cbn1cblxuQ29udGFjdE9yQm90PHwtLUNvbnRhY3RcbkNvbnRhY3RPckJvdDx8LS1Vc2VyT3JCb3RcblxuVXNlck9yQm90PHwtLUJvdFxuVXNlck9yQm90PHwtLVVzZXJcblxuQ29udGFjdDx8LS1Vc2VyXG5Db250YWN0PHwtLUdyb3VwXG5Db250YWN0PHwtLU90aGVyQ2xpZW50XG5cblVzZXI8fC0tTWVtYmVyXG5Vc2VyPHwtLUZyaWVuZFxuXG5NZW1iZXI8fC0tTm9ybWFsTWVtYmVyXG5NZW1iZXI8fC0tQW5vbnltb3VzTWVtYmVyIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0)
|
||
|
||
| 类型 | 描述 | 最低支持的版本 |
|
||
|:-----------------:|:-------------------------------------------------|:-----------:|
|
||
| `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 |
|
||
| `NormalMember` | 普通群成员对象. | 2.0 |
|
||
| `AnonymousMember` | 匿名群成员对象. | 2.0 |
|
||
|
||
|
||
我们称 `Contact` 为 _联系人_，它表示一个 `Bot` 可以联系的对象。如上图所示，`Contact` 的子类不仅有好友和群成员，还包括群和其他客户端。因此请不要因“联系人”中的“人”就认为它只代表一个用户。
|
||
|
||
## 获取联系人对象
|
||
|
||
`Bot.getFriends()`，`Bot.getGroups()` 等方法可以获取到对象列表。
|
||
|
||
可通过 `Bot.getFriend`， `Bot.getGroup`，`Bot.getStranger` 以 QQ 号或群号主动获取某个对象。
|
||
|
||
可以通过事件被动获取 *（后文介绍）*。
|
||
|
||
## 联系人对象唯一且属于 Bot
|
||
|
||
每个联系人对象都属于一个 `Bot`。可以通过 `Contact.bot` 获取到它们所属的 `Bot`。
|
||
|
||
对于同一个 `Bot`，不会有 `id` 相同的两个 `Group` 对象。通过 `Bot.getGroup` 得到的和在群消息事件得到的相同 `id` 的 `Group` 对象是同一个。
|
||
|
||
若应用同时登录多个 `Bot`，不同 `Bot` 的 `id` 相同的 `Group` 也是互相独立的。
|
||
|
||
## 常用功能
|
||
|
||
基于面向对象的设计，可直接获取 `Contact` 的属性如 `nick`，`permission`。请在实践时在接口源码内查看更清晰的说明。
|
||
|
||
### 接收消息
|
||
|
||
消息通过事件被动接收。事件将在下一章节 [Events](Events.md) 讲解。
|
||
|
||
### 主动发送消息
|
||
|
||
获取到目标对象并调用 `Contact.sendMessage(message)`。如要向某个群发送消息，则需要对应的 `Group` 对象，并调用 `Group.sendMessage(message)`。
|
||
|
||
注意，由于对象代表意义不同，发送的消息类型也可能不同。`NormalMember` 是普通群成员，`NormalMember.sendMessage` 是对群成员发送临时会话消息，而 `Friend.sendMessage` 是发送好友消息。（备注：在实际情况下，如果机器人与群成员有好友关系，`NormalMember.sendMessage` 也会自动转换为发送好友消息，以保证消息送达）
|
||
|
||
### 联系其他客户端
|
||
|
||
一个 QQ 账号可以在多个客户端登录，mirai 支持向其他客户端收发消息. 其他客户端被抽象为 `OtherClient`。
|
||
|
||
可以通过 `Bot.getOtherClients()` 获取到所有在线的其他客户端列表，并使用 `OtherClient.sendMessage` 来发送消息，这与操作普通好友类似。
|
||
|
||
### 使用戳一戳
|
||
|
||
戳一戳的被动接收与消息的接收相同，也是以事件的形式（`NudgeEvent`）。
|
||
|
||
要发起戳一戳，使用 `Contact.nudge()` 创建一个戳一戳动作（`Nudge`）然后将其发送到目标用户或群（`Nudge.sendTo`）。
|
||
|
||
### 操作群成员禁言和移除
|
||
|
||
使用 `Member.mute`, `Member.unmute`, `Member.kick`。
|
||
|
||
### 提及群成员
|
||
|
||
提及（`@`）群成员在 mirai 属于 _消息_ 的范畴。将在后面章节介绍。
|
||
|
||
### 其他功能
|
||
|
||
其他功能与上述类似，都作为成员方法位于目标对象中。未在成员方法或类注释中出现的其他功能即为目前还没有支持的功能。
|
||
|
||
----
|
||
|
||
> 下一步，[Events](Events.md)
|
||
>
|
||
> [回到 Mirai 文档索引](CoreAPI.md) |