主要 API 及其使用
约 2246 字大约 7 分钟
2025-02-09
发送简单消息
单纯的图片，@，回复，QQ 表情等，都叫简单消息。
纯文本消息
bot.api.post_group_msg_sync(group_id=123456, text="喵喵喵~") # 注意要用同步的方法
bot.api.post_group_msg_sync(group_id=123456, text="喵喵喵~[CQ:at,qq=123456], [CQ:face,id=123]")
bot.api.post_group_msg_sync(group_id=123456, text="[CQ:image,summary=[图片],url=https://foruda.gitee.com/images/1737622167903015509/9f9590eb_13790314.png]")没错，纯文本部分支持 CQ 码，支持以下 CQ 码：
[CQ:at,qq=123456]用于 @ 某人[CQ:face,id=123]用于发送 QQ 表情[CQ:image,summary=[图片],url=https://foruda.gitee.com/images/1737622167903015509/9f9590eb_13790314.png]用于发送图片[CQ:reply,id=123456]用于回复某条消息
命名参数发送消息
命名参数如下:
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)示例
示例调用: await bot.api.post_group_msg(123456789, "你好"): 发送一句 "你好".
示例调用: await bot.api.post_group_msg(123456789, "你好呀", at=123456): 发送一句 "你好呀" 并 @ QQ 号为 123456 的用户.
示例调用: await bot.api.post_group_msg(123456789, "你好呀", reply=13579): 向 id 为 13579 的消息回复 "你好呀".
示例调用: await bot.api.post_group_msg(123456789, image="https://example.com/meow.jpg"): 发送一张图片.
一般建议
- 无复杂顺序组合的文本采用本方式发送
- 有复杂顺序组合的消息采用消息链发送.
通过 MessageChain 发送消息
MessageChain 这个词是不是很熟悉呢?
没错, 就是从 mirai 处抄借鉴过来的.
导入 Message Chain 有关类
from ncatbot.core 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类, 直接传入字符串即可.CQ 码可以混入文本使用。
可发送对象: MessageChain, Element, str.
函数参数中指定命名参数 rtf 为一个 MessageChain 实例即可发送.
await bot.api.post_group_msg(group_id=123456, rtf=message)
await msg.reply(rtf=message)构造 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: 传入一个文件, 构造文件消息.（已弃用）- 本地路径(只建议绝对路径)
与消息有关的函数
能够发送消息的函数一共有三个, 分别是:
BotAPI.post_group_msg()BotAPI.post_private_msg()BaseMessage.reply()
BaseMessage.reply() 是对 BotAPI.post_xxx_msg() 的封装，支持的参数基本一致。
在群聊中，reply 方法会自动引用对应的 GroupMessage 消息，因此大多数情况下使用 BaseMessage.reply() 更为方便。
下文中, 发送私聊消息和发送群聊消息的唯一区别是 group_id 变为 user_id, 故不重复举例.
注意
再次提醒, BotAPI.post_xxx_msg() 和 BaseMessage.reply() 是异步函数。调用时要么 await，即 await BotAPI.post_xxx_msg()；要么用同步，即 BotAPI.post_xxx_msg_sync()。
函数原型位于其它 API 介绍。
上传文件
由于 NapCat 的一些原因, 发送视频建议以上传文件的形式进行.
通过文件消息发送
函数原型
参数
image, video, record, file, markdown 五个参数只能选一个不为 None.
image: 支持本地路径(只建议绝对路径), URL, Base64 编码.video: 支持本地路径(只建议绝对路径), URL.record: 支持本地路径(只建议绝对路径), URL.file: 支持本地路径(只建议绝对路径), URL.markdown: 暂未支持.
通过专用上传接口发送
一般来说私聊文件会直接发文件消息, 群文件需要指定上传到固定文件夹时可用这个接口.
专用接口为 upload_group_file.
函数原型
参数
group_id: 群号.file: 文件路径, 支持本地绝对路径或者 URL.name: 文件名.folder_id: 文件夹 ID, 参考这里可获取.
获取文件
文件消息中一般不提供文件的下载链接, 需要通过 get_file 方法传入 file_id 来请求下载链接, 也就是说, 获取文件的前提是获取 file_id。
通过 file_id 获取文件下载链接
使用 BotAPI.get_file 方法传入 file_id 即可获取消息的详细信息, 用法可以参考示例
返回值是一个 dict 类型, 示例如下:
result = {
"status": "ok",
"data": {
"file": "D:\\TencentFiles\\NapCat\\temp\\9f223e466 (1).txt", # 没啥用
"url": "D:\\TencentFiles\\NapCat\\temp\\9f223e466 (1).txt", # url 指示文件的获取方式，可能是一个本地路径，也可能是网络地址
"file_size": "35",
"file_name": "9f223e466.txt"
},
}注意
很多时候返回的 url 是一个本地路径，因为已经自动下载较小的文件到本地。如果 NapCat 和 NcatBot 不在同一台机器，还需要做额外的处理。
文件直接被发送
参考解析消息来获取一条消息中的 file_id.
已知文件位于某个群的群文件
通过 get_group_root_files 获取群文件根目录列表. 通过 get_group_files_by_folder 获取某个目录的列表.
如果文件位于根目录, 那么 get_group_root_files 的返回值的 data 中会带有对应的 file_name 和 file_id. 如果文件位于某个子目录, 那么 get_group_files_by_folder 的返回值的 data 中会带有对应的 file_name 和 file_id.
不知道文件位于哪个目录时, 可以通过以上两个函数来遍历获取.
get_group_root_files
返回指定群聊, 群文件根目录下所有文件和目录的信息.
返回值示例（省略了部分不重要的数据，如果需要，请自行实验）:
result = {
"status": "ok",
"data": {
"files": [
{
"group_id": 0,
"file_id": "string",
"file_name": "string",
}
],
"folders": [
{
"group_id": 0,
"folder_id": "string",
"folder": "string",
"folder_name": "string",
"create_time": "string",
}
]
},
}get_group_files_by_folder
返回指定目录所有文件和目录的信息.
返回值示例:
{
"status": "ok",
"data": {
"files": [
{
"group_id": 0,
"file_id": "string",
"file_name": "string",
"size": 0,
}
],
"folders": [
{
"group_id": 0,
"folder_id": "string",
"folder": "string",
"folder_name": "string",
}
]
},
}示例
收到群文件时输出下载链接
@bot.group_event()
def on_group_msg(msg: GroupMessage):
message_segs = msg.message
for message_seg in message_segs:
if message_seg['type'] == "file":
file_id = message_seg["data"]["file_id"]
file_source = bot.api.get_file_sync(file_id)['data']['url']
print("文件的获取途径是:", file_source)如果需要获取的文件已经存在于本地, 则 file_source 是一个绝对路径(有时候会自动下载到本地, 所以有时候不主动下载也会返回路径)
版权所有
版权归属：huan-yp