主要 API 及其使用
约 1794 字大约 6 分钟
2025-02-09
发送消息
有关函数原型
注意
对于 markdown 消息的支持不稳定, 请谨慎使用.
能够发送消息的函数一共有四个, 分别是:
BotAPI.post_group_msg()BotAPI.post_private_msg()GroupMessage.reply()PrivateMessage.reply()
它们都支持"MessageChain"和"命名参数"两种格式的消息.
xxx.reply() 是 BotAPI.post_group_msg() 的语法糖, 所支持的参数和 BotAPI.post_group_msg() 基本一致. 大部分时候使用 xxx.reply() 会更方便.
下文中, 发送私聊消息和发送群聊消息的唯一区别是 group_id 变为 user_id, 故不重复举例.
注意
再次提醒, BotAPI.post_xxx_msg() 和 xxx.reply() 是异步函数, 调用时应该 await xxx.reply() 或者 await BotAPI.post_xxx_msg(). 任何 xxx.reply() 或者 BotAPI.post_xxx_msg() 的调用都是错误的.
点击显示函数原型
class BotAPI:
async def post_group_msg(
self,
group_id: Union[int, str],
text: str = None,
face: int = None,
json: str = None,
markdown: str = None,
at: Union[int, str] = None,
reply: Union[int, str] = None,
music: Union[list, dict] = None,
dice: bool = False,
rps: bool = False,
image: str = None,
rtf: MessageChain = None,
):
"""
向对应群聊发送一条消息
:param group_id: 群号
:param text: 文本
:param face: 表情
:param json: JSON
:param markdown: Markdown
:param at: at
:param reply: 回复
:param music: 音乐
:param dice: 骰子
:param rps: 猜拳
:param image: 图片
:param rtf: 富文本(消息链)
:return: 发送群消息
"""
async def post_private_msg(
self,
user_id: Union[int, str],
...
):
"""
向对应的人发送一条消息
:param user_id: 聊天对象 QQ 号.
...
"""
"""
其它函数省略
"""
class GroupMessage:
async def reply(self, text: str = "", is_file: bool = False, **kwargs):
"""
在对应群聊中回复一条群聊消息
:param text: 文本信息
:param is_file: 是否为文件
:param kwargs: 其它参数, 参考 BotAPI.post_group_msg() 中除了 text, reply, group_id 之外的参数, 此外还有下面补充的参数
:param file: 所需发送的文件的路径
:param video: 所需发送的视频的路径
:param record: 所需发送的语音的路径
"""
if len(text): # 如果有文本, 把文本传入 kwargs
kwargs["text"] = text
if is_file: # 如果是文件, 则使用 post_group_file() 函数
return await self.api.post_group_file(self.group_id, **kwargs)
else:
return await self.api.post_group_msg(
self.group_id, reply=self.message_id, **kwargs
)
class PrivateMessage:
async def reply(self, text: str = "", is_file: bool = False, **kwargs):
"""
私聊回复对应的人一条消息, 参数同 GroupMessage.reply()
"""使用 MessageChain 构造并发送消息(推荐)
MessageChain 这个词是不是很熟悉呢?
没错, 就是从 mirai 处抄借鉴过来的.
导入 Message Chain 有关类
from ncatbot.core.element import (
MessageChain, # 消息链，用于组合多个消息元素
Text, # 文本消息
Reply, # 回复消息
At, # @某人
AtAll, # @全体成员
Dice, # 骰子
Face, # QQ表情
Image, # 图片
Json, # JSON消息
Music, # 音乐分享 (网易云, QQ 音乐等)
CustomMusic, # 自定义音乐分享
Record, # 语音
Rps, # 猜拳
Video, # 视频
File, # 文件（已弃用）
)当然, 你不需要导入所有类, 只需要导入你需要的类即可. 不过就算是笨蛋也知道 MessageChain 是必须的吧...
使用 MessageChain 构造消息
见下例:
# 构造消息链
@bot.group_event()
async def on_group_message(msg: GroupMessage):
if msg.raw_message == "测试":
message = MessageChain([
"喵喵喵~",
Text("你好"),
At(123456),
Image("meow.jpg"),
[
Face(123),
Image("https://example.com/meow.jpg"),
Reply(13579),
]
])
message += MessageChain(["咕咕咕"])
message = message + At(234567)
await bot.api.post_group_msg(group_id=123456, rtf=message)这里展示了 MessageChain 大部分常见的用法, 具体的:
列表化构造, 构造时传入一个列表, 列表中的元素是列表或者 Element 类. 列表至多嵌套一层.
通过
+运算符连接,MessageChain对可发送对象均可右加.单纯文本可以不使用
Element类, 直接传入字符串即可.
可发送对象: MessageChain, Element, str.
构造 Element
注意
当前版本中, Video, Record 两个类的支持可能存在问题, 建议使用上传文件的方式发送这两类消息.
Text: 传入一个字符串, 构造文本消息.Reply: 传入一个消息 ID, 指定回复消息, 多条Reply只生效第一条.At: 传入一个 QQ 号, 构造 @ 某人消息.AtAll: 构造 @ 全体消息.Dice: 构造一个骰子消息, 和表情一样, 不支持和其它元素混合发送.Face: 传入一个 QQ 表情 ID, 构造 QQ 表情消息.Image: 传入一个图片字符串, 构造图片消息, 图片支持:- 本地路径(只建议绝对路径)
- URL
- Base64 编码
Json: 传入一个 JSON 字符串, 构造 JSON 消息.Music: 传入一个平台音乐分享, 构造音乐分享消息, 不支持和其它元素混合发送:- type: 平台类型(qq/163/kugou/migu/kuwo)
- id: 音乐ID
CustomMusic: 自定义音乐, 使用字典格式, 需包含以下字段, 不支持和其它元素混合发送:- url: 跳转链接
- audio: 音频链接
- title: 标题
- image: 封面图 (可选)
- singer: 歌手名 (可选)
Record: 传入一个语音文件, 构造语音消息.Rps: 构造猜拳消息, 也和表情一样, 不支持和其它元素混合发送Video: 传入一个视频字符串, 构造视频消息, 支持:- 本地路径(只建议绝对路径)
- URL
File: 传入一个文件, 构造文件消息.（已弃用）- 本地路径(只建议绝对路径)
发送消息
函数参数中指定命名参数 rtf 为一个 MessageChain 实例即可.
await bot.api.post_group_msg(group_id=123456, rtf=message)
await msg.reply(rtf=message)使用命名参数构造消息(只需要发送简单消息时使用)
命名参数如下:
text: str: 文本消息.face: int: QQ 表情.json: str: JSON 消息.markdown: str: Markdown 消息.at: Union[int, str]: @ 某人.reply: Union[int, str]: 回复消息.music: Union[list, dict]: 音乐分享.dice: bool: 骰子.rps: bool: 猜拳.image: str: 图片, 支持类型同 MessageChain Image.
命名参数构造的消息不区分顺序, 一般只使用 at 消息和至多一个其它类型.
通过在函数中指定对应命名参数可以发送对应消息.
await bot.api.post_group_msg(group_id=123456, text="喵喵喵~", reply=13579)
await msg.reply(face=123, at=1234567)一般建议
- 无复杂顺序组合的文本采用普通参数发送.
- 有复杂顺序组合的消息采用消息链发送.
示例调用: bot.api.post_group_msg(123456789, "你好"): 发送一句 "你好".
示例调用: bot.api.post_group_msg(123456789, "你好呀", at=123456): 发送一句 "你好呀" 并 @ QQ 号为 123456 的用户.
示例调用: bot.api.post_group_msg(123456789, "你好呀", reply=13579): 向 id 为 13579 的消息回复 "你好呀".
示例调用: bot.api.post_group_msg(123456789, rtf=MessageChain([Text("你好")])): 发送一条消息链.
上传文件
函数原型
点击显示函数原型
async def post_private_file(
self,
user_id: Union[int, str],
image: str = None,
record: str = None,
video: str = None,
file: str = None,
markdown: str = None,
):
"""
:param user_id: QQ号
:param image: 图片
:param record: 语音
:param video: 视频
:param file: 文件
:param markdown: Markdown
:return: 发送私聊文件
"""
async def post_group_file(
self,
group_id: Union[int, str],
... # 同上
):
"""
:param group_id: 群号
:param ...: 同上
"""参数
image, video, record, file, markdown 五个参数只能选一个不为 None.
image: 支持本地路径(只建议绝对路径), URL, Base64 编码.video: 支持本地路径(只建议绝对路径), URL.record: 只支持本地路径(只建议绝对路径).file: 只支持本地路径(只建议绝对路径).markdown: 暂未支持.
版权所有
版权归属：huan-yp