Discord Components V2 (discord.js)
使用 Components V2 进行所有新的消息布局。经典的 content + embeds + 操作行仍然有效,但 V2 提供了完整的布局控制,是推荐的现代方法。
需要 discord.js ≥ 14.19(当前最新版本是 14.28.x)。始终设置标志。
关键规则
- 每条 V2 消息 必须 包含
flags: MessageFlags.IsComponentsV2(或MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral)。 - 一旦消息使用 V2 标志发送,在编辑时 不能 移除它。
- 设置标志后,你 不能 发送
content、embeds、poll或stickers。所有可见文本都位于TextDisplayBuilder中。 - 组件总数最多 40 个(嵌套计次)。所有 TextDisplay 的总字符数最多 4000 个。
- 附件不可见,除非通过 Thumbnail、MediaGallery 或 File 组件使用
attachment://filename引用。 - 顶层组件可以是:Container、TextDisplay、Section、Separator、MediaGallery、File、ActionRow。
- Container 不能嵌套在其他 Container 内部。
- 每个 Section 需要恰好一个配件(缩略图或按钮)。
限制
| 约束 | 限制 | 备注 |
|---|---|---|
| 每条消息的组件数 | 40 | 嵌套组件单独计数。 |
| 文本字符数 | 4,000 | 消息中每个 TextDisplay 的总和。 |
| 每个 ActionRow 的按钮数 | 5 | 或一个选择菜单,同一行中不能同时存在。 |
| 选择选项 | 25 | 每个选择菜单。 |
| MediaGallery 项目 | 10 | 每个画廊。 |
| Containers | 不可嵌套 | Container 不能包含另一个 Container。 |
| Sections | 每个 1 个配件 | 缩略图 或 按钮,不能同时存在,也不能没有。 |
| 附件 | 每条消息 10 个 | 每个都必须被引用才能可见。 |
当设置了 V2 标志时,经典的“每条消息 5 个 ActionRow”限制被替换为 40 组件的预算——ActionRow 仅仅是 40 个组件之一。
导入(典型)
const {
ContainerBuilder,
TextDisplayBuilder,
SectionBuilder,
SeparatorBuilder,
SeparatorSpacingSize,
MediaGalleryBuilder,
MediaGalleryItemBuilder,
FileBuilder,
ThumbnailBuilder,
ActionRowBuilder,
ButtonBuilder,
ButtonStyle,
StringSelectMenuBuilder,
UserSelectMenuBuilder,
RoleSelectMenuBuilder,
ChannelSelectMenuBuilder,
MentionableSelectMenuBuilder,
MessageFlags,
AttachmentBuilder,
} = require('discord.js');
标志
MessageFlags.IsComponentsV2 // V2 渲染必需
MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral // 临时回复
MessageFlags.IsComponentsV2 | MessageFlags.SuppressEmbeds
该标志是渲染 V2 组件所必需的,并且是 永久 的:一旦消息以该标志发送,编辑时不能移除。
核心构建器与模式
1. TextDisplay——所有文本都在这里
new TextDisplayBuilder().setContent('## 标题\n支持 **粗体**、*斜体*、`代码`、列表、提及、表情符号。')
仅支持标准 Discord Markdown:标题(#–###)、粗体、斜体、下划线、删除线、行内代码、代码块、剧透(||text||)、列表、引用、链接、时间戳、提及和表情符号。
使用 V2 时,消息上没有 content 字段——这个构建器是文本渲染的唯一位置。首选多个小的 TextDisplay 而不是一个大块,以获得更好的视觉效果。
2. Container——现代“嵌入”
const container = new ContainerBuilder()
.setAccentColor(0x5865F2) // 可选的左侧强调色(十六进制数字)
// .setSpoiler(true) // 模糊整个容器
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# 标题\n副标题或描述。'),
)
.addSeparatorComponents(
new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(/* 按钮或一个选择菜单 */),
);
完整方法集:addTextDisplayComponents、addSectionComponents、addSeparatorComponents、addActionRowComponents、addMediaGalleryComponents、addFileComponents、addComponents 和 setComponents([...]) 替换所有子组件。子组件的顺序保持不变,因此请按阅读顺序从上到下构建。
外观良好的强调色:Discord 模糊紫 0x5865F2、成功 0x57F287、危险 0xED4245、柔和灰色 0x99AAB5 或品牌颜色。省略强调色以获得干净平坦的外观。颜色必须是数字——'#5865F2' 和 'blurple' 会抛出错误。
3. Section——文本 + 配件(缩略图或按钮)
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**功能名称**'),
new TextDisplayBuilder().setContent('简短的支持文本。保持在 1–3 个 TextDisplay 内。'),
)
.setThumbnailAccessory(
new ThumbnailBuilder()
.setURL('https://example.com/icon.png') // 或 attachment://file.png
.setDescription('替代文本'),
)
// 或者
.setButtonAccessory(
new ButtonBuilder()
.setCustomId('action')
.setLabel('执行')
.setStyle(ButtonStyle.Primary),
);
当您想要在相关文本旁边显示缩略图或一个突出的按钮时,使用 Sections。永远不要让 Section 没有配件,也永远不要同时设置两个。
4. Separator——视觉呼吸空间
new SeparatorBuilder()
.setDivider(true) // 显示细线
.setSpacing(SeparatorSpacingSize.Small); // 或 Large
放置在逻辑组之间。对于大多数卡片,首选 Small + 分隔线;对于更大的视觉分隔,使用 Large。divider: false 配合 Large 间距会提供一个没有线条的空白间隙。
5. MediaGallery 与 File
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder()
.setURL('https://…') // 或 attachment://image.png
.setDescription('替代文本')
.setSpoiler(false),
// 最多 10 个项目
);
new FileBuilder().setURL('attachment://report.pdf'); // 还必须将文件传递给 `files`
上传但没有被 File、Thumbnail 或 MediaGallery 引用的文件保持不可见。
6. Thumbnail
new ThumbnailBuilder()
.setURL('https://…/icon.png') // 或 attachment://icon.png
.setDescription('替代文本')
.setSpoiler(false);
缩略图仅作为 Section 配件存在——它们不是顶层组件。
7. 交互式组件(在 ActionRows 内部)
- 每个 ActionRow 最多 5 个按钮 或 1 个选择菜单。
- 按钮:
ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium。 - 链接按钮需要
.setURL(),永远不要用 customId。高级按钮需要.setSKUId()。 - 始终为交互式组件提供一个唯一的、命名空间的
customId(例如ticket:close、poll:vote:yes)。自定义 ID 最多 100 个字符。
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('confirm').setLabel('确认').setStyle(ButtonStyle.Success),
new ButtonBuilder().setCustomId('cancel').setLabel('取消').setStyle(ButtonStyle.Secondary),
);
new ActionRowBuilder().addComponents(
new StringSelectMenuBuilder()
.setCustomId('choose-plan')
.setPlaceholder('选择一个计划…')
.addOptions(
{ label: '入门版', value: 'starter', description: '适用于个人' },
{ label: '专业版', value: 'pro', description: '适用于团队', emoji: '⭐' },
),
);
实体选择共享 setCustomId、setPlaceholder、setMinValues、setMaxValues、setDisabled:
| 构建器 | 默认值设置器 |
|---|---|
UserSelectMenuBuilder | setDefaultUsers(...) |
RoleSelectMenuBuilder | setDefaultRoles(...) |
ChannelSelectMenuBuilder | setDefaultChannels(...)、setChannelTypes(...) |
MentionableSelectMenuBuilder | setDefaultValues(...) |
选择框在 ActionRow 内部没有自己的标签——用户看到的是占位符。
8. 附件
const file = new AttachmentBuilder(buffer, { name: 'chart.png' });
// 在 MediaGallery、Thumbnail 或 File 中将其引用为 'attachment://chart.png'
附件的 name 必须与 attachment:// 匹配,包括大小写和扩展名。
发送与编辑
// 频道或交互
await channel.send({
components: [container], // 或 [text, separator, container, …]
flags: MessageFlags.IsComponentsV2,
files: [attachment], // 仅在引用时
allowedMentions: { parse: [] }, // 控制 TextDisplay 中的 @提及
});
// 临时回复
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral
// 编辑(标志是永久的)
await message.edit({
components: [newLayout],
// 不要尝试清除 V2 标志
});
所有构建器都实现了 .toJSON()。如果您持久化布局,存储 container.toJSON() 并将 JSON 传递回 components 以重建。
美观布局示例
干净的信息卡片
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# 服务器规则\n请仔细阅读。'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('1. 互相尊重\n2. 不要刷屏\n3. 遵守 Discord 服务条款'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('rules:accept').setLabel('我同意').setStyle(ButtonStyle.Success),
),
);
带缩略图的功能亮点
new ContainerBuilder()
.setAccentColor(0x57F287)
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## 新仪表盘'),
new TextDisplayBuilder().setContent('实时统计、角色管理和分析,集中在一处。'),
)
.setThumbnailAccessory(new ThumbnailBuilder().setURL('attachment://dashboard.png').setDescription('仪表盘预览')),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('dashboard:open').setLabel('打开仪表盘').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setLabel('更新日志').setURL('https://example.com/changelog').setStyle(ButtonStyle.Link),
),
);
将 files: [new AttachmentBuilder(buffer, { name: 'dashboard.png' })] 与组件一起传递。
多分区仪表盘风格消息
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(new TextDisplayBuilder().setContent('# 控制面板'))
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**状态**'),
new TextDisplayBuilder().setContent('🟢 所有系统正常运行\n👥 1,284 名成员\n📈 今日新增 42 人'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('status:refresh').setLabel('刷新').setStyle(ButtonStyle.Secondary),
),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(false).setSpacing(SeparatorSpacingSize.Large))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**操作**'),
new TextDisplayBuilder().setContent('管理、公告或配置服务器。'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('panel:settings').setLabel('设置').setStyle(ButtonStyle.Secondary),
),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('panel:announce').setLabel('公告').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setCustomId('panel:moderate').setLabel('管理').setStyle(ButtonStyle.Danger),
),
);
图片主导的公告
将文本保持在 2–3 个短行,以便图片保持焦点。横幅是一个 MediaGallery 项目——记得上传它。
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addMediaGalleryComponents(
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder().setURL('attachment://event-banner.png').setDescription('夏季活动横幅'),
),
)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# 夏季活动\n请在 **周五晚上 8 点** 加入我们观看开幕直播。'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('-# 参与是自愿的 · 时间以 UTC 显示'),
);
-# 是副文本——非常适合在不与标题竞争的情况下显示小字。
临时确认/错误
使用一个带有强调色 + 标题 + 消息的辅助函数,而不是编写两个布局。
const status = (type, text) => new ContainerBuilder()
.setAccentColor(type === 'error' ? 0xED4245 : 0x57F287)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent(`### ${type === 'error' ? '出了点问题' : '完成'}\n${text}`),
);
await interaction.reply({
components: [status('error', '您没有执行此操作的权限。')],
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
});
将临时回复保持在一个 Container 中——除非您需要一个后续按钮,否则不要使用分隔符或操作行。
确认提示
将破坏性操作放在最后,并将其样式设置为 Danger。
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## 删除 47 条消息?'),
new TextDisplayBuilder().setContent('此操作无法撤销。'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('purge:cancel').setLabel('取消').setStyle(ButtonStyle.Secondary),
new ButtonBuilder().setCustomId('purge:confirm').setLabel('删除').setStyle(ButtonStyle.Danger),
),
);
紧凑列表
对于变更日志、排行榜和状态列表:将标签加粗,每个条目保持在一行,使用 -# 表示元数据。
new Te
…
[为翻译截断]