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(ouMessageFlags.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,polloustickers. Tout le texte visible se trouve dansTextDisplayBuilder. - 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
| Contrainte | Limite | Notes |
|---|---|---|
| Composants par message | 40 | Les composants imbriqués sont comptés individuellement. |
| Caractères de texte | 4 000 | Somme de tous les TextDisplay du message. |
| Boutons par ActionRow | 5 | Ou un menu de sélection, jamais les deux dans la même rangée. |
| Options de sélection | 25 | Par menu de sélection. |
| Éléments MediaGallery | 10 | Par galerie. |
| Conteneurs | Pas d'imbrication | Un Container ne peut pas en contenir un autre. |
| Sections | 1 accessoire chacune | Vignette ou bouton, pas les deux, pas aucun. |
| Pièces jointes | 10 par message | Chacune 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
customIdunique et avec espace de noms (par exempleticket: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 :
| Constructeur | Définisseur de valeur par défaut |
|---|---|
UserSelectMenuBuilder | setDefaultUsers(...) |
RoleSelectMenuBuilder | setDefaultRoles(...) |
ChannelSelectMenuBuilder | setDefaultChannels(...), setChannelTypes(...) |
MentionableSelectMenuBuilder | setDefaultValues(...) |
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.