Discord Components V2 (discord.js)
Verwende Components V2 für alle neuen Nachrichtenlayouts. Klassische content + embeds + Action-Reihen funktionieren immer noch, aber V2 bietet vollständige Layout-Kontrolle und ist der empfohlene moderne Ansatz.
Erfordert discord.js ≥ 14.19 (aktuell neueste Version ist 14.28.x). Setze das Flag immer.
Kritische Regeln
- Jede V2-Nachricht muss
flags: MessageFlags.IsComponentsV2(oderMessageFlags.IsComponentsV2 | MessageFlags.Ephemeral) enthalten. - Sobald eine Nachricht mit dem V2-Flag gesendet wurde, kannst du es bei einer Bearbeitung nicht mehr entfernen.
- Mit gesetztem Flag kannst du kein
content,embeds,polloderstickerssenden. Der gesamte sichtbare Text befindet sich imTextDisplayBuilder. - Maximal 40 Komponenten insgesamt (verschachtelt gezählt). Maximal 4000 Zeichen über alle TextDisplays hinweg.
- Anhänge sind unsichtbar, es sei denn, sie werden von einer Thumbnail-, MediaGallery- oder File-Komponente über
attachment://filenamereferenziert. - Komponenten der obersten Ebene können sein: Container, TextDisplay, Section, Separator, MediaGallery, File, ActionRow.
- Container können nicht ineinander verschachtelt werden.
- Jede Section benötigt genau ein Accessoire (Thumbnail oder Button).
Limits
| Einschränkung | Limit | Hinweise |
|---|---|---|
| Komponenten pro Nachricht | 40 | Verschachtelte Komponenten werden einzeln gezählt. |
| Textzeichen | 4.000 | Summe aller TextDisplay in der Nachricht. |
| Buttons pro ActionRow | 5 | Oder ein Auswahlmenü, niemals beides in derselben Zeile. |
| Auswahloptionen | 25 | Pro Auswahlmenü. |
| MediaGallery-Elemente | 10 | Pro Galerie. |
| Container | Keine Verschachtelung | Ein Container kann keinen anderen Container enthalten. |
| Sections | 1 Accessoire pro Section | Thumbnail oder Button, nicht beides, nicht keins. |
| Anhänge | 10 pro Nachricht | Jeder muss referenziert werden, um sichtbar zu sein. |
Die klassische Obergrenze von "5 ActionRows pro Nachricht" wird durch das Budget von 40 Komponenten ersetzt, wenn das V2-Flag gesetzt ist – eine ActionRow ist einfach eine der 40 Komponenten.
Importe (typisch)
const {
ContainerBuilder,
TextDisplayBuilder,
SectionBuilder,
SeparatorBuilder,
SeparatorSpacingSize,
MediaGalleryBuilder,
MediaGalleryItemBuilder,
FileBuilder,
ThumbnailBuilder,
ActionRowBuilder,
ButtonBuilder,
ButtonStyle,
StringSelectMenuBuilder,
UserSelectMenuBuilder,
RoleSelectMenuBuilder,
ChannelSelectMenuBuilder,
MentionableSelectMenuBuilder,
MessageFlags,
AttachmentBuilder,
} = require('discord.js');
Flags
MessageFlags.IsComponentsV2 // erforderlich für V2-Rendering
MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral // ephemere Antwort
MessageFlags.IsComponentsV2 | MessageFlags.SuppressEmbeds
Das Flag ist erforderlich, um V2-Komponenten zu rendern, und ist permanent: Sobald eine Nachricht damit gesendet wurde, kann es durch Bearbeiten nicht entfernt werden.
Kern-Builder & Muster
1. TextDisplay – der gesamte Text befindet sich hier
new TextDisplayBuilder().setContent('## Überschrift\nUnterstützt **Markdown**, *Kursiv*, `Code`, Listen, Erwähnungen, Emojis.')
Nur Standard-Discord-Markdown: Überschriften (#–###), fett, kursiv, unterstrichen, durchgestrichen, Inline-Code, Code-Blöcke, Spoiler (||text||), Listen, Blockzitate, Links, Zeitstempel, Erwähnungen und Emoji.
Es gibt kein content-Feld in der Nachricht bei Verwendung von V2 – dieser Builder ist der einzige Ort, an dem Text gerendert wird. Bevorzuge mehrere kleine TextDisplays gegenüber einem großen Block für einen besseren visuellen Rhythmus.
2. Container – der moderne "Embed"
const container = new ContainerBuilder()
.setAccentColor(0x5865F2) // optionaler linker Akzent (Hex-Zahl)
// .setSpoiler(true) // verwischt den gesamten Container
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Titel\nUntertitel oder Beschreibung.'),
)
.addSeparatorComponents(
new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(/* Buttons oder ein Auswahlmenü */),
);
Vollständiger Methodensatz: addTextDisplayComponents, addSectionComponents, addSeparatorComponents, addActionRowComponents, addMediaGalleryComponents, addFileComponents, addComponents und setComponents([...]) zum Ersetzen aller Kinder. Die Reihenfolge der Kinder bleibt erhalten, also baue von oben nach unten in Lesereihenfolge.
Akzentfarben, die gut aussehen: Discord Blurple 0x5865F2, Erfolg 0x57F287, Gefahr 0xED4245, sanftes Grau 0x99AAB5 oder Markenfarben. Lasse den Akzent weg für ein sauberes, flaches Aussehen. Die Farbe muss eine Zahl sein – '#5865F2' und 'blurple' werfen einen Fehler.
3. Section – Text + Accessoire (Thumbnail oder Button)
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Funktionsname**'),
new TextDisplayBuilder().setContent('Kurzer unterstützender Text. Halte ihn auf 1–3 TextDisplays.'),
)
.setThumbnailAccessory(
new ThumbnailBuilder()
.setURL('https://example.com/icon.png') // oder attachment://file.png
.setDescription('Alt-Text'),
)
// ODER
.setButtonAccessory(
new ButtonBuilder()
.setCustomId('action')
.setLabel('Mach es')
.setStyle(ButtonStyle.Primary),
);
Verwende Sections, wenn du ein Thumbnail oder einen einzelnen prominenten Button neben verwandtem Text haben möchtest. Lasse eine Section niemals ohne Accessoire und setze niemals beides.
4. Separator – visuelle Atempausen
new SeparatorBuilder()
.setDivider(true) // die dünne Linie anzeigen
.setSpacing(SeparatorSpacingSize.Small); // oder Large
Platziere sie zwischen logischen Gruppen. Bevorzuge Small + Divider für die meisten Karten; Large für größere visuelle Unterbrechungen. divider: false mit Large-Abstand ergibt eine leere Lücke ohne Linie.
5. MediaGallery & File
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder()
.setURL('https://…') // oder attachment://image.png
.setDescription('Alt')
.setSpoiler(false),
// bis zu 10 Elemente
);
new FileBuilder().setURL('attachment://report.pdf'); // muss die Datei auch in `files` übergeben
Hochgeladene Dateien, die nie von einer File-, Thumbnail- oder MediaGallery-Komponente referenziert werden, bleiben unsichtbar.
6. Thumbnail
new ThumbnailBuilder()
.setURL('https://…/icon.png') // oder attachment://icon.png
.setDescription('Alt-Text')
.setSpoiler(false);
Thumbnails existieren nur als Section-Accessoire – sie sind keine Komponenten der obersten Ebene.
7. Interaktive Komponenten (innerhalb von ActionRows)
- Maximal 5 Buttons oder 1 Auswahlmenü pro ActionRow.
- Buttons:
ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium. - Link-Buttons benötigen
.setURL(), niemals eine customId. Premium-Buttons benötigen.setSKUId(). - Gib interaktiven Komponenten immer eine eindeutige, mit Namespace versehene
customId(z. B.ticket:close,poll:vote:yes). Custom-IDs sind maximal 100 Zeichen lang.
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('confirm').setLabel('Bestätigen').setStyle(ButtonStyle.Success),
new ButtonBuilder().setCustomId('cancel').setLabel('Abbrechen').setStyle(ButtonStyle.Secondary),
);
new ActionRowBuilder().addComponents(
new StringSelectMenuBuilder()
.setCustomId('choose-plan')
.setPlaceholder('Wähle einen Plan…')
.addOptions(
{ label: 'Starter', value: 'starter', description: 'Für Einzelpersonen' },
{ label: 'Pro', value: 'pro', description: 'Für Teams', emoji: '⭐' },
),
);
Entity-Auswahlen teilen sich setCustomId, setPlaceholder, setMinValues, setMaxValues, setDisabled:
| Builder | Setter für Standardwerte |
|---|---|
UserSelectMenuBuilder | setDefaultUsers(...) |
RoleSelectMenuBuilder | setDefaultRoles(...) |
ChannelSelectMenuBuilder | setDefaultChannels(...), setChannelTypes(...) |
MentionableSelectMenuBuilder | setDefaultValues(...) |
Auswahlen haben innerhalb einer ActionRow kein eigenes Label – der Placeholder ist das, was die Benutzer sehen.
8. Anhänge
const file = new AttachmentBuilder(buffer, { name: 'chart.png' });
// referenziere es als 'attachment://chart.png' in einer MediaGallery, Thumbnail oder File
Der name des Anhangs muss mit attachment:// übereinstimmen – inklusive Groß-/Kleinschreibung und Erweiterung.
Senden & Bearbeiten
// Channel oder Interaktion
await channel.send({
components: [container], // oder [text, separator, container, …]
flags: MessageFlags.IsComponentsV2,
files: [attachment], // nur wenn referenziert
allowedMentions: { parse: [] }, // steuere Pings von TextDisplays
});
// Ephemeral
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral
// Bearbeiten (Flag ist permanent)
await message.edit({
components: [newLayout],
// NICHT versuchen, das V2-Flag zu entfernen
});
Alle Builder implementieren .toJSON(). Wenn du Layouts persistierst, speichere container.toJSON() und übergib das JSON zurück in components, um es neu zu erstellen.
Schöne Layout-Rezepte
Saubere Info-Karte
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Serverregeln\nBitte sorgfältig lesen.'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('1. Sei respektvoll\n2. Kein Spam\n3. Folge den Discord AGB'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('rules:accept').setLabel('Ich stimme zu').setStyle(ButtonStyle.Success),
),
);
Feature-Highlight mit Thumbnail
new ContainerBuilder()
.setAccentColor(0x57F287)
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## Neues Dashboard'),
new TextDisplayBuilder().setContent('Echtzeit-Statistiken, Rollenverwaltung und Analysen an einem Ort.'),
)
.setThumbnailAccessory(new ThumbnailBuilder().setURL('attachment://dashboard.png').setDescription('Dashboard-Vorschau')),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('dashboard:open').setLabel('Dashboard öffnen').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setLabel('Changelog').setURL('https://example.com/changelog').setStyle(ButtonStyle.Link),
),
);
Übergib files: [new AttachmentBuilder(buffer, { name: 'dashboard.png' })] zusammen mit den Komponenten.
Multi-Section Dashboard-artige Nachricht
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(new TextDisplayBuilder().setContent('# Bedienfeld'))
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Status**'),
new TextDisplayBuilder().setContent('🟢 Alle Systeme betriebsbereit\n👥 1.284 Mitglieder\n📈 42 Beitritte heute'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('status:refresh').setLabel('Aktualisieren').setStyle(ButtonStyle.Secondary),
),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(false).setSpacing(SeparatorSpacingSize.Large))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**Aktionen**'),
new TextDisplayBuilder().setContent('Moderieren, ankündigen oder den Server konfigurieren.'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('panel:settings').setLabel('Einstellungen').setStyle(ButtonStyle.Secondary),
),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('panel:announce').setLabel('Ankündigen').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setCustomId('panel:moderate').setLabel('Moderieren').setStyle(ButtonStyle.Danger),
),
);
Bildgesteuerte Ankündigung
Halte den Text auf 2–3 kurze Zeilen, damit das Bild im Fokus bleibt. Das Banner ist ein MediaGallery-Element – denke daran, es hochzuladen.
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addMediaGalleryComponents(
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder().setURL('attachment://event-banner.png').setDescription('Sommer-Event-Banner'),
),
)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Sommer-Event\nSei **Freitag um 20 Uhr** beim Launch-Stream dabei.'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('-# Teilnahme ist optional · Zeiten werden in UTC angezeigt'),
);
-# ist Subtext – perfekt für Kleingedrucktes, ohne mit der Überschrift zu konkurrieren.
Ephemere Bestätigung / Fehler
Verwende einen Helfer mit Akzent + Titel + Nachricht anstatt zwei Layouts zu schreiben.
const status = (type, text) => new ContainerBuilder()
.setAccentColor(type === 'error' ? 0xED4245 : 0x57F287)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent(`### ${type === 'error' ? 'Etwas ist schiefgelaufen' : 'Erledigt'}\n${text}`),
);
await interaction.reply({
components: [status('error', 'Du hast keine Berechtigung, das zu tun.')],
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
});
Halte ephemere Antworten auf einen einzelnen Container – keine Trennlinien, keine Aktionszeilen, es sei denn, du benötigst einen Folge-Button.
Bestätigungsaufforderung
Setze die destruktive Aktion an letzte Stelle und gestalte sie mit Danger.
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## 47 Nachrichten löschen?'),
new TextDisplayBuilder().setContent('Dies kann nicht rückgängig gemacht werden.'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('purge:cancel').setLabel('Abbrechen').setStyle(ButtonStyle.Secondary),
new ButtonBuilder().setCustomId('purge:confirm').setLabel('Löschen').setStyle(ButtonStyle.Danger),
),
);
Kompakte Liste
Für Änderungsprotokolle, Ranglisten und Statuslisten: Mache das Label fett, halte jeden Eintrag in einer Zeile und verwende -# für Metadaten.
new ContainerBuilder()
.setAccentColor(0x99AAB5)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Änderungsprotokoll\n**v2.1.0** – `2024-01-15`\n**v2.0.0** – `2023-12-01`\n**v1.9.0** – `2023-10-22`'),
);
Galerie (Medien + Text)
new ContainerBuilder()
.setAccentColor(0x5865F2)
.setSpoiler(true)
.addMediaGalleryComponents(
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder().setURL('attachment://screenshot1.png').setDescription('Startseite'),
new MediaGalleryItemBuilder().setURL('attachment://screenshot2.png').setDescription('Dashboard'),
),
)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# Vorschau (Spoiler)\nKlicke auf den Container, um die Bilder zu sehen.'),
);