Communitygithub.com

Composants Discord V2 (discord.js)

Créez de magnifiques messages Discord modernes avec les Composants V2 et discord.js (v14.19+). À utiliser pour construire ou refondre des bots Discord nécessitant des mises en page modernes : conteneurs, sections, affichages de texte, boutons, menus de sélection, galeries média, ou lorsque l'utilisateur mentionne Composants V2, composants d'affichage, IS_COMPONENTS_V2, ou souhaite des messages interactifs soignés sans embeds classiques.

Qu'est-ce que Composants Discord V2 (discord.js) ?

Cette compétence fournit un guide complet pour utiliser les Composants V2 de Discord avec la bibliothèque discord.js (v14.19+). Elle explique comment créer des messages riches et modernes en remplacement des embeds classiques, en utilisant des conteneurs, des sections, des séparateurs, des affichages de texte, des galeries média, des fichiers et des boutons. Les règles critiques, comme l'obligation d'inclure le flag `MessageFlags.IsComponentsV2`, la limite de 40 composants par message, et l'impossibilité d'utiliser `content` ou `embeds` avec ce flag, y sont détaillées. La compétence propose des exemples de code pour tous les constructeurs essentiels (ContainerBuilder, TextDisplayBuilder, SectionBuilder, etc.) ainsi que des recettes de mise en page prêtes à l'emploi pour des messages élégants, tels que des cartes d'information, des annonces avec image, des confirmations éphémères ou des listes compactes. Elle est conçue pour les développeurs utilisant discord.js ≥ 14.19 souhaitant adopter les Composants V2 pour leurs bots Discord.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait Composants Discord V2 (discord.js) ?

Utilisez les Composants V2 pour toutes les nouvelles mises en page de messages. Les content + embeds + rangées d'actions classiques fonctionnent toujours, mais V2 offre un contrôle total de la mise en page et constitue l'approche moderne recommandée.

Nécessite discord.js ≥ 14.19 (la version actuelle la plus récente est 14.28.x). Définissez toujours le flag.

Règles critiques

  • Chaque message V2 doit inclure flags: MessageFlags.IsComponentsV2 (ou MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral).
  • Une fois qu'un message est envoyé avec le flag V2, vous ne pouvez pas le supprimer lors d'une modification.
  • Avec le flag activé, vous ne pouvez pas envoyer content, embeds, poll ou stickers. Tout le texte visible se trouve dans TextDisplayBuilder.
  • Maximum 40 composants au total (nombre imbriqué). Maximum 4000 caractères sur tous les TextDisplays.
  • Les pièces jointes sont invisibles sauf si elles sont référencées par un composant Thumbnail, MediaGallery ou File via attachment://filename.
  • Les composants de premier niveau peuvent être : Container, TextDisplay, Section, Separator, MediaGallery, File, ActionRow.
  • Les Conteneurs ne peuvent pas être imbriqués dans d'autres Conteneurs.
  • Chaque Section doit avoir exactement un accessoire (vignette ou bouton).

Limites

ContrainteLimiteNotes
Composants par message40Les composants imbriqués sont comptés individuellement.
Caractères de texte4 000Somme de tous les TextDisplay du message.
Boutons par ActionRow5Ou un menu de sélection, jamais les deux dans la même rangée.
Options de sélection25Par menu de sélection.
Éléments MediaGallery10Par galerie.
ConteneursPas d'imbricationUn Container ne peut pas en contenir un autre.
Sections1 accessoire chacuneVignette ou bouton, pas les deux, pas aucun.
Pièces jointes10 par messageChacune doit être référencée pour être visible.

La limite classique de "5 ActionRows par message" est remplacée par le budget de 40 composants lorsque le flag V2 est défini — une ActionRow est simplement l'un des 40 composants.

Imports (typiques)

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                          // requis pour le rendu V2
MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral // réponse éphémère
MessageFlags.IsComponentsV2 | MessageFlags.SuppressEmbeds

Le flag est requis pour afficher les composants V2 et est permanent : une fois qu'un message est envoyé avec, une modification ne peut pas le supprimer.

Constructeurs et modèles principaux

1. TextDisplay – tout le texte se trouve ici

new TextDisplayBuilder().setContent('## Titre\nPrend en charge la **mise en forme**, *l\'italique*, le `code`, les listes, les mentions, les emojis.')

Markdown Discord standard uniquement : titres (#–###), gras, italique, souligné, barré, code en ligne, blocs de code, spoilers (||texte||), listes, citations, liens, horodatages, mentions et emoji.

Il n'y a pas de champ content sur le message lors de l'utilisation de V2 — ce constructeur est le seul endroit où le texte est rendu. Privilégiez plusieurs petits TextDisplays plutôt qu'un seul bloc géant pour un meilleur rythme visuel.

2. Container – le "embed" moderne

const container = new ContainerBuilder()
  .setAccentColor(0x5865F2)          // barre latérale gauche optionnelle (nombre hexadécimal)
  // .setSpoiler(true)               // floute tout le conteneur
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# Titre\nSous-titre ou description.'),
  )
  .addSeparatorComponents(
    new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(/* boutons ou un menu de sélection */),
  );

Méthodes complètes : addTextDisplayComponents, addSectionComponents, addSeparatorComponents, addActionRowComponents, addMediaGalleryComponents, addFileComponents, addComponents, et setComponents([...]) pour remplacer tous les enfants. L'ordre des enfants est préservé, construisez donc de haut en bas dans l'ordre de lecture.

Couleurs d'accent qui rendent bien : le blurple Discord 0x5865F2, le succès 0x57F287, le danger 0xED4245, le gris doux 0x99AAB5, ou les couleurs de marque. Omettez l'accent pour un aspect plat et propre. La couleur doit être un nombre — '#5865F2' et 'blurple' génèrent une erreur.

3. Section – texte + accessoire (vignette ou bouton)

new SectionBuilder()
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('**Nom de la fonctionnalité**'),
    new TextDisplayBuilder().setContent('Texte d\'accompagnement court. Limitez-vous à 1 à 3 TextDisplays.'),
  )
  .setThumbnailAccessory(
    new ThumbnailBuilder()
      .setURL('https://example.com/icon.png')   // ou attachment://file.png
      .setDescription('Texte alternatif'),
  )
  // OU
  .setButtonAccessory(
    new ButtonBuilder()
      .setCustomId('action')
      .setLabel('Faire')
      .setStyle(ButtonStyle.Primary),
  );

Utilisez les Sections lorsque vous souhaitez une vignette ou un seul bouton proéminent à côté du texte associé. Ne laissez jamais une Section sans accessoire et ne définissez jamais les deux.

4. Separator – espace de respiration visuel

new SeparatorBuilder()
  .setDivider(true)                    // afficher la fine ligne
  .setSpacing(SeparatorSpacingSize.Small); // ou Large

Placez entre les groupes logiques. Préférez Small + séparateur pour la plupart des cartes ; Large pour des coupures visuelles plus grandes. divider: false avec un espacement Large donne un espace vide sans ligne.

5. MediaGallery & File

new MediaGalleryBuilder().addItems(
  new MediaGalleryItemBuilder()
    .setURL('https://…')          // ou attachment://image.png
    .setDescription('Alt')
    .setSpoiler(false),
  // jusqu'à 10 éléments
);

new FileBuilder().setURL('attachment://report.pdf'); // doit également passer le fichier dans `files`

Les fichiers téléchargés mais jamais référencés par un File, Thumbnail ou MediaGallery restent invisibles.

6. Thumbnail

new ThumbnailBuilder()
  .setURL('https://…/icon.png')   // ou attachment://icon.png
  .setDescription('Texte alternatif')
  .setSpoiler(false);

Les vignettes existent uniquement en tant qu'accessoire de Section — ce ne sont pas des composants de premier niveau.

7. Composants interactifs (dans les ActionRows)

  • Maximum 5 boutons ou 1 menu de sélection par ActionRow.
  • Boutons : ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium.
  • Les boutons Link ont besoin de .setURL(), jamais d'un customId. Les boutons Premium ont besoin de .setSKUId().
  • Donnez toujours aux composants interactifs un customId unique et avec espace de noms (par exemple ticket:close, poll:vote:yes). Les identifiants personnalisés font au maximum 100 caractères.
new ActionRowBuilder().addComponents(
  new ButtonBuilder().setCustomId('confirmer').setLabel('Confirmer').setStyle(ButtonStyle.Success),
  new ButtonBuilder().setCustomId('annuler').setLabel('Annuler').setStyle(ButtonStyle.Secondary),
);

new ActionRowBuilder().addComponents(
  new StringSelectMenuBuilder()
    .setCustomId('choisir-plan')
    .setPlaceholder('Sélectionnez un plan…')
    .addOptions(
      { label: 'Débutant', value: 'debutant', description: 'Pour les particuliers' },
      { label: 'Pro', value: 'pro', description: 'Pour les équipes', emoji: '⭐' },
    ),
);

Les sélecteurs d'entité partagent setCustomId, setPlaceholder, setMinValues, setMaxValues, setDisabled :

ConstructeurDéfinisseur de valeur par défaut
UserSelectMenuBuildersetDefaultUsers(...)
RoleSelectMenuBuildersetDefaultRoles(...)
ChannelSelectMenuBuildersetDefaultChannels(...), setChannelTypes(...)
MentionableSelectMenuBuildersetDefaultValues(...)

Les sélecteurs n'ont pas de libellé propre dans une ActionRow — c'est le placeholder que les utilisateurs voient.

8. Pièces jointes

const file = new AttachmentBuilder(buffer, { name: 'chart.png' });
// référencez-le comme 'attachment://chart.png' dans un MediaGallery, Thumbnail ou File

Le name de la pièce jointe est ce que attachment:// doit correspondre — y compris la casse et l'extension.

Envoi et modification

// Canal ou interaction
await channel.send({
  components: [container],          // ou [text, separator, container, …]
  flags: MessageFlags.IsComponentsV2,
  files: [attachment],              // uniquement si référencé
  allowedMentions: { parse: [] },   // contrôle les pings depuis les TextDisplays
});

// Éphémère
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral

// Modification (le flag est permanent)
await message.edit({
  components: [newLayout],
  // NE tentez PAS de supprimer le flag V2
});

Tous les constructeurs implémentent .toJSON(). Si vous persistez des mises en page, stockez container.toJSON() et passez le JSON dans components pour reconstruire.

Recettes de mise en page élégantes

Carte d'information simple

new ContainerBuilder()
  .setAccentColor(0x5865F2)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# Règles du serveur\nVeuillez lire attentivement.'),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('1. Soyez respectueux\n2. Pas de spam\n3. Suivez les CGU de Discord'),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('rules:accept').setLabel('J\'accepte').setStyle(ButtonStyle.Success),
    ),
  );

Mise en avant d'une fonctionnalité avec vignette

new ContainerBuilder()
  .setAccentColor(0x57F287)
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('## Nouveau tableau de bord'),
        new TextDisplayBuilder().setContent('Statistiques en temps réel, gestion des rôles et analyses en un seul endroit.'),
      )
      .setThumbnailAccessory(new ThumbnailBuilder().setURL('attachment://dashboard.png').setDescription('Aperçu du tableau de bord')),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('dashboard:open').setLabel('Ouvrir le tableau de bord').setStyle(ButtonStyle.Primary),
      new ButtonBuilder().setLabel('Journal des modifications').setURL('https://example.com/changelog').setStyle(ButtonStyle.Link),
    ),
  );

Passez files: [new AttachmentBuilder(buffer, { name: 'dashboard.png' })] avec les composants.

Message de type tableau de bord multi-sections

new ContainerBuilder()
  .setAccentColor(0x5865F2)
  .addTextDisplayComponents(new TextDisplayBuilder().setContent('# Panneau de contrôle'))
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('**Statut**'),
        new TextDisplayBuilder().setContent('🟢 Tous les systèmes opérationnels\n👥 1 284 membres\n📈 42 arrivées aujourd\'hui'),
      )
      .setButtonAccessory(
        new ButtonBuilder().setCustomId('status:refresh').setLabel('Actualiser').setStyle(ButtonStyle.Secondary),
      ),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(false).setSpacing(SeparatorSpacingSize.Large))
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('**Actions**'),
        new TextDisplayBuilder().setContent('Modérer, annoncer ou configurer le serveur.'),
      )
      .setButtonAccessory(
        new ButtonBuilder().setCustomId('panel:settings').setLabel('Paramètres').setStyle(ButtonStyle.Secondary),
      ),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('panel:announce').setLabel('Annoncer').setStyle(ButtonStyle.Primary),
      new ButtonBuilder().setCustomId('panel:moderate').setLabel('Modérer').setStyle(ButtonStyle.Danger),
    ),
  );

Annonce avec image en vedette

Gardez le texte sur 2 à 3 lignes courtes pour que l'image reste au centre de l'attention. La bannière est un élément MediaGallery — n'oubliez pas de la télécharger.

new ContainerBuilder()
  .setAccentColor(0xFEE75C)
  .addMediaGalleryComponents(
    new MediaGalleryBuilder().addItems(
      new MediaGalleryItemBuilder().setURL('attachment://event-banner.png').setDescription('Bannière de l\'événement estival'),
    ),
  )
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# Événement estival\nRejoignez-nous **vendredi à 20h** pour le lancement en direct.'),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('-# La participation est facultative · Les heures sont affichées en UTC'),
  );

-# est du sous-texte — parfait pour les mentions légales sans concurrencer le titre.

Confirmation / erreur éphémère

Réutilisez une seule fonction d'assistance avec un accent + titre + message au lieu d'écrire deux mises en page.

const statut = (type, texte) => new ContainerBuilder()
  .setAccentColor(type === 'error' ? 0xED4245 : 0x57F287)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent(`### ${type === 'error' ? 'Une erreur est survenue' : 'Fait'}\n${texte}`),
  );

await interaction.reply({
  components: [statut('error', 'Vous n\'avez pas la permission de faire cela.')],
  flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
});

Limitez les réponses éphémères à un seul Container — pas de séparateurs, pas de rangées d'actions sauf si vous avez besoin d'un bouton de suivi.

Invite de confirmation

Placez l'action destructive en dernier et stylisez-la en Danger.

new ContainerBuilder()
  .setAccentColor(0xFEE75C)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('## Supprimer 47 messages ?'),
    new TextDisplayBuilder().setContent('Cette action est irréversible.'),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('purge:cancel').setLabel('Annuler').setStyle(ButtonStyle.Secondary),
      new ButtonBuilder().setCustomId('purge:confirm').setLabel('Supprimer').setStyle(ButtonStyle.Danger),
    ),
  );

Liste compacte

Pour les journaux des modifications, les classements et les listes de statut : mettez le libellé en gras, gardez chaque entrée sur une ligne, utilisez -# pour les métadonnées.

new TextDisplayBuilder().setContent(
  '**Version 2.4.0** - 2025-04-01\n' +
  '✨ Nouveau tableau de bord\n' +
  '🐛 Correction d\'un bug de connexion\n' +
  '-# Notes de version complètes : /changelogs'
);

Enveloppez-le dans un Container pour une couleur d'accent, ou utilisez-le directement comme composant de premier niveau pour une liste minimaliste.

Skills associés