Skip to content

文本、Markdown 与按钮 ​

文本 ​

js
await ctx.reply('普通文本');
await ctx.replyText(`收到:${ctx.content}`);

单条最多 2000 字。

Markdown ​

js
await ctx.replyMarkdown([
  '## 查询结果',
  '',
  `**用户:** ${ctx.userName || '匿名'}`,
  `**内容:** ${ctx.content}`,
  '',
  '> 数据仅供参考',
].join('\n'));

支持标题、加粗、引用、列表、链接、图片和原生按钮。

图文一条发(图片内嵌) ​

图片直接写进 Markdown,就会和文字合成一条消息,不要先用 replyMarkdown 再补一条 replyImage(那是两条消息,还会多占一条被动回复额度):

js
await ctx.replyMarkdown([
  '## 🛒 订单已创建',
  `**订单号:** \`${orderNo}\``,
  '',
  '👇 长按识别或截图扫描下方二维码付款:',
  '',
  '![支付二维码 #240px #240px](https://api.qrserver.com/v1/create-qr-code/?size=250x250&data=xxx)',
].join('\n'));

#240px #240px 是显示尺寸(可省略);图片必须是公网可访问的直链。

二维码图源要用国内可达的

api.qrserver.com 等境外图源在 QQ 客户端内经常加载不出来(QQ 客户端走自己的图片代理,拉不到境外站)。生成支付二维码这类强依赖场景,务必用国内可达的图源(例如平台托管的 https://track.zxiaolin.com/qr?size=250&data=<URL编码内容>,返回 250×250 PNG),不要让「二维码不显示」变成售后工单。

@ 某人 ​

js
const at = ctx.userId ? `<qqbot-at-user id="${ctx.userId}" />` : '';
await ctx.replyMarkdown(`${at} 你好`);

必须是 qqbot-at-user 标签。写成 <@openid> 只会显示成一串文字,不会真的 @ 到人—— 「已付款但没收到货」这类提醒一定要真 @,否则群里没人知道在说谁。

按钮 ​

QQ 原生键盘结构:

js
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。

内联按钮写法(推荐模式) ​

键盘对象结构啰嗦,而且一旦按钮文案写死在代码里,机器人主人想改个措辞就得改代码。推荐把「文案 → 按令」声明成模板里的一行文本,发送前统一解析成键盘:

text
[[下一页 => 下页]] [[返回目录 => 菜单]]
  • 单独一行的 [[按钮文案 => 指令]]:点击后以用户身份发送该指令(等价 type=2)
  • 单独一行的 [[按钮文案 => https://链接]]:点击直接打开链接(等价 type=0)
  • 一行写多个 [[...]] 排成同一行;每行最多 5 个按钮、最多 5 行(QQ 硬限制)
  • 按钮行不会出现在正文里;文案最长 12 字

可复用的解析函数(放进插件代码或模板帮助库):

js
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,
  };
}

用法:

js
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,控制这条回复是否以「引用触发消息」的形式发出:

js
await ctx.reply('查询结果如下', true);                 // 引用触发消息
await ctx.replyMarkdown('### 列表', keyboard, false);  // 不引用
await ctx.reply('普通回复');                            // 不传 → 沿用机器人全局引用开关
  • 不传 quote 时,沿用机器人管理页的「引用回复」全局开关;
  • 传了布尔值则以插件本次调用为准,适合做配置项让机器人主人自己选(用 ctx.settings 读取开关后透传);
  • 私聊场景没有引用效果,参数会被忽略。
js
// 把引用行为做成插件配置项
const quote = ctx.settings.quote_reply === true;
await ctx.replyMarkdown(result, keyboard, quote);

主动 Markdown ​

js
await ctx.sendGroupMarkdown(groupId, markdown, keyboard);
await ctx.sendPrivateMarkdown(userId, markdown, keyboard);

薇薇官机平台 · ZL 系列插件