Communitygithub.com

discord-components-v2

使用 discord.js(v14.19+)的 Components V2 创建漂亮的 Discord 机器人消息。适用于构建或重构需要现代布局、容器、分区、文字显示、按钮、选择菜单、媒体画廊的 Discord 机器人,或当用户提到 Components V2、显示组件、IS_COMPONENTS_V2 或希望使用没有经典嵌入的精美交互式消息时。

discord-components-v2 是什么?

该技能提供了使用 discord.js(v14.19+)的 Components V2 功能创建现代 Discord 消息布局的全面指南。它详细解释了所有核心构建器,包括 ContainerBuilder、TextDisplayBuilder、SectionBuilder、SeparatorBuilder、MediaGalleryBuilder 和 FileBuilder,以及如何正确设置 `MessageFlags.IsComponentsV2` 标志。该技能强调了关键规则,例如在 V2 消息中不能使用 `content` 或 `embeds`,所有文本都必须位于 TextDisplay 中,并且每个 Section 必须恰好有一个配件(缩略图或按钮)。它还包含了限制表,详细说明了组件数量(40个)、文本字符(4000个)以及其他约束。最后,该技能提供了一系列成熟的布局示例,如信息卡片、功能亮点、仪表盘、图像主导的公告、临时确认/错误消息和确认提示,使开发者能够快速构建美观且功能丰富的 Discord 机器人界面。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Dqrshan/discord-components-v2-skill/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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:

构建器默认值设置器
UserSelectMenuBuildersetDefaultUsers(...)
RoleSelectMenuBuildersetDefaultRoles(...)
ChannelSelectMenuBuildersetDefaultChannels(...)、setChannelTypes(...)
MentionableSelectMenuBuildersetDefaultValues(...)

选择框在 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

…

[为翻译截断]

相关技能