Communitygithub.com

discord-components-v2

Erstelle wunderschöne Discord-Bot-Nachrichten mit Komponenten V2 und discord.js (v14.19+). Verwende diese Fähigkeit, wenn du Discord-Bots baust oder umstrukturierst, die moderne Layouts, Container, Abschnitte, Textanzeigen, Buttons, Auswahlmenüs, Mediengalerien benötigen oder wenn der Nutzer Components V2, display components, IS_COMPONENTS_V2 erwähnt oder polierte, interaktive Nachrichten ohne klassische Embeds wünscht.

Was ist discord-components-v2?

Diese Fähigkeit befähigt einen KI-Agenten (z. B. Claude Code, Cursor, Codex) dazu, Discord-Bot-Nachrichten unter Verwendung des Components V2 Systems mit der Bibliothek discord.js zu erstellen. Sie ist die moderne Alternative zu klassischen content- und embed-basierten Nachrichten. Sie bietet vollständige Layout-Kontrolle durch Container, TextDisplay, Section, Separator, MediaGallery und File Builder. Die Fähigkeit setzt detaillierte Regeln, Limits und Best Practices durch, die in der offiziellen discord.js Dokumentation definiert sind. Zu den wichtigen Regeln gehört die obligatorische Verwendung des Flags MessageFlags.IsComponentsV2, das Beschränken von Text auf maximal 4000 Zeichen in TextDisplayBuildern und die Limitierung der Gesamtzahl der Komponenten auf 40 (inklusive verschachtelter). Die Fähigkeit ist für discord.js v14.19 und neuer (aktuell v14.28.x) ausgelegt. Sie ist besonders nützlich für Entwickler, die ihre Discord-Bots von veralteten Nachrichtenformaten auf moderne, interaktive und ästhetisch ansprechende Layouts migrieren. Der Assistent kann Codebeispiele, Imports und komplexe Layout-Rezepte für Info-Karten, Feature-Highlights, Dashboard-ähnliche Nachrichten und mehr generieren. Die Fähigkeit behandelt auch das Senden, Bearbeiten und ephemere Antworten, stellt sicher, dass das V2-Flag dauerhaft ist, und erklärt, wie man Anhänge für die Sichtbarkeit referenziert.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Dqrshan/discord-components-v2-skill/tree/HEAD

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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 (oder MessageFlags.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, poll oder stickers senden. Der gesamte sichtbare Text befindet sich im TextDisplayBuilder.
  • 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://filename referenziert.
  • 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änkungLimitHinweise
Komponenten pro Nachricht40Verschachtelte Komponenten werden einzeln gezählt.
Textzeichen4.000Summe aller TextDisplay in der Nachricht.
Buttons pro ActionRow5Oder ein Auswahlmenü, niemals beides in derselben Zeile.
Auswahloptionen25Pro Auswahlmenü.
MediaGallery-Elemente10Pro Galerie.
ContainerKeine VerschachtelungEin Container kann keinen anderen Container enthalten.
Sections1 Accessoire pro SectionThumbnail oder Button, nicht beides, nicht keins.
Anhänge10 pro NachrichtJeder 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:

BuilderSetter für Standardwerte
UserSelectMenuBuildersetDefaultUsers(...)
RoleSelectMenuBuildersetDefaultRoles(...)
ChannelSelectMenuBuildersetDefaultChannels(...), setChannelTypes(...)
MentionableSelectMenuBuildersetDefaultValues(...)

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.'),
  );

Verwandte Skills