Écouteurs

Comment utiliser les écouteurs

Necord prend en charge l'interaction avec tous les événements Discord via les décorateurs @On et @Once. Ces décorateurs peuvent être utilisés dans n'importe quelle classe injectable, comme des services ou des providers personnalisés.

app.service.ts

import { Injectable, Logger } from '@nestjs/common';
import { Once, On, Context, ContextOf } from 'necord';

@Injectable()
export class AppService {
    private readonly logger = new Logger(AppService.name);

    @Once('clientReady')
    public onReady(@Context() [client]: ContextOf<'clientReady'>) {
        this.logger.log(`Bot logged in as ${client.user.username}`);
    }

    @On('warn')
    public onWarn(@Context() [message]: ContextOf<'warn'>) {
        this.logger.warn(message);
    }
}

Avertissement

Si vous utilisez des filtres, des gardes ou des intercepteurs globaux, ils seront déclenchés une fois par événement ! Cela signifie que si vous répondez au message dans des gardes, vous pouvez rencontrer des problèmes de réponses dupliquées ou d'interactions invalides. Consultez les métadonnées de NecordExecutionContext.getDiscovery() pour en savoir plus sur le contexte actuel.

Contexte

Vous avez peut-être remarqué le décorateur @Context dans le dernier extrait : il est utilisé pour injecter le contexte de l'événement dans la méthode. Comme il existe de nombreux types d'événements, son type doit être déduit du type ContextOf<type: string>.

Vous pouvez accéder aux variables de contexte en utilisant le décorateur @Context() dans votre fonction, ce qui remplira la variable avec un tableau d'arguments.

app.service.ts

@On('messageCreate')
public onMessageCreate(@Context() [message]: ContextOf<'messageCreate'>) {
    console.log(message.content);
}

Événements personnalisés

Necord prend en charge nativement tous les événements fournis par discord.js. Vous pouvez également créer des événements personnalisés à l'aide des décorateurs @CustomListenerHandler et @CustomListener.

user-update.handler.ts

import { Injectable } from '@nestjs/common';
import { CustomListener, CustomListenerHandler, BaseHandler, ContextOf, createCustomOnDecorator } from 'necord';
import { User } from 'discord.js';

export type CustomUserUpdateEvents = {
	userAvatarUpdate: [user: User, oldAvatar: string, newAvatar: string];
};

export type ContextOfCustomUserUpdate<K extends keyof E, E = CustomUserUpdateEvents> = E[K];

export const OnCustomUserUpdate = createCustomOnDecorator<CustomUserUpdateEvents>();

@Injectable()
@CustomListener('userUpdate')
export class UserUpdateHandler extends BaseHandler<CustomUserUpdateEvents> {
	@CustomListenerHandler()
	public handleUserAvatarUpdate([oldUser, newUser]: ContextOf<'userUpdate'>) {
		if (oldUser.partial) return;

		if (oldUser.displayAvatarURL() !== newUser.displayAvatarURL()) {
			this.emit(
				'userAvatarUpdate',
				newUser,
				oldUser.displayAvatarURL(),
				newUser.displayAvatarURL()
			);
		}
	}
}

Astuce

De plus, vous pouvez créer plusieurs gestionnaires d'événements personnalisés dans une seule classe en ajoutant d'autres méthodes avec le décorateur @CustomListenerHandler().

Vous pouvez ensuite écouter l'événement personnalisé à l'aide du décorateur @OnCustomUserUpdate.

app.service.ts

import { Injectable } from '@nestjs/common';
import { OnCustomUserUpdate, ContextOfCustomUserUpdate, Context } from './user-update.handler';

@Injectable()
export class AppService {
	@OnCustomUserUpdate('userAvatarUpdate')
	public onAvatarUpdate(@Context() context: ContextOfCustomUserUpdate<'userAvatarUpdate'>) {
		const [user, oldAvatar, newAvatar] = context;
		console.log(`User ${user.username} changed avatar from ${oldAvatar} to ${newAvatar}`);
	}
}

Vous pouvez également utiliser @On<CustomUserUpdateEvents>('userAvatarUpdate') au lieu de créer un nouveau décorateur. Mais créer un nouveau décorateur est plus pratique et plus propre.

Liste des événements personnalisés

Voici la liste de tous les événements personnalisés fournis par Necord. Ils sont accessibles via le décorateur @On.

Événements de salon

Nom de l'événement	Description
guildChannelPermissionsUpdate	Émis chaque fois que la surcharge des permissions d'un salon pour un serveur est mise à jour.

Événements de serveur

Nom de l'événement	Description
guildBoostLevelUp	Émis chaque fois que le niveau de boost d'un serveur augmente.
guildBoostLevelDown	Émis chaque fois que le niveau de boost d'un serveur diminue.
guildBannerAdd	Émis chaque fois que la bannière d'un serveur est ajoutée.
guildAfkChannelAdd	Émis chaque fois que le salon AFK d'un serveur est ajouté.
guildVanityURLAdd	Emitted whenever a guild's vanity URL is added.
guildVanityURLUpdate	Emitted whenever a guild's vanity URL is updated.
guildVanityURLRemove	Emitted whenever a guild's vanity URL is removed.
guildFeaturesUpdate	Emitted whenever a guild's features are updated.
guildAcronymUpdate	Emitted whenever a guild's acronym is updated.
guildOwnerUpdate	Emitted whenever a guild's owner is updated.
guildPartnerAdd	Emitted whenever a guild's is partner of discord now
guildPartnerRemove	Emitted whenever a guild's is no longer partner of discord
guildVerificationAdd	Emitted whenever a guild's verification level is added.
guildVerificationRemove	Emitted whenever a guild's verification level is removed.

Guild Audit Log Events

Nom de l'événement	Description
guildAuditLogEntryAdd	Emitted whenever an entry is added to the audit log.
guildAuditLogEntryUpdate	Emitted whenever an entry is updated in the audit log.
guildAuditLogEntryDelete	Emitted whenever an entry is removed from the audit log.
guildAuditLogEntryWebhookCreate	Emitted whenever a webhook is created in the audit log.
guildAuditLogEntryWebhookUpdate	Emitted whenever a webhook is updated in the audit log.
guildAuditLogEntryWebhookDelete	Emitted whenever a webhook is deleted in the audit log.

Guild Member Events

Nom de l'événement	Description
guildMemberBoost	Emitted whenever a member's boost is activated.
guildMemberUnboost	Emitted whenever a member's boost is deactivated.
guildMemberRoleAdd	Emitted whenever a role is added to a member.
guildMemberRoleRemove	Emitted whenever a role is removed from a member.
guildMemberNicknameUpdate	Emitted whenever a member's nickname is updated.
guildMemberEntered	Emitted whenever a member enters a guild.
guildMemberAvatarAdd	Emitted whenever a member's avatar is added.
guildMemberAvatarRemove	Emitted whenever a member's avatar is removed.
guildMemberAvatarUpdate	Emitted whenever a member's avatar is updated.

Role Update Events

Nom de l'événement	Description
rolePositionUpdate	Emitted whenever a role's position is updated.
rolePermissionsUpdate	Emitted whenever a role's permissions are updated.
roleIconAdd	Emitted whenever a role's icon is added.
roleIconRemove	Emitted whenever a role's icon is removed.
roleIconUpdate	Emitted whenever a role's icon is updated.

Thread Update Events

Nom de l'événement	Description
threadStateUpdate	Emitted whenever a thread's state is updated.
threadNameUpdate	Emitted whenever a thread's name is updated.
threadLockStateUpdate	Emitted whenever a thread's lock state is updated.
threadRateLimitPerUserUpdate	Emitted whenever a thread's rate limit per user is updated.
threadAutoArchiveDurationUpdate	Emitted whenever a thread's auto archive duration is updated.

Message Events

Nom de l'événement	Description
messagePinned	Emitted whenever a message is pinned.
messageContentEdited	Emitted whenever a message is updated.

Presence Events

Nom de l'événement	Description
guildMemberOffline	Emitted whenever a member goes offline.
guildMemberOnline	Emitted whenever a member goes online.

User Events

Nom de l'événement	Description
userAvatarUpdate	Emitted whenever a user's avatar is updated.
userUsernameUpdate	Emitted whenever a user's username is updated.
userDiscriminatorUpdate	Emitted whenever a user's discriminator is updated.
userFlagsUpdate	Emitted whenever a user's flags are updated.
userPrimaryGuildUpdate	Emitted whenever a user's primary guild is updated.

Voice Events

Nom de l'événement	Description
voiceChannelJoin	Emitted whenever a member joins a voice channel.
voiceChannelLeave	Emitted whenever a member leaves a voice channel.
voiceChannelSwitch	Emitted whenever a member switches voice channel.
voiceChannelMutestate	Emitted whenever a member is muted or deafened in a voice channel.
voiceChannelUnmute	Emitted whenever a member is unmuted in a voice channel.
voiceChannelDeaf	Emitted whenever a member is deafened in a voice channel.
voiceChannelUndeaf	Emitted whenever a member is undeafened in a voice channel.
voiceStreamingStart	Emitted whenever a member starts streaming.
voiceStreamingStop	Emitted whenever a member stops streaming.