富媒体上传

富媒体（图片/视频/语音/文件）的发送统一封装在 Bngeuit 门面：ByUrl（公网 URL）与 ByFile（本地文件）两种方式，命名对称成对。

与「素材管理」的区别

本页讲的是把媒体作为消息附件发送（msg_type=7）。若目标是让图片出现在 Markdown 正文里，用素材管理接口预上传拿 qqbot-media:// 链接，见 素材管理。

FileType

枚举值	数值	说明
IMAGE	1	图片（png/jpg，软限制 20MB）
VIDEO	2	视频（mp4，软限制 30MB）
VOICE	3	语音（silk，软限制 20MB）
FILE	4	文件（任意格式，软限制 200MB）

方式一：公网 URL（ByUrl）

传入一个公网可访问的 URL，内部自动完成上传 → 发送：

import cn.org.bukkit.bngeuit.Bngeuit;

// 群聊
Bngeuit.sendGroupImageByUrl(groupOpenid, "https://example.com/img.png");
Bngeuit.sendGroupVideoByUrl(groupOpenid, "https://example.com/video.mp4");

// 私聊
Bngeuit.sendC2CVoiceByUrl(openid, "https://example.com/voice.silk");
Bngeuit.sendC2CFileByUrl(openid, "https://example.com/file.rar");

方式二：本地文件（ByFile）

传入本地 File 对象，内部自动分片上传 → 发送（预上传 → 逐片 PUT → 分片确认 → 合并），无需关心分片细节：

import cn.org.bukkit.bngeuit.Bngeuit;

// 群聊
Bngeuit.sendGroupImageByFile(groupOpenid, new File("path/to/img.png"));
Bngeuit.sendGroupVideoByFile(groupOpenid, new File("path/to/video.mp4"));

// 私聊
Bngeuit.sendC2CVoiceByFile(openid, new File("path/to/voice.silk"));
Bngeuit.sendC2CFileByFile(openid, new File("path/to/file.rar"));

便捷助手

Bngeuit.getMediaFile(String fileName) 从启动时扫描 media_files 建立的缓存中取 File（键为相对路径，支持子目录如 sub/a.png），可直接喂给 ByFile 方法：

Bngeuit.sendGroupImageByFile(groupOpenid, Bngeuit.getMediaFile("测试图片.jpg"));

该方法只查缓存，不校验文件当前是否存在；启动后新放进 media_files 的文件不会被收录，需要重启框架。

高级：只上传不发送

需要分步控制时，先上传拿到 file_info，再用它发送：

import cn.org.bukkit.bngeuit.dto.message.upload.FileType;
import cn.org.bukkit.bngeuit.dto.message.upload.UploadResponse;

var api = Bngeuit.api();

// URL 上传（单次请求）
UploadResponse r = api.uploadGroupFile(groupOpenid, FileType.IMAGE, url, false);

// 本地文件分片上传（自动走完分片全流程）
UploadResponse r2 = api.uploadGroupFileByFile(groupOpenid, FileType.IMAGE, new File("img.png"));

// 用上传结果直接发送，跳过再次上传
api.sendGroupMedia(groupOpenid, r2.fileInfo());

分片上传事件

本地分片上传会触发可取消的发送事件，可在各步骤拦截：

步骤	事件
预上传前	GroupUploadPrepareEvent / C2CUploadPrepareEvent
每片确认前	GroupUploadPartFinishEvent / C2CUploadPartFinishEvent
合并前	GroupUploadChunkedEvent / C2CUploadChunkedEvent（携带 File 对象，getFile() / getFileName() / getFilePath()）

取消事件则对应 API 调用被跳过并返回 null。