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:
| 建構器 | 預設值設定器 |
|---|---|
UserSelectMenuBuilder | setDefaultUsers(...) |
RoleSelectMenuBuilder | setDefaultRoles(...) |
ChannelSelectMenuBuilder | setDefaultChannels(...)、setChannelTypes(...) |
MentionableSelectMenuBuilder | setDefaultValues(...) |
選擇器在 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
…
[此處截斷以利翻譯]