Appearance
消息段 API
消息段（Segment）是 QQ 官方机器人 SDK 中用于构建富媒体消息的核心概念。通过组合不同类型的消息段，您可以发送包含文本、图片、视频、音频、表情等多种内容的复杂消息。
📋 目录
🎯 基础概念
消息段结构
每个消息段都遵循统一的数据结构：
typescript
interface MessageElem {
type: string // 消息段类型
[key: string]: any // 消息段数据
}发送消息类型
typescript
// 可发送的内容类型
type Sendable = string | MessageElem | (string | MessageElem)[]
// 可引用的消息（用于回复）
interface Quotable {
id?: string // 消息 ID
event_id?: string // 事件 ID
}📝 类型定义
可重复组合的消息元素
这些消息段可以在同一条消息中多次使用：
typescript
type RepeatableCombineElem =
| TextElem // 文本消息段
| FaceElem // 表情消息段
| LinkElem // 链接消息段（仅频道支持）
| AtElem // @提及消息段
| ButtonElem // 按钮消息段独立消息元素
这些消息段通常独立使用，不与其他同类型消息段组合：
typescript
type IndependentElem =
| ImageElem // 图片消息段
| VideoElem // 视频消息段
| AudioElem // 音频消息段
| MDElem // Markdown 消息段
| ArkElem // Ark 卡片消息段
| EmbedElem // Embed 嵌入消息段带回复的消息元素
typescript
type WithReply<T extends MessageElem> =
| T
| [T]
| [ReplyElem, T]
| [ReplyElem, ...RepeatableCombineElem[]]完整的 Sendable 定义
typescript
export type Sendable =
| string // 纯文本
| RepeatableCombineElem // 单个可重复元素
| (RepeatableCombineElem | string)[] // 可重复元素数组
| WithReply<IndependentElem> // 带回复的独立元素📐 组合规则
1. 可重复消息段
- ✅ 可以多个同时使用
- ✅ 可以与其他可重复消息段组合
- ✅ 可以添加回复引用
包括:
2. 独立消息段
- ⚠️ 每条消息只能包含一个
- ✅ 可以添加回复引用
- ⚠️ 不能与其他独立消息段组合
包括:
3. 特殊消息段
- 回复 (ReplyElem) - 只能与其他消息段组合使用
💡 使用示例
基础文本消息
typescript
// 发送纯文本
await bot.sendMessage(channelId, "这是一条文本消息")
// 发送文本消息段
await bot.sendMessage(channelId, {
type: "text",
text: "这是一条文本消息"
})组合消息
typescript
// 文本 + 表情 + @提及
await bot.sendMessage(channelId, [
{ type: "text", text: "你好 " },
{ type: "at", user_id: "123456" },
{ type: "text", text: " " },
{ type: "face", id: "1" }
])带回复的消息
typescript
// 回复 + 图片
await bot.sendMessage(channelId, [
{ type: "reply", message_id: "原消息ID" },
{ type: "image", file: "https://example.com/image.jpg" }
])服务模块使用
typescript
// 使用消息服务发送
const result = await bot.messageService.sendGuildMessage(
channelId,
[
{ type: "text", text: "查看这张图片：" },
{ type: "image", file: "local_image.jpg" }
]
)
// 使用消息构建器
const message = bot.messageBuilder
.text("欢迎 ")
.at(userId)
.text(" 加入频道！")
.face("1")
.build()
await bot.sendMessage(channelId, message)📚 消息段列表
| 类型 | 说明 | 可重复 | 支持平台 | 文档链接 |
|---|---|---|---|---|
| text | 文本消息 | ✅ | 全部 | 文档 |
| face | 表情消息 | ✅ | 全部 | 文档 |
| at | @提及消息 | ✅ | 全部 | 文档 |
| link | 链接消息 | ✅ | 频道 | 文档 |
| button | 按钮消息 | ✅ | 全部 | 文档 |
| image | 图片消息 | ❌ | 全部 | 文档 |
| video | 视频消息 | ❌ | 全部 | 文档 |
| audio | 音频消息 | ❌ | 全部 | 文档 |
| markdown | Markdown | ❌ | 频道 | 文档 |
| ark | Ark 卡片 | ❌ | 频道 | 文档 |
| embed | 嵌入消息 | ❌ | 频道 | 文档 |
| reply | 回复引用 | 特殊 | 全部 | 文档 |
⚡ 快速开始
1. 安装和导入
typescript
import { Bot, MessageBuilder } from 'qq-official-bot'
const bot = new Bot({
appid: 'your_app_id',
secret: 'your_secret',
mode: 'websocket'
})2. 发送基础消息
typescript
// 文本消息
await bot.sendMessage(channelId, "Hello, World!")
// 图片消息
await bot.sendMessage(channelId, {
type: "image",
file: "https://example.com/image.jpg"
})3. 发送复合消息
typescript
await bot.sendMessage(channelId, [
{ type: "text", text: "欢迎新成员 " },
{ type: "at", user_id: newMemberId },
{ type: "text", text: "！" },
{ type: "face", id: "1" }
])4. 使用消息构建器
typescript
const message = new MessageBuilder()
.text("这是一条包含多种元素的消息：")
.image("image.jpg")
.reply(sourceMessage)
.build()
await bot.sendMessage(channelId, message)🔧 高级功能
消息模板
typescript
// 创建消息模板
function createWelcomeMessage(userId: string, userName: string) {
return [
{ type: "text", text: `欢迎 ` },
{ type: "at", user_id: userId },
{ type: "text", text: ` (${userName}) 加入频道！` },
{ type: "face", id: "1" }
]
}
// 使用模板
await bot.sendMessage(channelId, createWelcomeMessage("123", "张三"))条件消息
typescript
function createConditionalMessage(hasImage: boolean, text: string, imageUrl?: string) {
const elements = [{ type: "text", text }]
if (hasImage && imageUrl) {
elements.push({ type: "image", file: imageUrl })
}
return elements
}🚨 注意事项
- 类型安全: 使用 TypeScript 时，IDE 会提供智能提示和类型检查
- 平台限制: 某些消息段仅在特定平台（如频道）中支持
- 组合规则: 严格遵循消息段组合规则，避免发送失败
- 文件处理: 图片、视频、音频支持本地文件、URL 和 Base64 格式
- 权限要求: 某些消息类型需要特定的机器人权限
📖 更多资源
💡 提示: 消息段设计遵循类型安全原则，能够在编译时发现大部分消息构建错误，提升开发体验。