文本、Markdown 与按钮
文本
await ctx.reply('普通文本');
await ctx.replyText(`收到:${ctx.content}`);单条最多 2000 字。
Markdown
await ctx.replyMarkdown([
'## 查询结果',
'',
`**用户:** ${ctx.userName || '匿名'}`,
`**内容:** ${ctx.content}`,
'',
'> 数据仅供参考',
].join('\n'));支持标题、加粗、引用、列表、链接、图片和原生按钮。
图文一条发(图片内嵌)
图片直接写进 Markdown,就会和文字合成一条消息,不要先用 replyMarkdown 再补一条 replyImage(那是两条消息,还会多占一条被动回复额度):
await ctx.replyMarkdown([
'## 🛒 订单已创建',
`**订单号:** \`${orderNo}\``,
'',
'👇 长按识别或截图扫描下方二维码付款:',
'',
'',
].join('\n'));#240px #240px 是显示尺寸(可省略);图片必须是公网可访问的直链。
二维码图源要用国内可达的
api.qrserver.com 等境外图源在 QQ 客户端内经常加载不出来(QQ 客户端走自己的图片代理,拉不到境外站)。生成支付二维码这类强依赖场景,务必用国内可达的图源(例如平台托管的 https://track.zxiaolin.com/qr?size=250&data=<URL编码内容>,返回 250×250 PNG),不要让「二维码不显示」变成售后工单。
@ 某人
const at = ctx.userId ? `<qqbot-at-user id="${ctx.userId}" />` : '';
await ctx.replyMarkdown(`${at} 你好`);必须是 qqbot-at-user 标签。写成 <@openid> 只会显示成一串文字,不会真的 @ 到人—— 「已付款但没收到货」这类提醒一定要真 @,否则群里没人知道在说谁。
按钮
QQ 原生键盘结构:
const keyboard = {
content: {
rows: [
{
buttons: [
{
id: 'next',
render_data: { label: '下一页', visited_label: '下一页', style: 1 },
action: {
type: 2,
permission: { type: 2 },
data: '下页',
enter: true,
unsupported_tips: '请升级 QQ 后重试',
},
},
],
},
],
},
};
await ctx.replyMarkdown('### 列表\n点击下方按钮继续', keyboard);按钮类型
| action.type | 行为 | 用户插件入口 |
|---|---|---|
| 0 | 打开链接 | 无 |
| 1 | 回调 | onInteraction |
| 2 | 发送指令 | onMessage |
建议优先用 type=2,点击后作为普通消息进入 onMessage。
内联按钮写法(推荐模式)
键盘对象结构啰嗦,而且一旦按钮文案写死在代码里,机器人主人想改个措辞就得改代码。推荐把「文案 → 按令」声明成模板里的一行文本,发送前统一解析成键盘:
[[下一页 => 下页]] [[返回目录 => 菜单]]- 单独一行的
[[按钮文案 => 指令]]:点击后以用户身份发送该指令(等价type=2) - 单独一行的
[[按钮文案 => https://链接]]:点击直接打开链接(等价type=0) - 一行写多个
[[...]]排成同一行;每行最多 5 个按钮、最多 5 行(QQ 硬限制) - 按钮行不会出现在正文里;文案最长 12 字
可复用的解析函数(放进插件代码或模板帮助库):
const BTN_RE = /\[\[([^\[\]]+?)\]\]/g;
function linkBtn(label, url) {
return { render_data: { label, visited_label: label, style: 1 },
action: { type: 0, permission: { type: 2 }, data: url, enter: true, unsupported_tips: '请升级 QQ 后打开链接' } };
}
function cmdBtn(label, data) {
return { render_data: { label, visited_label: label, style: 1 },
action: { type: 2, permission: { type: 2 }, data, enter: true, unsupported_tips: '请升级 QQ 后重试' } };
}
/** 把正文里的按钮行拆出来,返回 { text, keyboard } */
function splitButtons(text) {
const rows = [], kept = [];
String(text ?? '').split('\n').forEach(line => {
const t = line.trim();
const specs = t.match(BTN_RE) || [];
if (!specs.length || t.replace(BTN_RE, '').trim()) { kept.push(line); return; } // 混排行不当按钮
const btns = specs.map(s => {
const inner = s.slice(2, -2);
const idx = inner.indexOf('=>');
if (idx < 0) return null;
const label = inner.slice(0, idx).trim().slice(0, 12);
const target = inner.slice(idx + 2).trim();
if (!label || !target) return null;
return /^https?:\/\//i.test(target) ? linkBtn(label, target) : cmdBtn(label, target.slice(0, 100));
}).filter(Boolean);
if (btns.length) rows.push(btns); else kept.push(line);
});
return {
text: kept.join('\n').replace(/\n{3,}/g, '\n\n'),
keyboard: rows.length ? { content: { rows: rows.slice(0, 5).map(r => ({ buttons: r.slice(0, 5) })) } } : undefined,
};
}用法:
const { text, keyboard } = splitButtons('### 商品列表\n点下面翻页\n\n[[下一页 => 下页]] [[回首页 => 菜单]]');
await ctx.replyMarkdown(text, keyboard);这样按钮文案放进 ctx.settings 的 textarea 字段,机器人主人改文案、换指令都不用动代码。注意按钮指令仍然只是「替用户发一条消息」,QQ 官方按钮不能弹输入框收集自由文本(邮箱、卡密这类要用户自己发消息,配一条指令如 邮箱 xxx@xx.com 处理)。
限制
- 每行最多 5 个按钮
- 最多 5 行
- 同一条消息每个插件最多 2 条回复,超出静默丢弃;QQ 总上限 5 条,所有插件共用
引用回复
ctx.reply 的第二个参数、ctx.replyMarkdown 的第三个参数都是布尔值 quote,控制这条回复是否以「引用触发消息」的形式发出:
await ctx.reply('查询结果如下', true); // 引用触发消息
await ctx.replyMarkdown('### 列表', keyboard, false); // 不引用
await ctx.reply('普通回复'); // 不传 → 沿用机器人全局引用开关- 不传
quote时,沿用机器人管理页的「引用回复」全局开关; - 传了布尔值则以插件本次调用为准,适合做配置项让机器人主人自己选(用
ctx.settings读取开关后透传); - 私聊场景没有引用效果,参数会被忽略。
// 把引用行为做成插件配置项
const quote = ctx.settings.quote_reply === true;
await ctx.replyMarkdown(result, keyboard, quote);主动 Markdown
await ctx.sendGroupMarkdown(groupId, markdown, keyboard);
await ctx.sendPrivateMarkdown(userId, markdown, keyboard);