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écorateurs Background Title Decorator Types and Application Locations Center: Class @ClassDecorator Class Decorator Arrows to all directions Top: Property Decorator Property Decorator @propertyDecorator Right: Method Decorator Method Decorator @methodDecorator Bottom: Parameter Decorator Parameter Decorator @paramDecorator Lower Right: Accessor Decorator Accessor Decorator @getterDecorator Decorator Factory Explanation Decorator Factory A decorator factory is a function that returns a decorator function, enabling configuration through parameters. Example: function color(code: string) { return function(target) { ... }; } → @color("34") Arrow marker

Introduction 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

// Définir une fonction de décorateur 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

// Définir une fabrique de 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

// Fabrique de 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é

// Fabrique de décorateur 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

// Décorateur de paramètre
// 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

// Fabrique de décorateurs : reçoit les paramètres de configuration et renvoie une fonction de décorateur
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

// Empiler plusieurs 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

// Décorateur de journalisation
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

// Simuler le rôle de l'utilisateur actuel
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