消息段

Seg 模块提供类型安全的消息段构造器，用于构建复杂的 QQ 消息内容。

基本使用

import { Seg } from '@aemeath-projects/napcat'

// 发送组合消息
await msg.sendGroupMsg(groupId, [
  Seg.at(123456),
  Seg.text(' 你好！'),
  Seg.image('http://example.com/img.png'),
])

消息段类型

方法	说明
`Seg.text(text: string)`	纯文本
`Seg.face(id: number)`	QQ 表情
`Seg.image(file: string, opts?)`	图片
`Seg.record(file: string, opts?)`	语音
`Seg.video(file: string, opts?)`	视频
`Seg.at(qq: number \| 'all')`	@某人（传 `'all'` @全体成员）
`Seg.reply(id: number)`	引用回复
`Seg.forward(id: string)`	合并转发
`Seg.mface(opts)`	商城表情（NapCat 扩展）
`Seg.dice()`	骰子
`Seg.rps()`	猜拳
`Seg.poke(type: string, id: string)`	戳一戳
`Seg.file(file: string, opts?)`	文件
`Seg.json(data: string)`	JSON 富文本
`Seg.music(type: string, id: string)`	平台音乐分享
`Seg.customMusic(url, audio, title, singer?, image?)`	自定义音乐分享
`Seg.node(content, userId?, nickname?)`	转发消息节点
`Seg.contact(type: 'qq' \| 'group', id: string)`	联系人名片
`Seg.markdown(content: string)`	Markdown
`Seg.share(url, title, opts?)`	链接分享
`Seg.location(lat, lon, opts?)`	位置

参数说明

Seg.text

纯文本消息段，最简单的消息类型。

参数	类型	必填	说明
`text`	`string`	是	文本内容

Seg.face

QQ 表情消息段。

参数	类型	必填	说明
`id`	`number`	是	QQ 表情 ID

Seg.image

图片消息段。file 支持本地路径、网络 URL、base64 编码。

参数	类型	必填	说明
`file`	`string`	是	图片文件路径/URL/base64
`opts.name`	`string`	否	图片名称
`opts.summary`	`string`	否	图片摘要
`opts.sub_type`	`number`	否	图片子类型
`opts.file_id`	`string`	否	文件 ID（群文件复用）
`opts.url`	`string`	否	图片 URL
`opts.path`	`string`	否	本地路径
`opts.file_size`	`number`	否	文件大小
`opts.file_unique`	`string`	否	文件唯一标识

Seg.record

语音消息段。

参数	类型	必填	说明
`file`	`string`	是	语音文件路径/URL/base64
`opts.name`	`string`	否	文件名称
`opts.file_id`	`string`	否	文件 ID
`opts.url`	`string`	否	语音 URL
`opts.path`	`string`	否	本地路径
`opts.file_size`	`number`	否	文件大小
`opts.file_unique`	`string`	否	文件唯一标识

Seg.video

视频消息段。

参数	类型	必填	说明
`file`	`string`	是	视频文件路径/URL/base64
`opts.name`	`string`	否	文件名称
`opts.thumb`	`string`	否	缩略图
`opts.file_id`	`string`	否	文件 ID
`opts.url`	`string`	否	视频 URL
`opts.path`	`string`	否	本地路径
`opts.file_size`	`number`	否	文件大小
`opts.file_unique`	`string`	否	文件唯一标识

Seg.at

@提及消息段。

参数	类型	必填	说明
`qq`	`number \| 'all'`	是	QQ 号（数字自动转字符串），传 `'all'` 表示 @全体成员

Seg.reply

引用回复消息段。

参数	类型	必填	说明
`id`	`number`	是	被回复消息的 message_id

Seg.forward

合并转发消息段。

参数	类型	必填	说明
`id`	`string`	是	合并转发 ID（通过 getForwardMsg 获取）

Seg.mface

商城表情消息段（NapCat 扩展）。

参数	类型	必填	说明
`opts.emoji_id`	`string`	否	表情 ID
`opts.emoji_package_id`	`string`	否	表情包 ID
`opts.key`	`string`	否	表情 key
`opts.summary`	`string`	否	表情摘要

Seg.dice

骰子消息段，无参数，随机生成点数。

Seg.rps

猜拳消息段，无参数，随机生成石头剪刀布。

Seg.poke

戳一戳消息段。

参数	类型	必填	说明
`type`	`string`	是	戳一戳类型
`id`	`string`	是	戳一戳 ID

Seg.file

文件消息段。

参数	类型	必填	说明
`file`	`string`	是	文件路径/URL
`opts.name`	`string`	否	文件名称
`opts.file_id`	`string`	否	文件 ID
`opts.file_size`	`number`	否	文件大小
`opts.file_unique`	`string`	否	文件唯一标识
`opts.path`	`string`	否	本地路径
`opts.url`	`string`	否	文件 URL

Seg.json

JSON 富文本消息段。

参数	类型	必填	说明
`data`	`string`	是	JSON 字符串

Seg.music

平台音乐分享消息段。

参数	类型	必填	说明
`type`	`string`	是	音乐平台类型：`qq`、`163`、`kugou`、`kuwo`、`migu`
`id`	`string`	是	音乐 ID

Seg.customMusic

自定义音乐分享消息段。

参数	类型	必填	说明
`url`	`string`	是	跳转链接
`audio`	`string`	是	音乐文件 URL
`title`	`string`	是	标题
`singer`	`string`	否	歌手
`image`	`string`	否	封面图片 URL

Seg.node

转发消息节点（用于构建合并转发消息）。

参数	类型	必填	说明
`content`	`MessageSegment[]`	是	消息段数组
`userId`	`number`	否	发送者 QQ
`nickname`	`string`	否	发送者昵称

Seg.contact

联系人名片消息段。

参数	类型	必填	说明
`type`	`'qq' \| 'group'`	是	名片类型：QQ 好友或群聊
`id`	`string`	是	QQ 号或群号

Seg.markdown

Markdown 消息段。

参数	类型	必填	说明
`content`	`string`	是	Markdown 内容

链接分享消息段。

参数	类型	必填	说明
`url`	`string`	是	分享链接
`title`	`string`	是	标题
`opts.content`	`string`	否	内容描述
`opts.image`	`string`	否	缩略图 URL

Seg.location

位置消息段。

参数	类型	必填	说明
`lat`	`number`	是	纬度
`lon`	`number`	是	经度
`opts.title`	`string`	否	位置标题
`opts.content`	`string`	否	位置描述

完整示例

import { Seg } from '@aemeath-projects/napcat'

// 组合消息：@某人 + 文本 + 图片
const segments = [
  Seg.at(123456789),
  Seg.text(' 这是一张图片：'),
  Seg.image('https://example.com/image.png', { summary: '示例图片' }),
]

// 引用回复
const withReply = [
  Seg.reply(12345),
  Seg.text('已收到您的消息'),
]

// 构建合并转发节点
const forwardNodes = [
  Seg.node([Seg.text('第一条消息')], 10001, '用户A'),
  Seg.node([Seg.text('第二条消息')], 10002, '用户B'),
]

// 音乐分享
Seg.music('163', '123456')        // 网易云音乐
Seg.customMusic('https://...', 'https://.../audio.mp3', '我的歌', '歌手名')

// 其他
Seg.dice()                    // 骰子
Seg.rps()                     // 猜拳
Seg.contact('qq', '123456')   // 联系人名片
Seg.location(39.9, 116.4, { title: '北京', content: '天安门' })

消息段 ​

基本使用 ​

消息段类型 ​

参数说明 ​

Seg.text ​

Seg.face ​

Seg.image ​

Seg.record ​

Seg.video ​

Seg.at ​

Seg.reply ​

Seg.forward ​

Seg.mface ​

Seg.dice ​

Seg.rps ​

Seg.poke ​

Seg.file ​

Seg.json ​

Seg.music ​

Seg.customMusic ​

Seg.node ​

Seg.contact ​

Seg.markdown ​

Seg.share ​

Seg.location ​

完整示例 ​

消息段