TypeScript學習筆記（九）：裝飾器（Decorators）

裝飾器簡介

裝飾器（Decorators）為我們在類的聲明及成員上通過元編程語法添加標注提供了一種方式。 

需要注意的是：裝飾器是一項實驗性特性，在未來的版本中可能會發生改變。

若要啟用實驗性的裝飾器特性，你必須在命令行或tsconfig.json里啟用experimentalDecorators編譯器選項：

{
    "compilerOptions": {
        "target": "ES5",
        "experimentalDecorators": true
    }
}

如何定義

裝飾器使用@expression這種形式，expression求值后必須為一個函數，它會在運行時被調用，被裝飾的聲明信息做為參數傳入。

裝飾器組合

多個裝飾器可以同時應用到一個聲明上，就像下面的示例：

書寫在同一行上：

@f @g x

書寫在多行上：

@f
@g
x

在TypeScript里，當多個裝飾器應用在一個聲明上時會進行如下步驟的操作：

1. 由上至下依次對裝飾器表達式求值。
2. 求值的結果會被當作函數，由下至上依次調用。

類裝飾器

類裝飾器在類聲明之前被聲明（緊靠着類聲明）。 類裝飾器應用於類構造函數，可以用來監視，修改或替換類定義。 類裝飾器不能用在聲明文件中( .d.ts)，也不能用在任何外部上下文中（比如declare的類）。

類裝飾器表達式會在運行時當作函數被調用，類的構造函數作為其唯一的參數。

我們來看一個例子：

function sealed(constructor: Function) {
    Object.seal(constructor);
    Object.seal(constructor.prototype);
}

@sealed
class MyClass {
    a: number = 0;
    b: string = "hello";
}

var obj = new MyClass();
// obj.c = true; // 編譯報錯

通過類裝飾器我們可以對類的原型對象做一定的修改。

編譯后的源碼：

"use strict";
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
function sealed(constructor) {
    Object.seal(constructor);
    Object.seal(constructor.prototype);
}
var MyClass = (function () {
    function MyClass() {
        this.a = 0;
        this.b = "hello";
    }
    MyClass = __decorate([
        sealed
    ], MyClass);
    return MyClass;
}());
var obj = new MyClass();
// obj.c = true; // 編譯報錯 

這里我們只關注傳遞到裝飾函數的constructor參數：就是我們定義的MyClass對象。

方法裝飾器

方法裝飾器聲明在一個方法的聲明之前（緊靠着方法聲明）。 它會被應用到方法的 屬性描述符上，可以用來監視，修改或者替換方法定義。 方法裝飾器不能用在聲明文件( .d.ts)，重載或者任何外部上下文（比如declare的類）中。

方法裝飾器表達式會在運行時當作函數被調用，傳入下列3個參數：

1. 對於靜態成員來說是類的構造函數，對於實例成員是類的原型對象。
2. 成員的名字。
3. 成員的屬性描述符。

注意：如果代碼輸出目標版本小於ES5，屬性描述符將會是undefined。

我們來看下面的例子：

function methodDecorator(param1: boolean, param2?: string) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        console.log(param1 + ", " + param2 + ", " + target + ", " + propertyKey + ", " + JSON.stringify(descriptor));
    };
}

class MyClass {
    @methodDecorator(true, "this is static")
    public static sFunc(): void {
        console.log("call static method");
    }

    @methodDecorator(false)
    public func(): void {
        console.log("call method");
    }
}

MyClass.sFunc();
MyClass.sFunc();

var obj = new MyClass();
obj.func();
obj.func();

輸出如下：

false, undefined, [object Object], func, {"writable":true,"enumerable":true,"configurable":true}
true, this is static, function MyClass() {
    }, sFunc, {"writable":true,"enumerable":true,"configurable":true}
call static method
call static method
call method
call method

我們可以發現，方法裝飾器返回的函數會在解釋類的對應方法時被調用一次，並可以得到裝飾器的參數和被裝飾的方法的相關信息。

裝飾器方法的調用只會在加載代碼時執行一次，調用被裝飾的方法不會觸發裝飾器方法。

編譯后的源碼：

"use strict";
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
function methodDecorator(param1, param2) {
    return function (target, propertyKey, descriptor) {
        console.log(param1 + ", " + param2 + ", " + target + ", " + propertyKey + ", " + JSON.stringify(descriptor));
    };
}
var MyClass = (function () {
    function MyClass() {
    }
    MyClass.sFunc = function () {
        console.log("call static method");
    };
    MyClass.prototype.func = function () {
        console.log("call method");
    };
    __decorate([
        methodDecorator(false)
    ], MyClass.prototype, "func", null);
    __decorate([
        methodDecorator(true, "this is static")
    ], MyClass, "sFunc", null);
    return MyClass;
}());
MyClass.sFunc();
MyClass.sFunc();
var obj = new MyClass();
obj.func();
obj.func();

這里我們只關注傳遞到裝飾函數的target參數：

裝飾靜態方法時是定義的MyClass對象；

裝飾動態方法時是定義的MyClass對象的原型對象，在24行這里“], MyClass.prototype, "func", null);”，我們知道，MyClass的原型對象在沒有繼承時是一個Object對象，該對象是所有MyClass的實例共用的，在有繼承時，MyClass的原型對象會是一個新創建的對象，並且會對父類的方法進行淺復制的對象，如下：

var __extends = (this && this.__extends) || (function () {
    var extendStatics = Object.setPrototypeOf ||
        ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
        function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
    return function (d, b) {
        extendStatics(d, b);
        function __() { this.constructor = d; }
        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
    };
})();
// ...
var MyClass = (function () {
    function MyClass() {
    }
    // ...
    return MyClass;
}());
var MyClass2 = (function (_super) {
    __extends(MyClass2, _super);
    function MyClass2() {
        return _super !== null && _super.apply(this, arguments) || this;
    }
    // ...
    return MyClass2;
}(MyClass));

此時如果操作target對象，比如為該對象添加一個屬性，那么這個屬性MyClass類的所有實例都可以訪問到。

訪問器裝飾器

訪問器裝飾器聲明在一個訪問器的聲明之前（緊靠着訪問器聲明）。 訪問器裝飾器應用於訪問器的 屬性描述符並且可以用來監視，修改或替換一個訪問器的定義。 訪問器裝飾器不能用在聲明文件中（.d.ts），或者任何外部上下文（比如 declare的類）里。

訪問器裝飾器表達式會在運行時當作函數被調用，傳入下列3個參數：

1. 對於靜態成員來說是類的構造函數，對於實例成員是類的原型對象。
2. 成員的名字。
3. 成員的屬性描述符。

注意:如果代碼輸出目標版本小於ES5，Property Descriptor將會是undefined。

同時TypeScript不允許同時裝飾一個成員的get和set訪問器。取而代之的是，一個成員的所有裝飾的必須應用在文檔順序的第一個訪問器上。這是因為，在裝飾器應用於一個屬性描述符時，它聯合了get和set訪問器，而不是分開聲明的。

我們來看一個例子：

function methodDecorator(param1: boolean, param2?: string) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        console.log(param1 + ", " + param2 + ", " + target + ", " + propertyKey + ", " + JSON.stringify(descriptor));
    };
}

class MyClass {
    private static _myName: string;

    @methodDecorator(true, "this is static")
    public static set myName(value: string) {
        this._myName = value;
    }

    public static get myName(): string {
        return this._myName;
    }

    private _age: number;

    @methodDecorator(false)
    public set age(value: number) {
        this._age = value;
    }

    public get age(): number {
        return this._age;
    }
}

MyClass.myName = "hello";
console.log(MyClass.myName);

var obj = new MyClass();
obj.age = 28;
console.log(obj.age);

輸出如下：

false, undefined, [object Object], age, {"enumerable":true,"configurable":true}
true, this is static, function MyClass() {
    }, myName, {"enumerable":true,"configurable":true}
hello
28

我們可以發現，訪問器裝飾器返回的函數會在解釋類的對應訪問器時被調用一次，並可以得到裝飾器的參數和被裝飾的訪問器的相關信息。

裝飾器方法的調用只會在加載代碼時執行一次，調用被裝飾的訪問器不會觸發裝飾器方法。

編譯后的源碼：

"use strict";
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
function methodDecorator(param1, param2) {
    return function (target, propertyKey, descriptor) {
        console.log(param1 + ", " + param2 + ", " + target + ", " + propertyKey + ", " + JSON.stringify(descriptor));
    };
}
var MyClass = (function () {
    function MyClass() {
    }
    Object.defineProperty(MyClass, "myName", {
        get: function () {
            return this._myName;
        },
        set: function (value) {
            this._myName = value;
        },
        enumerable: true,
        configurable: true
    });
    Object.defineProperty(MyClass.prototype, "age", {
        get: function () {
            return this._age;
        },
        set: function (value) {
            this._age = value;
        },
        enumerable: true,
        configurable: true
    });
    __decorate([
        methodDecorator(false)
    ], MyClass.prototype, "age", null);
    __decorate([
        methodDecorator(true, "this is static")
    ], MyClass, "myName", null);
    return MyClass;
}());
MyClass.myName = "hello";
console.log(MyClass.myName);
var obj = new MyClass();
obj.age = 28;
console.log(obj.age);

請參考方法裝飾器。

屬性裝飾器

屬性裝飾器聲明在一個屬性聲明之前（緊靠着屬性聲明）。 屬性裝飾器不能用在聲明文件中（.d.ts），或者任何外部上下文（比如 declare的類）里。

屬性裝飾器表達式會在運行時當作函數被調用，傳入下列2個參數：

1. 對於靜態成員來說是類的構造函數，對於實例成員是類的原型對象。
2. 成員的名字。

我們來看一個例子：

function propDecorator(param1: boolean, param2?: string) {
    return function (target: any, propertyKey: string) {
        console.log(param1 + ", " + param2 + ", " + target + ", " + propertyKey);
    };
}

class MyClass {
    @propDecorator(false, "Hi")
    public static A: number = 0;

    @propDecorator(true)
    public a: string = "hello";
}

console.log(MyClass.A);
var obj = new MyClass();
console.log(obj.a);

輸出如下：

true, undefined, [object Object], a
false, Hi, function MyClass() {
        this.a = "hello";
    }, A
0
hello

我們可以發現，屬性裝飾器返回的函數會在解釋類的對應屬性時被調用一次，並可以得到裝飾器的參數和被裝飾的屬性的相關信息。

裝飾器方法的調用只會在加載代碼時執行一次，調用被裝飾的屬性不會觸發裝飾器方法。

編譯后的源碼：

"use strict";
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
function propDecorator(param1, param2) {
    return function (target, propertyKey) {
        console.log(param1 + ", " + param2 + ", " + target + ", " + propertyKey);
    };
}
var MyClass = (function () {
    function MyClass() {
        this.a = "hello";
    }
    MyClass.A = 0;
    __decorate([
        propDecorator(true)
    ], MyClass.prototype, "a", void 0);
    __decorate([
        propDecorator(false, "Hi")
    ], MyClass, "A", void 0);
    return MyClass;
}());
console.log(MyClass.A);
var obj = new MyClass();
console.log(obj.a);

請參考方法裝飾器。

參數裝飾器

參數裝飾器聲明在一個參數聲明之前（緊靠着參數聲明）。 參數裝飾器應用於類構造函數或方法聲明。 參數裝飾器不能用在聲明文件（.d.ts），重載或其它外部上下文（比如 declare的類）里。

參數裝飾器表達式會在運行時當作函數被調用，傳入下列3個參數：

1. 對於靜態成員來說是類的構造函數，對於實例成員是類的原型對象。
2. 成員的名字。
3. 參數在函數參數列表中的索引。

我們來看一個例子：

function paramDecorator(target: Object, propertyKey: string | symbol, parameterIndex: number) {
    console.log(target + ", " + <any> propertyKey + ", " + parameterIndex);
}

class MyClass {
    public func(@paramDecorator a: number, @paramDecorator b: string = "hello", @paramDecorator c?: boolean): void {
        console.log("call method");
    }
}

var obj = new MyClass();
obj.func(1);
obj.func(2);

輸出如下：

[object Object], func, 2
[object Object], func, 1
[object Object], func, 0
call method
call method

我們可以發現，參數裝飾器返回的函數會在解釋方法的參數時被調用一次，並可以得到參數的相關信息。我們有3個參數就調用了3次。

裝飾器方法的調用只會在加載代碼時執行一次，調用被裝飾的參數的方法不會觸發裝飾器方法。

編譯后的源碼：

"use strict";
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
var __param = (this && this.__param) || function (paramIndex, decorator) {
    return function (target, key) { decorator(target, key, paramIndex); }
};
function paramDecorator(target, propertyKey, parameterIndex) {
    console.log(target + ", " + propertyKey + ", " + parameterIndex);
}
var MyClass = (function () {
    function MyClass() {
    }
    MyClass.prototype.func = function (a, b, c) {
        if (b === void 0) { b = "hello"; }
        console.log("call method");
    };
    __decorate([
        __param(0, paramDecorator), __param(1, paramDecorator), __param(2, paramDecorator)
    ], MyClass.prototype, "func", null);
    return MyClass;
}());
var obj = new MyClass();
obj.func(1);
obj.func(2);

請參考方法裝飾器。