Création Avancée de Commande

Les exemples que nous avons couverts jusqu'à présent ont tous été des commandes assez simples, telles que ping, server et user qui ont tous des réponses statiques standard. Cependant, vous pouvez faire beaucoup plus avec la suite complète d'outils de commande slash !

Ajout d'options

Les commandes d'application peuvent avoir des options supplémentaires. Pensez à ces options comme des arguments pour une fonction, et comme un moyen pour l'utilisateur de fournir les informations supplémentaires que la commande nécessite.

Les options nécessitent au minimum un nom et une description. Les mêmes restrictions s'appliquent aux noms d'options qu'aux noms de commandes slash - 1-32 caractères sans majuscules, espaces ou symboles autres que - et _. Vous pouvez les spécifier comme indiqué dans la commande echo ci-dessous, qui invite l'utilisateur à entrer une chaîne pour l'option input.

const { SlashCommandBuilder } = require('discord.js');

const data = new SlashCommandBuilder()
	.setName('echo')
|	.setDescription('Répond avec votre entrée !')
|	.addStringOption((option) => option.setName('input').setDescription('L\'entrée à renvoyer'));

Types d'options

En spécifiant le type d'une ApplicationCommandOption en utilisant la méthode correspondante, vous pouvez restreindre ce que l'utilisateur peut fournir en entrée, et pour certaines options, tirer parti de l'analyse automatique des options dans des objets appropriés par Discord.

L'exemple ci-dessus utilise addStringOption, la forme la plus simple d'entrée de texte standard sans validation supplémentaire. En tirant parti des types d'options supplémentaires, vous pouvez modifier le comportement de cette commande de nombreuses manières, par exemple en utilisant une option de canal pour diriger la réponse vers un canal spécifique :

const { SlashCommandBuilder } = require('discord.js');

const data = new SlashCommandBuilder()
	.setName('echo')
|	.setDescription('Répond avec votre entrée !')
|	.addStringOption((option) => option.setName('input').setDescription('L\'entrée à renvoyer'))
|
|	.addChannelOption((option) => option.setName('channel').setDescription('Le canal où échouer'));

Ou une option booléenne pour donner à l'utilisateur le contrôle de la réponse éphémérale afin que seul l'auteur de la commande puisse voir la réponse.

const { SlashCommandBuilder } = require('discord.js');

const data = new SlashCommandBuilder()
	.setName('echo')
|	.setDescription('Répond avec votre entrée !')
|	.addStringOption((option) => option.setName('input').setDescription('L\'entrée à renvoyer'))
|
|	.addBooleanOption((option) =>
|		option.setName('ephemeral').setDescription('Si l\'echo doit être éphéméral ou non'),
	);

Voici ci-dessous une courte description des différents types d'options qui peuvent être ajoutés. Pour plus d'informations, consultez les méthodes add_____Option dans la documentation SlashCommandBuilder.

• Les options String, Integer, Number et Boolean acceptent toutes les valeurs primitives de leur type associé.
  • Integer accepte uniquement des nombres entiers.
  • Number accepte à la fois des nombres entiers et des décimales.
• Les options User, Channel, Role et Mentionable afficheront une liste de sélection dans l'interface Discord pour leur type associé, ou accepteront un Flocon de neige (id) comme entrée.
• Les options Attachment invitent l'utilisateur à charger un fichier avec la commande slash.
• Les options Subcommand et SubcommandGroup vous permettent d'avoir des chemins de ramification d'options ultérieures pour vos commandes - plus sur ce sujet plus loin dans cette page.

Options obligatoires

Avec les types d'options couverts, vous pouvez commencer à examiner d'autres formes de validation pour vous assurer que les données que votre bot reçoit sont à la fois complètes et exactes. L'ajout le plus simple est de rendre les options obligatoires, pour s'assurer que la commande ne peut pas être exécutée sans une valeur obligatoire. Cette validation peut être appliquée à des options de n'importe quel type.

Examinez à nouveau l'exemple echo et utilisez setRequired(true) pour marquer l'option input comme obligatoire.

const { SlashCommandBuilder } = require('discord.js');

const data = new SlashCommandBuilder()
	.setName('echo')
	.setDescription('Replies with your input!')
|
|	.addStringOption((option) => option.setName('input').setDescription('L\'entrée à renvoyer')); 
|
|	.addStringOption((option) => option.setName('input').setDescription('L\'entrée à renvoyer').setRequired(true));

Choix

Les types d'options String, Number et Integer peuvent avoir des choices. Si vous préférez que les utilisateurs sélectionnent parmi des valeurs prédéfinies plutôt que d'une entrée libre, choices peut vous aider à l'appliquer. Ceci est particulièrement utile lors du traitement d'ensembles de données externes, d'API et similaires, où des formats d'entrée spécifiques sont requis.

Spécifiez les choix en utilisant la méthode addChoices() dans le générateur d'options, tels que SlashCommandBuilder#addStringOption. Les choix nécessitent un name qui s'affiche à l'utilisateur pour la sélection, et une value que votre bot recevra lorsque ce choix est sélectionné, comme si l'utilisateur l'avait tapé dans l'option manuellement.

L'exemple de commande gif ci-dessous permet aux utilisateurs de sélectionner parmi les catégories prédéfinies de gifs à envoyer :

const { SlashCommandBuilder } = require('discord.js');

const data = new SlashCommandBuilder()
	.setName('gif')
|	.setDescription('Envoie un gif aléatoire !')
|	.addStringOption((option) =>
|		option
|			.setName('category')
|			.setDescription('La catégorie gif')
			.setRequired(true)
			.addChoices(
				{ name: 'Funny', value: 'gif_funny' },
				{ name: 'Meme', value: 'gif_meme' },
				{ name: 'Movie', value: 'gif_movie' },
			),
	);

Si vous avez trop de choix à afficher (le maximum est 25), vous pouvez préférer fournir des choix dynamiques en fonction de ce que l'utilisateur a tapé jusqu'à présent. Ceci peut être réalisé en utilisant autocomp létion.

Validation supplémentaire

Même sans choix prédéfinis, des restrictions supplémentaires peuvent toujours être appliquées sur des entrées autrement libres.

• Pour les options String, setMaxLength() et setMinLength() peuvent imposer des limitations de longueur.
• Pour les options Integer et Number, setMaxValue() et setMinValue() peuvent imposer des limitations de plage sur la valeur.
• Pour les options Channel, addChannelTypes() peut limiter la sélection à des types de canal spécifiques, par ex. ChannelType.GuildText.

Nous allons les utiliser pour vous montrer comment améliorer votre commande echo d'avant avec une validation supplémentaire pour s'assurer qu'elle ne se cassera pas (ou du moins ne devrait pas) lors de l'utilisation :

const { SlashCommandBuilder, ChannelType } = require('discord.js');

const data = new SlashCommandBuilder()
	.setName('echo')
	.setDescription('Replies with your input!')
	.addStringOption((option) =>
		option
			.setName('input')
|			.setDescription('L\'entrée à renvoyer')
|			// S'assurer que le texte s'adaptera à une description d'intergiciel, si l'utilisateur choisit cette option
|
|			.setMaxLength(2_000),
|	)
|	.addChannelOption((option) =>
|		option
|			.setName('channel')
|			.setDescription('Le canal où échouer')
|			// S'assurer que l'utilisateur peut uniquement sélectionner un TextChannel pour la sortie
|
|			.addChannelTypes(ChannelType.GuildText),
|	)
|	.addBooleanOption((option) => option.setName('embed').setDescription('Si l\'echo doit être intégré ou non'));

Sous-commandes

Les sous-commandes sont disponibles avec la méthode .addSubcommand(). Ceci vous permet de ramifier une seule commande pour nécessiter des options différentes selon la sous-commande choisie.

Avec cette approche, vous pouvez fusionner les commandes d'information user et server de la section précédente en une seule commande info avec deux sous-commandes. De plus, la sous-commande user a une option de type User pour cibler d'autres utilisateurs, tandis que la sous-commande server n'en a pas besoin et afficherait simplement les informations de la guílde actuelle.

const { SlashCommandBuilder } = require('discord.js');

const data = new SlashCommandBuilder()
	.setName('info')
|	.setDescription('Obtenir des informations sur un utilisateur ou un serveur !')
|
|	.addSubcommand((subcommand) =>
|		subcommand
|			.setName('user')
|			.setDescription('Informations sur un utilisateur')
|			.addUserOption((option) => option.setName('target').setDescription('L\'utilisateur')),
|	)
|	.addSubcommand((subcommand) => subcommand.setName('server').setDescription('Informations sur le serveur'));

Localisations

Les noms et les descriptions des commandes slash peuvent être localisés dans la langue sélectionnée par l'utilisateur. Vous pouvez trouver la liste des paramètres régionaux acceptés sur la documentation de l'API Discord.

La définition des localisations avec setNameLocalizations() et setDescriptionLocalizations() prend le format d'un objet, mappant les codes d'emplacement (par ex. pl et de) à leurs chaînes localisées.

const { SlashCommandBuilder } = require('discord.js');

const data = new SlashCommandBuilder()
	.setName('dog')
	.setNameLocalizations({
		pl: 'pies',
		de: 'hund',
	})
|	.setDescription('Obtenez une jolie photo d\'un chien !')
	.setDescriptionLocalizations({
		pl: 'Słodkie zdjęcie pieska!',
		de: 'Poste ein niedliches Hundebild!',
	})
	.addStringOption((option) =>
		option
			.setName('breed')
|			.setDescription('Race de chien')
|
|			.setNameLocalizations({
|				pl: 'rasa',
|				de: 'rasse',
|			})
|			.setDescriptionLocalizations({
|				pl: 'Rasa psa',
|				de: 'Hunderasse',
			}),
	);

Étapes suivantes

Pour plus d'informations sur la réception et l'analyse des différents types d'options couverts sur cette page, consultez analyse des options, ou pour des informations plus générales sur la façon dont vous pouvez répondre aux commandes slash, consultez méthodes de réponse.