Communitygithub.com

discord-components-v2

使用 discord.js (v14.19+) 的 Components V2 建立美觀的 Discord 機器人訊息。適合建置或重構需要現代版面、容器、區塊、文字顯示、按鈕、選單或媒體藝廊的 Discord 機器人,或當使用者提及 Components V2、顯示元件、IS_COMPONENTS_V2,或希望使用拋光互動訊息而非傳統嵌入時使用。

discord-components-v2 是什麼?

此技能提供使用 Discord 的 Components V2 系統與 discord.js (v14.19+) 來建置機器人訊息的完整指引。Components V2 是 Discord 推薦的現代方法,提供對版面配置的全面控制,取代傳統的 `content` + `embeds` + ActionRow 模式。此技能涵蓋所有核心建構器,包括 ContainerBuilder、TextDisplayBuilder、SectionBuilder、SeparatorBuilder、MediaGalleryBuilder、FileBuilder 與 ActionRowBuilder;並說明嚴格規則,例如每個 V2 訊息都必須設定 `MessageFlags.IsComponentsV2`,且設定此旗標後無法使用 `content`、`embeds`、poll 或 stickers。此技能也詳細說明限制,例如最多 40 個元件、跨所有 TextDisplay 最多 4000 個字元、每個 Section 需有剛好一個附件(縮圖或按鈕),並提供多個範例佈局,包括資訊卡片、功能亮點、儀表板式訊息、以圖片為主的公告,以及暫時性確認/錯誤訊息。此技能支援 discord.js v14.19 及以上版本,並可在任何能使用 discord.js 的 Node.js 環境中實作。

相容平台~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 + ActionRow 仍然可用,但 V2 提供完整的版面控制,是推薦的現代方法。

需要 discord.js ≥ 14.19(目前最新版本為 14.28.x)。務必設定旗標。

重要規則

  • 每個 V2 訊息必須包含 flags: MessageFlags.IsComponentsV2(或 MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral)。
  • 一旦訊息以 V2 旗標發送,編輯時無法移除該旗標。
  • 設定此旗標後,無法發送 content、embeds、poll 或 stickers。所有可見文字皆需放在 TextDisplayBuilder 中。
  • 最多40個元件總數(含巢狀計算)。最多 4000 個字元橫跨所有 TextDisplay。
  • 附件若未被 Thumbnail、MediaGallery 或 File 元件透過 attachment://filename 引用,則不會顯示。
  • 頂層元件可為:Container、TextDisplay、Section、Separator、MediaGallery、File、ActionRow。
  • Container 不能巢狀包含其他 Container。
  • 每個 Section 需要剛好一個附件(縮圖或按鈕)。

限制

限制項目限制值備註
每則訊息的元件數40巢狀元件會個別計算。
文字字元數4,000訊息中所有 TextDisplay 的字元總和。
每個 ActionRow 的按鈕數5或一個選單,同一行不能同時有兩者。
選單選項25每個選單。
MediaGallery 項目10每個藝廊。
Container不可巢狀Container 不能包含另一個 Container。
Section每個一個附件縮圖或按鈕,不能兩者都有,也不能都沒有。
附件每則訊息 10 個每個都必須被引用才能顯示。

傳統的「每則訊息 5 個 ActionRow」上限在設定 V2 旗標後被 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)               // 模糊整個 Container
  .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),
  );

當您想在相關文字旁放置縮圖或一個醒目按鈕時,請使用 Section。永遠不要讓 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);

Thumbnail 僅作為 Section 附件存在——它們不是頂層元件。

7. 互動元件(在 ActionRow 內)

  • 每個 ActionRow 最多 5 個按鈕或 1 個選單。
  • 按鈕:ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium。
  • 連結按鈕需要使用 .setURL(),永遠不要有 customId。進階按鈕需要使用 .setSKUId()。
  • 務必為互動元件提供獨特、命名空間化的 customId(例如 ticket:close、poll:vote:yes)。Custom 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 內沒有自己的標籤——使用者看到的是 placeholder。

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——除非需要後續按鈕,否則不要用分隔線或 ActionRow。

確認提示

將破壞性動作放在最後,並設定為 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

…

[此處截斷以利翻譯]

相關技能