Décorateurs TypeScript
Les décorateurs sont une fonctionnalité expérimentale de TypeScript.
Ils permettent aux développeurs d'ajouter des fonctionnalités supplémentaires aux classes, méthodes, propriétés ou paramètres sans modifier la classe d'origine.
Un décorateur est essentiellement une fonction qui peut être appelée au moment de l'exécution pour modifier le comportement de l'objet cible.
Diagramme SVG : Types de décorateursIntroduction aux décorateurs
Les décorateurs utilisent le symbole `@` comme sucre syntaxique et peuvent être attachés à des classes, méthodes, accesseurs, propriétés ou paramètres.
Ce modèle est couramment utilisé dans le développement de frameworks ; par exemple, Angular, TypeORM, etc., utilisent largement les décorateurs pour implémenter l'injection de dépendances, la validation des données et d'autres fonctionnalités.
Remarque :Les décorateurs sont actuellement une fonctionnalité expérimentale et doivent être explicitement activés dans tsconfig.json. Lorsque vous les utilisez en production, veuillez confirmer le niveau de prise en charge des fonctionnalités expérimentales par le projet.
Configuration pour activer les décorateurs
Avant d'utiliser des décorateurs, vous devez activer les options du compilateur concernées dans le fichier de configuration TypeScript tsconfig.json.
Configuration de tsconfig.json
"compilerOptions": {
// Activer la syntaxe des décorateurs
"experimentalDecorators": true,
// Activer les métadonnées de décorateur (utilisées pour les frameworks d'injection de dépendances)
"emitDecoratorMetadata": true
}
}
Description du paramètre :
- experimentalDecorators:Active la prise en charge de la syntaxe des décorateurs ; c'est un prérequis pour utiliser les décorateurs.
- emitDecoratorMetadata:Génère des métadonnées de décorateur dans le JavaScript compilé pour une utilisation par les frameworks d'injection de dépendances.
Décorateurs de classe
Les décorateurs de classe sont appliqués au constructeur de la classe et peuvent modifier la définition de la classe ou ajouter une logique de traitement supplémentaire.
Un décorateur de classe reçoit un paramètre : le constructeur de la classe cible.
Utilisation de base des décorateurs de classe
// Le paramètre target est le constructeur de la classe décorée
function sealed(target: Function) {
// Afficher le nom de la classe à laquelle le décorateur est appliqué
console.log("Décorateur appliqué à : " + target.name);
// Utiliser Object.seal pour verrouiller le constructeur et le prototype
// Empêcher l'ajout ou la suppression de propriétés à l'exécution
Object.seal(target);
Object.seal(target.prototype);
}
// Utiliser la syntaxe @ pour appliquer le décorateur à la classe
@sealed
class Person {
name: string;
constructor(name: string) {
this.name = name;
}
}
// Créer une instance pour les tests
var person = new Person("EXAMPLE");
console.log("Created: " + person.name);
// Essayer d'ajouter une nouvelle propriété (sera empêché car la classe est scellée)
// person.age = 25; // échoue silencieusement
Sortie :
装饰器 applied to: Person 创建: EXAMPLE
Explication :
Les décorateurs de classe s'exécutent au moment de la définition de la classe et sont généralement utilisés pour modifier le comportement de la classe, ajouter des métadonnées ou implémenter l'AOP (programmation orientée aspect).
Décorateurs de méthode
Les décorateurs de méthode sont appliqués aux méthodes de classe et peuvent modifier le descripteur de propriété de la méthode.
Un décorateur de méthode reçoit trois paramètres : l'objet cible, le nom de la propriété et le descripteur de propriété.
Utilisation de base des décorateurs de méthode
// Retourner une fonction décorateur
function enumerable(value: boolean) {
// Retourne une fonction décorateur qui reçoit trois paramètres
return function (
target: any, // L'objet prototype de la classe conteneur
propertyKey: string, // Le nom de la méthode
descriptor: PropertyDescriptor // Le descripteur de propriété
) {
// Modifier l'attribut enumerable de la propriété
// false signifie que la méthode n'est pas énumérable
descriptor.enumerable = value;
};
}
class Greeter {
greeting: string;
constructor(message: string) {
this.greeting = message;
}
// Appliquer le décorateur pour définir la méthode comme non énumérable
@enumerable(false)
greet() {
return "Hello, " + this.greeting;
}
}
var g = new Greeter("World");
// Vérifier si la méthode greet est énumérable
console.log("Méthode énumérable : " + g.propertyIsEnumerable("greet"));
// Parcourir les propriétés de l'objet
for (var key in g) {
console.log("Propriétés : " + key);
}
Sortie :
方法可枚举: false
Astuce :PropertyDescriptor contient des attributs tels que enumerable, configurable, writable et value, qui peuvent être modifiés selon les besoins.
Décorateurs d'accesseurs
Les décorateurs d'accesseurs sont appliqués aux méthodes getter et setter d'une classe.
Comme les décorateurs de méthode, les décorateurs d'accesseurs peuvent également modifier le descripteur de propriété.
Utilisation des décorateurs d'accesseur
function configurable(value: boolean) {
return function (
target: any,
propertyKey: string,
descriptor: PropertyDescriptor
) {
// Modifier l'attribut configurable de la propriété
// false signifie que l'accesseur ne peut pas être reconfiguré ni supprimé
descriptor.configurable = value;
};
}
class Point {
private _x: number = 0;
private _y: number = 0;
// Utiliser le décorateur pour verrouiller le getter
@configurable(false)
get x() {
return this._x;
}
@configurable(false)
get y() {
return this._y;
}
set x(value: number) {
this._x = value;
}
set y(value: number) {
this._y = value;
}
}
var point = new Point();
point.x = 10;
point.y = 20;
console.log("Coordonnées : (" + point.x + ", " + point.y + ")");
Explication :
Les décorateurs d'accesseur ne peuvent pas être appliqués à la fois au getter et au setter d'une même propriété ; un seul d'entre eux peut être choisi.
Décorateurs de propriété
Les décorateurs de propriété sont appliqués aux définitions de propriété d'une classe.
Un décorateur de propriété reçoit deux paramètres : l'objet cible et le nom de la propriété.
Utilisation des décorateurs de propriété
function format(formatString: string) {
return function (
target: any, // L'objet prototype de la classe
propertyKey: string // Le nom de la propriété
) {
// Stocker les métadonnées sur l'objet cible
// Utiliser propertyKey + "_format" comme nom de clé pour éviter les conflits
Object.defineProperty(target, propertyKey + "_format", {
value: formatString,
writable: false,
enumerable: false,
configurable: true
});
};
}
class User {
// Appliquer le décorateur de propriété pour spécifier le format de date
@format("YYYY-MM-DD")
birthDate: string;
constructor(birthDate: string) {
this.birthDate = birthDate;
}
}
var user = new User("1990-01-01");
console.log("Date de naissance : " + user.birthDate);
// Accéder aux métadonnées stockées
console.log("Format de date : " + (user as any).birthDate_format);
Sortie :
出生日期: 1990-01-01 日期格式: YYYY-MM-DD
Décorateurs de paramètres
Les décorateurs de paramètres sont appliqués aux paramètres des méthodes de classe et peuvent ajouter des métadonnées ou des marqueurs aux paramètres.
Un décorateur de paramètre reçoit trois paramètres : l'objet cible, le nom de la méthode et l'index du paramètre dans la fonction.
Utilisation des décorateurs de paramètres
// Utilisé pour enregistrer les informations de paramètre ou effectuer une validation
function logParameter(
target: any, // L'objet prototype de la classe
propertyKey: string, // Le nom de la méthode
parameterIndex: number // La position de l'index du paramètre dans la fonction (à partir de 0)
) {
console.log("Décorateur de paramètre : " + propertyKey +
" " + (parameterIndex + 1) + "ème paramètre");
}
class Greeter {
greeting: string;
constructor(greeting: string) {
this.greeting = greeting;
}
// Utilisez la syntaxe @ avant le paramètre pour appliquer le décorateur
greet(@logParameter name: string) {
return this.greeting + ", " + name;
}
}
var greeter = new Greeter("Bonjour");
greeter.greet("EXEMPLE");
Sortie :
参数装饰器: greet 第 1 个参数
Fabrique de décorateurs
Une fabrique de décorateurs est une fonction qui renvoie une fonction décorateur.
Grâce à une fabrique de décorateurs, vous pouvez transmettre des paramètres personnalisés lors de l'application du décorateur, ce qui permet une configuration plus flexible.
Fabrique de décorateurs pour journaux colorés
function color(colorCode: string) {
// colorCode est le code de couleur dans les séquences d'échappement ANSI
// Par exemple : 34 = bleu, 31 = rouge, 32 = vert
return function (
target: any,
propertyKey: string,
descriptor: PropertyDescriptor
) {
// Sauvegarder la méthode d'origine
var originalMethod = descriptor.value;
// Redéfinir la méthode pour ajouter de la couleur
descriptor.value = function (...args: any[]) {
// Appeler la méthode d'origine pour obtenir la valeur de retour
var result = originalMethod.apply(this, args);
// Si dans un environnement de terminal, ajouter de la couleur à la sortie
// Format de séquence d'échappement ANSI : \x1b[code couleur m contenu \x1b[0m
return "\x1b[" + colorCode + "m" + result + "\x1b[0m";
};
};
}
class Logger {
// Utilisez une fabrique de décorateur, passez le code couleur bleu 34
@color("34")
log(message: string): string {
return message;
}
@color("31")
error(message: string): string {
return message;
}
@color("32")
success(message: string): string {
return message;
}
}
var logger = new Logger();
console.log(logger.log("Ceci est un journal bleu"));
console.log(logger.error("Ceci est une erreur rouge"));
console.log(logger.success("Ceci est un succès vert"));
Résultat de l'exécution :
This is blue log (displayed as blue in terminal) This is red error (displayed as red in terminal) This is green success (displayed as green in terminal)
Explication :La fabrique de décorateurs est la forme la plus couramment utilisée en développement réel. Elle permet de passer des paramètres lors de l'application des décorateurs, ce qui permet la configuration.
Ordre d'exécution des décorateurs
Lorsqu'une classe possède plusieurs décorateurs, l'ordre d'exécution suit des règles spécifiques.
- Les décorateurs sont appliqués de bas en haut
- Plusieurs décorateurs du même type s'exécutent de droite à gauche
- Les décorateurs de paramètres s'exécutent avant les décorateurs de méthodes
Exemple d'ordre d'exécution des décorateurs
function first() {
console.log("first decorator");
return function (target: any) {
console.log("first decorator function");
};
}
function second() {
console.log("deuxième décorateur");
return function (target: any) {
console.log("deuxième fonction décorateur");
};
}
@first()
@second()
class MyClass {
name: string;
}
var obj = new MyClass();
Résultat de l'exécution :
second 装饰器 first 装饰器 second 装饰器函数 first 装饰器函数
Explication :
Les définitions des fonctions décorateur s'exécutent en premier (console.log), puis les fonctions décorateur s'exécutent dans l'ordre du bas vers le haut.
Scénarios d'application concrets
Les décorateurs ont un large éventail de scénarios d'application dans des projets réels.
Journalisation
Enregistrer automatiquement les journaux d'appels de méthode.
Exemple
function log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
var originalMethod = descriptor.value;
descriptor.value = function (...args: any[]) {
console.log("Appel de la méthode : " + propertyKey + ", paramètres : " + JSON.stringify(args));
var result = originalMethod.apply(this, args);
console.log("La méthode a retourné : " + JSON.stringify(result));
return result;
};
}
class MathService {
@log
add(a: number, b: number): number {
return a + b;
}
@log
multiply(a: number, b: number): number {
return a * b;
}
}
var math = new MathService();
console.log("Résultat du calcul : " + math.add(5, 3));
Résultat de l'exécution :
调用方法: add,参数: [5,3] 方法返回: 8 计算结果: 8
Vérification des permissions
Implémenter la vérification des permissions au niveau des méthodes.
Exemple
var currentUser = { role: "admin" };
// Décorateur de permission
function requireRole(role: string) {
return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
var originalMethod = descriptor.value;
descriptor.value = function (...args: any[]) {
if (currentUser.role !== role) {
console.log("Permissions insuffisantes, impossible d'exécuter " + propertyKey);
return null;
}
return originalMethod.apply(this, args);
};
};
}
class AdminService {
@requireRole("admin")
deleteUser(id: number): string {
return "Suppression de l'utilisateur " + id + " réussie";
}
@requireRole("admin")
viewUser(id: number): string {
return "Affichage de l'utilisateur " + id;
}
}
var admin = new AdminService();
console.log(admin.viewUser(1));
console.log(admin.deleteUser(1));
// Simuler un utilisateur standard
currentUser = { role: "user" };
console.log(admin.deleteUser(2));
Résultat de l'exécution :
查看用户 1 删除用户 1 成功 权限不足,无法执行 deleteUser
Notes
- Fonctionnalité expérimentale :Les décorateurs sont une proposition _stade 3_ d'ECMAScript et constituent encore actuellement une fonctionnalité expérimentale
- Options du compilateur :Il faut activer experimentalDecorators
- Définitions de type :Une version plus récente de TypeScript est requise pour une prise en charge complète des types
- Remarque sur le débogage :Les décorateurs s'exécutent au moment de la compilation, et certains outils de débogage peuvent ne pas associer correctement les emplacements source
Recommandation :Lorsque vous utilisez des décorateurs dans un projet, il est recommandé de créer des classes utilitaires ou des bibliothèques de fonctions dédiées aux décorateurs afin de gérer uniformément la définition et l'utilisation des décorateurs.
Résumé
Les décorateurs TypeScript offrent une puissante capacité de métaprogrammation.
- Décorateurs de classe :Modifient la classe elle-même, peuvent être utilisés pour ajouter des métadonnées, verrouiller des classes, etc.
- Décorateurs de méthode :Modifient les propriétés de méthode, peuvent être utilisés pour la journalisation, la validation, etc.
- Décorateurs d'accesseur :Modifient les getter/setter, contrôlent la configurabilité des propriétés
- Décorateurs de propriété :Ajoutent des métadonnées aux propriétés
- Décorateurs de paramètre :Marquent ou valident les paramètres de méthode
- Fabrique de décorateur:Obtenir une configuration de décorateur plus flexible grâce à la paramétrisation
Autres extensions