Comment utiliser les boutons et les menus déroulants (select menu) dans Discord.js v14 ?
Les boutons et les menus déroulants (select menu) permettent aux utilisateurs de se servir de votre bot en cliquant sur des éléments du message, sans taper de commande. Dans ce guide, vous allez créer avec discord.js v14 un bouton de confirmation, un menu à choix multiples et un panneau de sélection de rôles qui continue de fonctionner même après un redémarrage du bot ; vous verrez aussi les trois façons d'intercepter un clic, la règle des 3 secondes et les limites des composants.
Avant de commencer
- Un bot à commandes slash qui fonctionne : les exemples reprennent la structure de projet du guide Comment créer un bot Discord à partir de zéro avec Discord.js v14 : le dossier
commands/utility,deploy-commands.js,index.jset les scriptsnpm start/npm run deploy. - discord.js v14 et Node.js : les exemples ont été écrits d'après la documentation de discord.js 14.27.0. Cette version exige Node.js 18 ou une version plus récente ; la version LTS du guide d'installation remplit cette condition. Vous pouvez afficher les versions installées avec les commandes
npm ls discord.jsetnode -v. - Aucun intent (autorisation d'événements) supplémentaire : les clics arrivent eux aussi sous forme d'interactions, comme les commandes slash ;
GatewayIntentBits.Guildssuffit. - Permission pour le panneau de rôles : le rôle du bot doit disposer de la permission Gérer les rôles (Manage Roles). Discord n'autorise un bot à attribuer que les rôles situés en dessous de son propre rôle le plus élevé ; dans la liste « Paramètres du serveur → Rôles », placez le rôle du bot au-dessus des rôles qu'il doit distribuer.
- Où faire tourner le bot : le code et les commandes sont identiques sous Windows et sous Linux ; vous pouvez développer sur votre propre ordinateur. Pour qu'un panneau permanent réponde à tout moment, le bot doit rester allumé en permanence ; utilisez pour cela un VDS. Les offres VDS pour bot Discord de HanHosting sont fournies avec 4 CPU, 2–4 Go de RAM et 30–40 Go de disque NVMe.
1. Découvrir la structure des composants et les méthodes d'interception
Pour ajouter des composants à un message, vous créez un ActionRowBuilder (ligne d'action), vous y placez les boutons ou le menu, puis vous passez cette ligne au tableau components du message. Un message classique compte au maximum 5 lignes ; une ligne contient au maximum 5 boutons ou un seul menu déroulant, et un bouton et un menu ne peuvent pas partager la même ligne.
Chaque composant interactif possède une valeur customId (identifiant personnalisé) que vous définissez ; lorsque l'utilisateur clique, Discord envoie cet identifiant au bot, qui sait ainsi quel composant a été actionné. Discord attend la première réponse à chaque interaction dans un délai de 3 secondes ; sans réponse, il considère que l'interaction a échoué et l'utilisateur voit un message d'erreur sous le message. Il existe trois façons d'intercepter un clic :
| Méthode | Usage adapté | Si le bot redémarre |
|---|---|---|
awaitMessageComponent | Questions de confirmation n'attendant qu'une seule réponse | L'attente est perdue |
createMessageComponentCollector (collecteur) | Plusieurs clics pendant une durée donnée : menu, vote | Le collecteur s'arrête |
interactionCreate (événement) | Panneaux sans limite de durée : sélection de rôles, ouverture d'un ticket de support | Continue de fonctionner |
Les deux premières vivent dans la mémoire du processus du bot et prennent fin à l'expiration du délai. Avec la troisième, le customId est enregistré dans le message : les anciens panneaux fonctionnent donc encore lorsque le bot redémarre.
2. Écrire une commande avec des boutons de confirmation
Créez le fichier commands/utility/confirmation.js. La commande envoie deux boutons et attend pendant 60 secondes le clic de la seule personne qui a utilisé la commande :
const {
ActionRowBuilder, ButtonBuilder, ButtonStyle, SlashCommandBuilder,
} = require('discord.js');
module.exports = {
data: new SlashCommandBuilder()
.setName('confirmation')
.setDescription('Affiche les boutons de confirmation.'),
async execute(interaction) {
const confirmer = new ButtonBuilder()
.setCustomId('confirmer')
.setLabel('Confirmer')
.setStyle(ButtonStyle.Success);
const annuler = new ButtonBuilder()
.setCustomId('annuler')
.setLabel('Annuler')
.setStyle(ButtonStyle.Secondary);
const ligne = new ActionRowBuilder().addComponents(annuler, confirmer);
const reponse = await interaction.reply({
content: 'Confirmez-vous cette action ?',
components: [ligne],
withResponse: true,
});
const filtre = (i) => i.user.id === interaction.user.id;
try {
const clic = await reponse.resource.message.awaitMessageComponent({
filter: filtre,
time: 60_000,
});
const texte = clic.customId === 'confirmer' ? 'Action confirmée.' : 'Action annulée.';
await clic.update({ content: texte, components: [] });
} catch {
await interaction.editReply({
content: 'Aucune réponse en 1 minute, action annulée.',
components: [],
});
}
},
};
withResponse: truevous donne accès au message envoyé viareponse.resource.message; l'optionfetchReply: truedes anciens exemples est marquée comme obsolète (deprecated).filterignore les clics des autres membres ; la personne laissée sans réponse voit alors un message d'erreur. Si vous voulez l'éviter, répondez-lui séparément, comme à l'étape 3.update()répond en modifiant le message qui porte le bouton ;components: []retire les boutons.- Si le délai expire,
awaitMessageComponentlève une erreur et le bloccatchmet le message à jour.
3. Lire un menu déroulant avec un collecteur
StringSelectMenuBuilder est le menu dont vous écrivez vous-même les options (dans les premières versions de la v14, il s'appelait SelectMenuBuilder ; ce nom fonctionne encore, mais il est obsolète et affiche un avertissement). Pour chaque option, le label (libellé) que voit l'utilisateur et la value (valeur) transmise au bot sont obligatoires ; description est facultatif. setMinValues et setMaxValues activent le choix multiple. commands/utility/jeux.js :
const {
ActionRowBuilder, ComponentType, MessageFlags, SlashCommandBuilder,
StringSelectMenuBuilder, StringSelectMenuOptionBuilder,
} = require('discord.js');
module.exports = {
data: new SlashCommandBuilder()
.setName('jeux')
.setDescription('Choisissez les jeux auxquels vous jouez.'),
async execute(interaction) {
const menu = new StringSelectMenuBuilder()
.setCustomId('choix-jeux')
.setPlaceholder('Choisissez 3 jeux au maximum')
.setMinValues(1)
.setMaxValues(3)
.addOptions(
new StringSelectMenuOptionBuilder().setLabel('Minecraft').setValue('minecraft'),
new StringSelectMenuOptionBuilder().setLabel('FiveM').setValue('fivem'),
new StringSelectMenuOptionBuilder()
.setLabel('Rust')
.setValue('rust')
.setDescription('Jeu de survie'),
);
const reponse = await interaction.reply({
content: 'À quels jeux jouez-vous ?',
components: [new ActionRowBuilder().addComponents(menu)],
withResponse: true,
});
const collecteur = reponse.resource.message.createMessageComponentCollector({
componentType: ComponentType.StringSelect,
time: 120_000,
});
collecteur.on('collect', async (i) => {
if (i.user.id !== interaction.user.id) {
await i.reply({ content: 'Ce menu appartient à la personne qui a utilisé la commande.', flags: MessageFlags.Ephemeral });
return;
}
await i.update({ content: `Votre sélection : ${i.values.join(', ')}` });
});
collecteur.on('end', async () => {
await interaction.editReply({ components: [] });
});
},
};
Avec le choix multiple, l'interaction n'est pas envoyée à chaque clic, mais lorsque l'utilisateur a terminé sa sélection et clique en dehors du menu ; toutes les valeurs choisies arrivent dans le tableau i.values. Au bout de 2 minutes, le collecteur déclenche l'événement end et le menu est retiré. Le jeton (token) de l'interaction d'origine est valable 15 minutes ; passé ce délai, interaction.editReply ne fonctionne plus. Gardez la durée du collecteur en dessous de cette limite et, pour les menus à longue durée de vie, utilisez l'étape 4.
4. Mettre en place un panneau permanent de sélection de rôles
Pour un panneau qui restera dans un salon pendant des semaines, traitez les clics dans index.js, dans l'événement interactionCreate, en vous fiant à la valeur customId. Créez d'abord le fichier roles.js à la racine du projet. Remplacez les identifiants de l'exemple par ceux de vos propres rôles. Pour copier l'identifiant d'un rôle, activez le Mode développeur (Developer Mode) dans « Paramètres utilisateur → Avancés », puis utilisez le menu du rôle dans la liste « Paramètres du serveur → Rôles » ; le nom des menus peut varier selon la version de l'interface.
// roles.js - rôles du panneau (25 au maximum)
module.exports = [
{ label: 'Annonces', value: '111111111111111111' },
{ label: 'Événements', value: '222222222222222222' },
{ label: 'Minecraft', value: '333333333333333333' },
];
La commande qui envoie le panneau est commands/utility/panneau-roles.js. Par défaut, setDefaultMemberPermissions n'affiche la commande qu'aux membres disposant de la permission « Gérer les rôles » :
const {
ActionRowBuilder, PermissionFlagsBits, SlashCommandBuilder, StringSelectMenuBuilder,
} = require('discord.js');
const rolesPanneau = require('../../roles.js');
module.exports = {
data: new SlashCommandBuilder()
.setName('panneau-roles')
.setDescription('Envoie le panneau de sélection de rôles dans ce salon.')
.setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles),
async execute(interaction) {
const menu = new StringSelectMenuBuilder()
.setCustomId('panneau-roles')
.setPlaceholder('Choisissez les rôles à obtenir ou à retirer')
.setMinValues(1)
.setMaxValues(rolesPanneau.length)
.addOptions(...rolesPanneau);
await interaction.reply({
content: "Un rôle choisi vous est attribué si vous ne l'avez pas, et retiré si vous l'avez déjà.",
components: [new ActionRowBuilder().addComponents(menu)],
});
},
};
Ajoutez maintenant les lignes rolesPanneau en haut du fichier index.js, et le contrôle du panneau au début de l'écouteur d'événements qui traite les commandes slash. La ligne require('discord.js') du guide d'installation importe déjà les noms Events et MessageFlags :
const rolesPanneau = require('./roles.js');
const autorises = rolesPanneau.map((r) => r.value);
client.on(Events.InteractionCreate, async (interaction) => {
if (interaction.isStringSelectMenu() && interaction.customId === 'panneau-roles') {
await interaction.deferUpdate();
const roles = interaction.member.roles;
let ajoutes = 0;
let retires = 0;
try {
for (const id of interaction.values.filter((v) => autorises.includes(v))) {
if (roles.cache.has(id)) {
await roles.remove(id);
retires++;
} else {
await roles.add(id);
ajoutes++;
}
}
await interaction.followUp({
content: `Rôles attribués : ${ajoutes}, rôles retirés : ${retires}.`,
flags: MessageFlags.Ephemeral,
});
} catch (error) {
console.error(error);
await interaction.followUp({
content: 'Impossible de mettre à jour les rôles ; vérifiez les permissions de rôle du bot.',
flags: MessageFlags.Ephemeral,
});
}
return;
}
if (!interaction.isChatInputCommand()) return;
// ... le code existant qui gère les commandes slash reste inchangé
});
Comme le panneau a le même aspect pour tout le monde, le menu n'indique pas quels rôles le membre possède déjà ; c'est pourquoi l'exemple suit la logique « si le membre a le rôle choisi, le retirer ; sinon, l'attribuer ». La liste autorises garantit que le code ne touche qu'aux rôles définis dans roles.js. Comme deferUpdate() accuse immédiatement réception de l'interaction, celle-ci n'échoue pas même si les opérations sur les rôles dépassent 3 secondes ; l'appel réinitialise en outre l'état du message, ce qui efface la sélection dans le menu. Dans ce cas, editReply() modifierait le message du panneau lui-même ; le résultat est donc communiqué avec followUp(), dans un message éphémère (ephemeral) visible uniquement par la personne qui a cliqué. Un bouton permanent (par exemple pour ouvrir un ticket de support) se traite avec la même structure, à l'aide d'un contrôle interaction.isButton() et customId.
5. Utiliser les menus de sélection d'utilisateurs, de rôles et de salons
Vous n'ajoutez pas d'options aux menus UserSelectMenuBuilder, RoleSelectMenuBuilder, MentionableSelectMenuBuilder et ChannelSelectMenuBuilder ; Discord liste lui-même les membres, les rôles ou les salons du serveur.
const {
ChannelSelectMenuBuilder, ChannelType, UserSelectMenuBuilder,
} = require('discord.js');
const menuUtilisateurs = new UserSelectMenuBuilder()
.setCustomId('choix-utilisateurs')
.setMaxValues(5);
const menuSalons = new ChannelSelectMenuBuilder()
.setCustomId('choix-salon')
.setChannelTypes(ChannelType.GuildText);
setChannelTypes limite la liste aux salons textuels. Distinguez les clics avec isUserSelectMenu(), isRoleSelectMenu(), isMentionableSelectMenu() ou isChannelSelectMenu() ; le tableau values contient les identifiants sélectionnés. Ces menus conviennent aux commandes de configuration, comme le choix d'un salon de logs.
6. Enregistrer les commandes et tester
Enregistrez les nouveaux fichiers de commandes auprès de Discord, puis démarrez le bot :
npm run deploy
npm start
Sur le serveur de test, essayez les commandes /confirmation, /jeux et /panneau-roles. Testez le filtre en cliquant, avec un second compte, sur les boutons ouverts par quelqu'un d'autre ; après avoir essayé le panneau de rôles, redémarrez le bot et vérifiez que le panneau fonctionne toujours.
Les définitions des boutons et des menus appartiennent au message, pas à l'enregistrement des commandes : lorsque vous modifiez un libellé ou une option, npm run deploy est inutile, il suffit de redémarrer le bot. Un ancien panneau resté dans un salon affiche les anciens composants ; renvoyez le panneau. Si le bot tourne avec PM2 sur un VDS (installation décrite dans le guide Garder un bot Discord en ligne 24 h/24, 7 j/7 sur un VDS), exécutez ceci après avoir mis à jour les fichiers :
pm2 restart discord-bot
Limites des composants et méthodes de réponse
Les valeurs proviennent de la référence des composants de Discord :
| Élément | Limite |
|---|---|
| Ligne d'action (message classique) | 5 au maximum par message |
| Contenu d'une ligne | 5 boutons au maximum ou 1 menu déroulant |
customId | 1–100 caractères ; unique au sein d'un même message |
| Libellé d'un bouton | 80 caractères au maximum |
| Option d'un menu déroulant | 25 au maximum ; label, value, description : 100 caractères au maximum chacun |
placeholder | 150 caractères au maximum |
setMinValues / setMaxValues | Valeur minimale 0–25, valeur maximale 25 au plus ; 1 par défaut pour les deux |
| Style / méthode | Utilité |
|---|---|
ButtonStyle.Primary / Secondary | Action principale bleu-violet / action secondaire grise (p. ex. Annuler) |
ButtonStyle.Success / Danger | Confirmation verte / action destructrice rouge (suppression, expulsion) |
ButtonStyle.Link | Exige setURL et n'accepte pas de customId ; ouvre une adresse dans le navigateur, sans qu'aucune interaction parvienne au bot |
update() | Répond en modifiant le message qui porte le composant |
deferUpdate() | Accuse immédiatement réception de l'interaction ; ensuite, editReply() modifie le message qui porte le composant et followUp() envoie un nouveau message |
reply() / deferReply() | Nouveau message de réponse ; avec MessageFlags.Ephemeral, seule la personne qui a cliqué le voit |
followUp() / editReply() | Message supplémentaire ou modification après la première réponse |
Erreurs fréquentes
- Un message d'erreur apparaît au clic (« This interaction failed » dans l'interface anglaise) : aucun code n'écoute le composant (le délai du collecteur a expiré, le bot a redémarré ou le
customIddu code ne correspond pas à celui du message), ou bien la réponse a dépassé 3 secondes. Si la console afficheDiscordAPIError[10062]: Unknown interaction, vous avez répondu trop tard : appelezdeferUpdate()oudeferReply()avant les tâches longues. DiscordAPIError[40060]: Interaction has already been acknowledged: la même interaction a reçu deux fois une première réponse : soit un collecteur etinteractionCreatetraitent tous deux le mêmecustomId, soitupdate()a été suivi d'un appel àreply(). Après la première réponse, utilisezfollowUp()oueditReply(); donnez des identifiants différents aux composants permanents et aux composants temporaires.DiscordAPIError[50035]: Invalid Form Body: Discord a refusé la définition du composant. Plus de 5 boutons sur une ligne, un bouton et un menu sur la même ligne, plus de 25 options, deux composants portant le même identifiant, un bouton normal sanscustomIdou un bouton Link doté d'uncustomIdprovoquent cette erreur.- À l'attribution d'un rôle,
DiscordAPIError[50013]: Missing Permissions: le bot n'a pas la permission « Gérer les rôles », ou le rôle à attribuer n'est pas situé en dessous du rôle le plus élevé du bot. Remontez le rôle du bot dans la liste. MessageButton is not a constructor: le code est prévu pour discord.js v13. Équivalents en v14 :MessageActionRow→ActionRowBuilder,MessageButton→ButtonBuilder,MessageSelectMenu→StringSelectMenuBuilder(le nomSelectMenuBuilderdes premières versions de la v14 etisSelectMenu()sont eux aussi obsolètes ; utilisezisStringSelectMenu()),'PRIMARY'→ButtonStyle.Primary,'BUTTON'→ComponentType.Button. À la place de l'option obsolèteephemeral: true, écrivezflags: MessageFlags.Ephemeral.
Questions fréquentes
Que deviennent les boutons lorsque le bot est éteint ?
Les boutons paraissent cliquables, mais comme aucune réponse n'arrive, l'utilisateur voit un message d'erreur. Au redémarrage du bot, les panneaux traités par interactionCreate fonctionnent de nouveau, contrairement aux messages liés à un collecteur. Retirez les composants dans l'événement end du collecteur ; si le bot s'arrête avant l'expiration du délai, end ne s'exécute pas et les anciens composants restés en place affichent un message d'erreur.
Puis-je ouvrir un formulaire au clic sur un bouton ?
Oui, showModal() permet d'afficher une modale (formulaire en fenêtre contextuelle). Une modale est une première réponse ; elle ne s'ouvre pas si vous avez déjà appelé deferUpdate(), deferReply() ou reply() sur la même interaction.
Peut-on réserver un bouton à un rôle précis ?
Toute personne qui voit le message peut cliquer ; la restriction se fait dans le code. Vérifiez le rôle de la personne qui clique avec interaction.member.roles.cache.has('id-du-role') et, si elle n'est pas autorisée, signalez-le-lui par une réponse éphémère (ephemeral) ; si vous la laissez sans réponse, elle voit un message d'erreur.
Qu'est-ce que Components V2 et dois-je l'utiliser ?
C'est la nouvelle mise en page des messages de Discord, activée par le flag IS_COMPONENTS_V2 : lorsque le flag est actif, content et les embeds ne peuvent pas être utilisés, le contenu est construit à l'aide de composants et un message peut compter jusqu'à 40 composants. Discord indique que les composants classiques ne seront pas rendus obsolètes ; la logique des boutons et des menus est la même dans les deux mises en page. Les détails figurent sur la page Display Components (composants d'affichage) du guide discord.js, et la liste complète des classes et des méthodes dans la documentation de discord.js.
Guides associés
- Comment créer un bot Discord à partir de zéro avec Discord.js v14
- Ajouter des commandes slash (/) avec Discord.js v14
- Comment créer un bot de support (tickets) avec Discord.js v14 ?
- Bases de données pour bots Discord : SQLite, PostgreSQL, MySQL, MongoDB
- Garder un bot Discord en ligne 24 h/24, 7 j/7 sur un VDS : PM2, systemd et NSSM
Les autres guides consacrés aux bots se trouvent sur la page Guides bot Discord ; les offres de serveurs, sur la page VDS pour bot Discord.
Commentaires0
Pas encore de commentaire
Soyez le premier à partager votre avis.
Veuillez vous connecter ou vous inscrire pour laisser un commentaire.