Mise à jour vers v14

Avant de commencer

Assurez-vous que vous utilisez la dernière version LTS de Node. Pour vérifier votre version de Node, utilisez node -v dans votre terminal ou invite de commande, et si ce n'est pas assez haut, mettez-la à jour ! Il y a de nombreuses ressources en ligne pour vous aider à cette étape en fonction de votre système hôte.

Divers paquets sont maintenant inclus dans v14

Si vous aviez précédemment @discordjs/builders, @discordjs/formatters, @discordjs/rest ou discord-api-types installés manuellement, il est hautement recommandé que vous désinstalliez les paquets pour éviter les conflits de version de paquet.

npm uninstall @discordjs/builders @discordjs/formatters @discordjs/rest discord-api-types

Changements qui cassent le code

Version de l'API

discord.js v14 passe à l'API Discord v10 !

Ruptures courantes

Valeurs d'enum

Les zones qui acceptaient précédemment un type string ou number pour un paramètre d'enum n'accepteront maintenant que des number exclusivement.

De plus, les anciennes énumérations exportées par discord.js v13 et inférieur sont remplacées par les nouvelles énumérations de discord-api-types.

Différences nouvelles enum

La plupart de la différence entre les énumérations de discord.js et discord-api-types peut être résumée comme suit :

Les énumérations sont singulières, c'est-à-dire, ApplicationCommandOptionTypes -> ApplicationCommandOptionType
Les énumérations préfixées avec Message n'ont plus le préfixe Message, c'est-à-dire, MessageButtonStyles -> ButtonStyle
Les valeurs d'enum sont PascalCase plutôt que SCREAMING_SNAKE_CASE, c'est-à-dire, .CHAT_INPUT -> .ChatInput

Vous pourriez être tenté d'utiliser des number bruts (communément appelés nombres magiques) au lieu des valeurs d'enum. C'est fortement déconseillé. Les énumérations offrent plus de lisibilité et sont plus résistantes aux changements de l'API. Les nombres magiques peuvent obscurcir le sens de votre code de nombreuses façons, consultez cet article de blog si vous voulez plus de contexte sur les raisons pour lesquelles ils ne devraient pas être utilisés.

Ruptures d'enum courantes

Les zones comme l'initialisation de Client, les commandes slash JSON et les composants de message JSON devront probablement être modifiées pour tenir compte de ces changements :

Common Client Initialization Changes

const { Client, Intents } = require('discord.js'); 
const { Client, GatewayIntentBits, Partials } = require('discord.js'); 

const client = new Client({ intents: [Intents.FLAGS.GUILDS], partials: ['CHANNEL'] }); 
const client = new Client({ intents: [GatewayIntentBits.Guilds], partials: [Partials.Channel] });

Common Application Command Data changes

const { ApplicationCommandType, ApplicationCommandOptionType } = require('discord.js'); 

const command = {
	name: 'ping',
	type: 'CHAT_INPUT', 
	type: ApplicationCommandType.ChatInput, 
	options: [
		{
			name: 'option',
			description: 'A sample option',
			type: 'STRING', 
			type: ApplicationCommandOptionType.String, 
		},
	],
};

Common Button Data changes

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

const button = {
	label: 'test',
	style: 'PRIMARY', 
	style: ButtonStyle.Primary, 
	customId: '1234',
};

Suppression des gardes de type basées sur les méthodes

Canaux

Certaines méthodes de garde de type de canal qui se rétrécissaient à un type de canal ont été supprimées. Au lieu de cela, comparez la propriété type à un membre d'énumération ChannelType pour rétrécir les canaux.

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

channel.isText(); 
channel.type === ChannelType.GuildText; 

channel.isVoice(); 
channel.type === ChannelType.GuildVoice; 

channel.isDM(); 
channel.type === ChannelType.DM;

Constructeurs

Les constructeurs ne sont plus retournés par l'API comme ils l'étaient auparavant. Par exemple, vous envoyez un EmbedBuilder à l'API mais vous recevez un Embed avec les mêmes données de l'API. Cela peut affecter la façon dont votre code gère les structures reçues telles que les composants. Reportez-vous à la section des changements de composants de message pour plus de détails.

Ajouté disableValidators() et enableValidators() comme exportations de niveau supérieur qui désactivent ou activent la validation (activée par défaut).

Consolidation des paramètres `create()` & `edit()`

Divers méthodes create() et edit() sur les gestionnaires et les objets ont eu leurs paramètres consolidés. Les changements sont ci-dessous :

Guild#edit() prend maintenant reason dans le paramètre data
GuildChannel#edit() prend maintenant reason dans le paramètre data
GuildEmoji#edit() prend maintenant reason dans le paramètre data
Role#edit() prend maintenant reason dans le paramètre data
Sticker#edit() prend maintenant reason dans le paramètre data
ThreadChannel#edit() prend maintenant reason dans le paramètre data
GuildChannelManager#create() prend maintenant name dans le paramètre options
GuildChannelManager#createWebhook() (et autres canaux basés sur le texte) prend maintenant channel et name dans le paramètre options
GuildChannelManager#edit() prend maintenant reason comme faisant partie de data
GuildEmojiManager#edit() prend maintenant reason comme faisant partie de data
GuildManager#create() prend maintenant name comme faisant partie d'options
GuildMemberManager#edit() prend maintenant reason comme faisant partie de data
GuildMember#edit() prend maintenant reason comme faisant partie de data
GuildStickerManager#edit() prend maintenant reason comme faisant partie de data
RoleManager#edit() prend maintenant reason comme faisant partie d'options
Webhook#edit() prend maintenant reason comme faisant partie d'options
GuildEmojiManager#create() prend maintenant attachment et name comme faisant partie d'options
GuildStickerManager#create() prend maintenant file, name et tags comme faisant partie d'options

Activity

Les propriétés suivantes ont été supprimées car elles ne sont pas documentées par Discord :

Activity#id
Activity#platform
Activity#sessionId
Activity#syncId

Application

Application#fetchAssets() a été supprimé car il n'est plus supporté par l'API.

BitField

Les constituants BitField ont maintenant un suffixe BitField pour éviter les conflits de noms avec les noms d'énumération :

new Permissions(); 
new PermissionsBitField(); 

new MessageFlags(); 
new MessageFlagsBitField(); 

new ThreadMemberFlags(); 
new ThreadMemberFlagsBitField(); 

new UserFlags(); 
new UserFlagsBitField(); 

new SystemChannelFlags(); 
new SystemChannelFlagsBitField(); 

new ApplicationFlags(); 
new ApplicationFlagsBitField(); 

new Intents(); 
new IntentsBitField(); 

new ActivityFlags(); 
new ActivityFlagsBitField();

#FLAGS a été renommé en #Flags

CDN

Les méthodes qui retournent les URL CDN ont changé. Voici un exemple sur un utilisateur :

const url = user.displayAvatarURL({ dynamic: true, format: 'png', size: 1_024 }); 
const url = user.displayAvatarURL({ extension: 'png', size: 1_024 });

Les URL dynamiques utilisent ImageURLOptions et les URL statiques utilisent BaseImageURLOptions. Étant donné que les URL dynamiques sont retournées par défaut, cette option a été renommée en forceStatic qui force le retour d'une URL statique. De plus, format a été renommé en extension.

CategoryChannel

CategoryChannel#children n'est plus une Collection des canaux que contient la catégorie. C'est maintenant un gestionnaire (CategoryChannelChildManager). Cela signifie également que CategoryChannel#createChannel() a été déplacé au CategoryChannelChildManager.

Channel

Les gardes de type suivants ont été supprimés :

Channel#isText()
Channel#isVoice()
Channel#isDirectory()
Channel#isDM()
Channel#isGroupDM()
Channel#isCategory()
Channel#isNews()

Repórtez-vous à cette section pour plus de contexte.

La classe de base du canal est maintenant BaseChannel.

Client

L'option client restWsBridgeTimeout a été supprimée.

CommandInteractionOptionResolver

CommandInteractionOptionResolver#getMember() n'a plus de paramètre pour required. Voir cette demande de fusion pour plus d'informations.

Constants

De nombreux objets constants et tableaux de clés sont maintenant des exportations de niveau supérieur par exemple :

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

Les structures de constantes refactorées ont des noms de membres PascalCase par rapport aux noms de membres SCREAMING_SNAKE_CASE.
De nombreuses structures de constantes exportées ont été remplacées et renommées :

Opcodes; 
GatewayOpcodes; 

WSEvents; 
GatewayDispatchEvents; 

WSCodes; 
GatewayCloseCodes; 

InviteScopes; 
OAuth2Scopes;

Events

Les événements message et interaction ont été supprimés. Utilisez messageCreate et interactionCreate à la place.

applicationCommandCreate, applicationCommandDelete et applicationCommandUpdate ont tous été supprimés. Voir cette demande de fusion pour plus d'informations.

L'événement threadMembersUpdate émet maintenant les utilisateurs qui ont été ajoutés, les utilisateurs qui ont été supprimés et le thread respectivement.

GuildBanManager

Les développeurs doivent utiliser deleteMessageSeconds à la place de days et deleteMessageDays :

<GuildBanManager>.create('123456789', {
 days: 3
 deleteMessageDays: 3
 deleteMessageSeconds: 3 * 24 * 60 * 60
});

deleteMessageDays (introduit avec la version 14) et days sont tous deux dépréciés et seront supprimés dans l'avenir.

Guild

Guild#setRolePositions() et Guild#setChannelPositions() ont été supprimés. Utilisez RoleManager#setPositions() et GuildChannelManager#setPositions() respectivement.

Guild#maximumPresences n'a plus de valeur par défaut de 25 000.

Guild#me a été déplacé vers GuildMemberManager#me. Voir cette demande de fusion pour plus d'informations.

GuildAuditLogs & GuildAuditLogsEntry

GuildAuditLogs.build() a été supprimé car il a été considéré comme défaillant. Il n'y a pas d'alternative.

Les propriétés et méthodes suivantes ont été déplacées vers la classe GuildAuditLogsEntry :

GuildAuditLogs.Targets
GuildAuditLogs.actionType()
GuildAuditLogs.targetType()

GuildMember

GuildMember#pending est maintenant nullable pour tenir compte des membres de guílde partiels. Voir ce problème pour plus d'informations.

IntegrationApplication

IntegrationApplication#summary a été supprimé car il n'est plus supporté par l'API.

Interaction

Chaque fois qu'une interaction est répondue et que l'on récupère la réponse, elle pourrait éventuellement donner un APIMessage si la guílde n'était pas mise en cache. Cependant, les réponses d'interaction retournent maintenant toujours un InteractionCallbackResponse avec withResponse défini sur true.

La classe d'interaction de base est maintenant BaseInteraction.

Invite

Invite#inviter est maintenant un getter et résout les structures du cache.

MessageAttachment

MessageAttachment a été renommé en AttachmentBuilder.

new MessageAttachment(buffer, 'image.png'); 
new AttachmentBuilder(buffer, { name: 'image.png' });

MessageComponent

Les composants de message ont également été renommés. Ils n'ont plus le préfixe Message et ont maintenant un suffixe Builder :

const button = new MessageButton(); 
const button = new ButtonBuilder(); 

const selectMenu = new MessageSelectMenu(); 
const selectMenu = new StringSelectMenuBuilder(); 

const actionRow = new MessageActionRow(); 
const actionRow = new ActionRowBuilder(); 

const textInput = new TextInputComponent(); 
const textInput = new TextInputBuilder();

Les composants reçus de l'API ne sont plus directement mutables. Si vous souhaitez muter un composant de l'API, utilisez ComponentBuilder#from. Par exemple, si vous voulez rendre un bouton mutable :

const editedButton = receivedButton 
	.setDisabled(true); 
const { ButtonBuilder } = require('discord.js'); 
const editedButton = ButtonBuilder.from(receivedButton) 
	.setDisabled(true);

MessageManager

Le deuxième paramètre de MessageManager#fetch() a été supprimé. Le BaseFetchOptions que le deuxième paramètre était est maintenant fusionné dans le premier paramètre.

messageManager.fetch('1234567890', { cache: false, force: true }); 
messageManager.fetch({ message: '1234567890', cache: false, force: true });

MessageSelectMenu

MessageSelectMenu a été renommé en StringSelectMenuBuilder
StringSelectMenuBuilder#addOption() a été supprimé. Utilisez StringSelectMenuBuilder#addOptions() à la place.

MessageEmbed

MessageEmbed a maintenant été renommé en EmbedBuilder.
EmbedBuilder#setAuthor() accepte maintenant un seul objet EmbedAuthorOptions.
EmbedBuilder#setFooter() accepte maintenant un seul objet EmbedFooterOptions.
EmbedBuilder#addField() a été supprimé. Utilisez EmbedBuilder#addFields() à la place.

new MessageEmbed().addField('Inline field title', 'Some value here', true); 
new EmbedBuilder().addFields([ 
 { name: 'one', value: 'one', inline: true }, 
 { name: 'two', value: 'two', inline: true }, 
+]);

Modal a également été renommé et a maintenant un suffixe Builder :

const modal = new Modal(); 
const modal = new ModalBuilder();

PartialTypes

Le tableau de chaînes PartialTypes a été supprimé. Utilisez plutôt l'enum Partials.

De plus, il y a maintenant un nouveau partiel : Partials.ThreadMember.

Permissions

Les autorisations de thread USE_PUBLIC_THREADS et USE_PRIVATE_THREADS ont été supprimées car elles sont dépréciées dans l'API. Utilisez CREATE_PUBLIC_THREADS et CREATE_PRIVATE_THREADS respectivement.

ManageEmojisAndStickers a été déprécié en raison des changements d'API. Son remplacement est ManageGuildExpressions. Consultez cette demande de fusion pour plus d'informations.

PermissionOverwritesManager

Les remplacements sont maintenant clés par la clé de permission PascalCase plutôt que par la clé de permission SCREAMING_SNAKE_CASE.

Événements REST

apiRequest

Cet événement REST a été supprimé car discord.js utilise maintenant Undici comme gestionnaire de requête sous-jacent. Vous devez maintenant utiliser un Canal de diagnostics. Voici un exemple simple :

import diagnosticsChannel from 'node:diagnostics_channel';

diagnosticsChannel.channel('undici:request:create').subscribe((data) => {
	// If you use TypeScript, `data` may be casted as
	// `DiagnosticsChannel.RequestCreateMessage`
	// from Undici to receive type definitions.
	const { request } = data;
	console.log(request.method); // Log the method
	console.log(request.path); // Log the path
	console.log(request.headers); // Log the headers
	console.log(request); // Or just log everything!
});

Vous pouvez trouver d'autres exemples dans la documentation Undici Diagnostics Channel.

apiResponse

Cet événement REST a été renommé en response et déplacé vers Client#rest :

client.on('apiResponse', ...); 
client.rest.on('response', ...);

invalidRequestWarning

Cet événement REST a été déplacé vers Client#rest :

client.on('invalidRequestWarning', ...); 
client.rest.on('invalidRequestWarning', ...);

rateLimit

Cet événement REST a été renommé en rateLimited et déplacé vers Client#rest :

client.on('rateLimit', ...); 
client.rest.on('rateLimited', ...);

RoleManager

Role.comparePositions() a été supprimé. Utilisez RoleManager#comparePositions() à la place.

Sticker

Sticker#tags est maintenant une chaîne nullable (string | null). Précédemment, c'était un tableau de chaînes nullable (string[] | null). Voir cette demande de fusion pour plus d'informations.

ThreadChannel

L'aide MAX utilisé dans ThreadAutoArchiveDuration a été supprimé. Discord a depuis permis à n'importe quelle guílde d'utiliser n'importe quel temps d'archivage automatique, ce qui rend cet helper redondant.

ThreadMemberManager

Le deuxième paramètre de ThreadMemberManager#fetch() a été supprimé. Le BaseFetchOptions que le deuxième paramètre était est maintenant fusionné dans le premier paramètre. De plus, l'aide booléenne pour spécifier cache a été supprimée.

L'utilisation est maintenant la suivante :

|// Le deuxième paramètre est fusionné dans le premier paramètre.
|threadMemberManager.fetch('1234567890', { cache: false, force: true }); 
|threadMemberManager.fetch({ member: '1234567890', cache: false, force: true }); 
|
|// Le seul booléen a été supprimé. On doit être explicite ici.
|threadMemberManager.fetch(false); 
|threadMemberManager.fetch({ cache: false });

Util

Util.removeMentions() a été supprimé. Pour contrôler les mentions, vous devriez utiliser allowedMentions sur BaseMessageOptions à la place.

Util.splitMessage() a été supprimé. Cette méthode utilitaire est quelque chose que le développeur doit faire lui-même.

Util.resolveAutoArchiveMaxLimit() a été supprimé. Discord a depuis permis à n'importe quelle guílde d'utiliser n'importe quel temps d'archivage automatique, ce qui rend cette méthode redondante.

D'autres fonctions dans Util ont été déplacées vers des exportations de niveau supérieur afin que vous puissiez les importer directement depuis discord.js.

import { Util } from 'discord.js'; 
Util.escapeMarkdown(message); 
import { escapeMarkdown } from 'discord.js'; 
escapeMarkdown(message);

Les champs `.deleted` ont été supprimés

Vous ne pouvez plus utiliser la propriété deleted pour vérifier si une structure a été supprimée. Voir ce problème pour plus d'informations.

VoiceChannel

VoiceChannel#editable a été supprimé. Vous devriez utiliser GuildChannel#manageable à la place.

VoiceRegion

VoiceRegion#vip a été supprimé car il ne fait plus partie de l'API.

Webhook

Le deuxième paramètre de Webhook#fetchMessage() ne permet plus de passer un booléen. L'option cache dans WebhookFetchMessageOptions doit être utilisée à la place.

Caractéristiques

ApplicationCommand

Les commandes NSFW sont supportées.

Pièce jointe

Soutien ajouté pour les champs de métadonnées des messages vocaux.

AutocompleteInteraction

AutocompleteInteraction#commandGuildId a été ajouté, c'est l'identifiant de la guilde sur laquelle la commande d'application invoquée est enregistrée.

BaseChannel

Soutien ajouté pour BaseChannel#flags.

Les canaux de magasin ont été supprimés car ils ne font plus partie de l'API.

BaseChannel#url a été ajouté, c'est un lien vers un canal, tout comme dans le client.

De plus, de nouveaux typeguards ont été ajoutés :

BaseChannel#isDMBased()
BaseChannel#isTextBased()
BaseChannel#isVoiceBased()

BaseInteraction

Ajouté BaseInteraction#isRepliable() pour vérifier si une interaction donnée peut être répondue.

ClientApplication

Soutien ajouté pour les métadonnées de connexion de rôle.

Collection

Ajouté Collection#merge() et Collection#combineEntries().
Nouveau type : ReadonlyCollection qui indique une Collection immuable.

Collector

Un nouvel événement ignore a été ajouté qui est émis chaque fois qu'un élément n'est pas collecté par le collecteur.

Les options du collecteur de composants utilisent maintenant les valeurs enum ComponentType :

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

const collector = interaction.channel.createMessageComponentCollector({
	filter: collectorFilter,
	componentType: 'BUTTON', 
	componentType: ComponentType.Button, 
	time: 20_000,
});

CommandInteraction

CommandInteraction#commandGuildId a été ajouté, c'est l'ID de la guílde sur laquelle la commande d'application invoquée est enregistrée.

CommandInteractionOptionResolver

CommandInteractionOptionResolver#getChannel() a maintenant un troisième paramètre qui affine le type de canal.

Events

Soutien ajouté pour l'événement guildAuditLogEntryCreate.

ForumChannel

Soutien ajouté pour les canaux de forum.

Soutien ajouté pour ForumChannel#defaultForumLayout.

Guild

Ajouté Guild#setMFALevel() qui définit le niveau MFA de la guílde.

Ajouté Guild#maxVideoChannelUsers qui indique le nombre maximal d'utilisateurs de canal vidéo.

Ajouté Guild#maxStageVideoChannelUsers qui indique le nombre maximal d'utilisateurs de canal vidéo pour les canaux d'activité.

Ajouté Guild#disableInvites() qui désactive les invitations de la guílde.

Soutien ajouté pour le paramètre after dans Guild#fetchAuditLogs().

Sur cette page