TS学习笔记十：装饰器及三斜线指令

本节介绍TS中的装饰器和三斜线指令，装饰器（Decorators）为我们在类的声明及成员上通过元编程语法添加标注提供了一种方式。三斜线指令是包含单个XML标签的单行注释。注释的内容会做为编译器指令使用。

B站视频 https://www.bilibili.com/video/BV1CQ4y1w76R/ https://www.bilibili.com/video/BV1kC4y1C78A/ https://www.bilibili.com/video/BV1bk4y1D72M/
西瓜视频 https://www.ixigua.com/7324864397644562998

一、装饰器

装饰器（Decorators）为我们在类的声明及成员上通过元编程语法添加标注提供了一种方式。在ts中目前是实验性的特性，要启用需要在命令行或tsconfig.json里启用experimentalDecorators编译器选项，具体启用方式如下： 命令行：

tsc --target ES5 --experimentalDecorators

tsconfig.json：

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

装饰器是一个特殊的类型声明，能够被附加到类声明、方法、访问符、属性、参数等上，使用@expr的形式进行附加，expr求值后必须为一个函数，会在运行时被调用，被装饰的声明信息作为参数传入，如下：

function sealed(target){
}

定义后可以@sealed(‘’)的方式进行使用。 1. 装饰器工厂 要定制一个装饰器并应用到一个声明上，需要写一个装饰器工厂，装饰器工厂是一个简单的函数，并返回一个表达式，此表达式在运行的时候调用。

function color(value: string) { // 这是一个装饰器工厂
    return function (target) { //  这是装饰器
        // do something with "target" and "value"...
    }
}

2.装饰器组合 多个装饰器可以同时应用到一个声明上：

@a @b x
@a
@b
x

可以在同一行，也可以在不同行，多个声明时求值方式与符合函数类型，即a(b(x))，具体如下：

由上至下依次对装饰器表达式求值
求值的结果会被当做函数，由下至上依次调用。

function f() {
    console.log("f(): evaluated");
    return function (target, propertyKey: string, descriptor: PropertyDescriptor) {
        console.log("f(): called");
    }
}

function g() {
    console.log("g(): evaluated");
    return function (target, propertyKey: string, descriptor: PropertyDescriptor) {
        console.log("g(): called");
    }
}

class C {
    @f()
    @g()
    method() {}
}

调用结果如下：

f(): evaluated
g(): evaluated
g(): called
f(): called

3. 装饰器求值 类中不同声明上的装饰器的应用顺序如下：

参数装饰器，其次是方法，访问符，或属性装饰器应用到每个实例成员。
参数装饰器，其次是方法，访问符，或属性装饰器应用到每个静态成员。
参数装饰器应用到构造函数。
类装饰器应用到类。

4.类装饰器 类装饰器在类声明之前被调用，应用于构造函数，可以用来监视，修改或替换类的具体定义，不能再声明文件.d.ts及外部上下文中使用。类装饰器的表达式会被当做函数调用，调用时类的构造函数当做其参数。如果类装饰器返回一个值，会使用提供的构造函数来替换类的声明。如果返回的是一个新的构造函数，需要手动处理原型链的内容，ts不会自动处理。

@sealed
class Greeter {
    greeting: string;
    constructor(message: string) {
        this.greeting = message;
    }
    greet() {
        return "Hello, " + this.greeting;
    }
}
function sealed(constructor: Function) {
    Object.seal(constructor);
    Object.seal(constructor.prototype);
}

上述示例当@sealed装饰器被执行时，会封闭此类的构造函数和原型，封闭后将不可扩展。

5.方法装饰器 方法装饰器在声明一个方法之前，会被应用到方法的属性描述符上，可用来监视，修改或替换方法的定义，不能用在声明文件.d.ts、重载或者任何外部上下文中。方法装饰器的表达式会被当做函数调用，调用时传入以下三个参数：

对于静态成员来说是类的构造函数，对于实例成员是类的原型对象。
成员的名字。
成员的属性描述符。

如果代码的目标版本小于es5，则成员的描述符为undefined。如果方法返回一个值，会被当做方法的属性描述符。如果目标版本小于es5，返回值会被忽略。

class Greeter {
    greeting: string;
    constructor(message: string) {
        this.greeting = message;
    }
    @enumerable(false)
    greet() {
        return "Hello, " + this.greeting;
    }
}
function enumerable(value: boolean) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        descriptor.enumerable = value;
    };
}

上述示例中当@enumerable(false)被调用时，会修改属性描述符的enumerable 。

6.访问器装饰器 访问器装饰器声明在一个访问器声明之前，应用于访问器的属性描述符，可用来监视，修改和替换一个访问器的定义，不能在声明文件.d.ts或任何外部上下中。 ts不允许同时装饰一个成员的get和set访问器，一个成员的所有装饰必须引用在文档顺序的第一个访问器上，因为装饰器应用于一个属性描述符时，已经联合了get和set访问器，不用分开声明。访问器装饰器表达式会在运行时当做函数被调用，调用时传入一下三个参数：

对于静态成员来说是类的构造函数，对于实例成员是类的原型对象。
成员的名字。
成员的属性描述符。

代码输出目标小于es5,时成员属性描述符参数是undefined。如果访问器返回一个值，会被当做方法的属性描述符。如果代码目标小于es5时，返回值会被忽略。

class Point {
    private _x: number;
    private _y: number;
    constructor(x: number, y: number) {
        this._x = x;
        this._y = y;
    }

    @configurable(false)
    get x() { return this._x; }

    @configurable(false)
    get y() { return this._y; }
}
function configurable(value: boolean) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        descriptor.configurable = value;
    };
}

7.属性装饰器 属性装饰器声明在一个属性之前，不能在声明文件.d.ts及任何外部上下文中。属性装饰器表达式会在运行时当做函数被调用，调用时传入2个参数：

对于静态成员来说是类的构造函数，对于实例成员是类的原型对象。
成员的名字。

属性描述符不会做为参数传入属性装饰器，如果属性装饰器返回一个值，会被当做方法的属性描述符，如果目标小于es5返回值会被忽略。如果装饰器返回一个值，会被当做方法的属性描述符。

class Greeter {
    @format("Hello, %s")
    greeting: string;

    constructor(message: string) {
        this.greeting = message;
    }
    greet() {
        let formatString = getFormat(this, "greeting");
        return formatString.replace("%s", this.greeting);
    }
}
import "reflect-metadata";
const formatMetadataKey = Symbol("format");
function format(formatString: string) {
    return Reflect.metadata(formatMetadataKey, formatString);
}
function getFormat(target: any, propertyKey: string) {
    return Reflect.getMetadata(formatMetadataKey, target, propertyKey);
}

上述示例中当@format("Hello, %s")被调用时，会添加一条这个属性的元数据，通过reflect-metadata库里的Reflect.metadata函数，当getFormat被调用时，会读取格式的元数据。

8.参数装饰器 参数装饰器声明在一个参数之前，应用于类型构造函数或方法声明，不能用在声明文件.d.ts、重载或其它外部上下文里，参数装饰器表达式会被当做函数被调用，调用时传入3个参数：

对于静态成员来说是类的构造函数，对于实例成员是类的原型对象。
成员的名字。
参数在函数参数列表中的索引。

参数装饰器只能用来监听一个方法的参数是否被传入，参数装饰器的返回值会被忽略。

class Greeter {
    greeting: string;

    constructor(message: string) {
        this.greeting = message;
    }

    @validate
    greet(@required name: string) {
        return "Hello " + name + ", " + this.greeting;
    }
}
import "reflect-metadata";

const requiredMetadataKey = Symbol("required");

function required(target: Object, propertyKey: string | symbol, parameterIndex: number) {
    let existingRequiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];
    existingRequiredParameters.push(parameterIndex);
    Reflect.defineMetadata(requiredMetadataKey, existingRequiredParameters, target, propertyKey);
}

function validate(target: any, propertyName: string, descriptor: TypedPropertyDescriptor<Function>) {
    let method = descriptor.value;
    descriptor.value = function () {
        let requiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyName);
        if (requiredParameters) {
            for (let parameterIndex of requiredParameters) {
                if (parameterIndex >= arguments.length || arguments[parameterIndex] === undefined) {
                    throw new Error("Missing required argument.");
                }
            }
        }

        return method.apply(this, arguments);
    }
}

上述示例中使用@required添加了元数据实体把参数标记为必须得，@validate装饰器包裹函数，在调用原先的函数前验证函数参数。 9.元数据 reflect-metadata是处理元数据的库，不是es的标准库，需要额外引入，安装指令：npm i reflect-metadata --save。ts支持为带有装饰器的声明生成元数据，需要在命令行或jsconfig.json中开启emitDecoratorMetadata编译选项。命令行：

tsc --target ES5 --experimentalDecorators --emitDecoratorMetadata

jsconfig.json:

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

启用后，安装了reflect-metadata并引入的情况下，类型信息可以在运行时调用：

import "reflect-metadata";

class Point {
    x: number;
    y: number;
}

class Line {
    private _p0: Point;
    private _p1: Point;

    @validate
    set p0(value: Point) { this._p0 = value; }
    get p0() { return this._p0; }

    @validate
    set p1(value: Point) { this._p1 = value; }
    get p1() { return this._p1; }
}

function validate<T>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) {
    let set = descriptor.set;
    descriptor.set = function (value: T) {
        let type = Reflect.getMetadata("design:type", target, propertyKey);
        if (!(value instanceof type)) {
            throw new TypeError("Invalid type.");
        }
    }
}

ts编译器可通过@Reflect.metadata装饰器注入设计阶段的类型信息：

class Line {
    private _p0: Point;
    private _p1: Point;

    @validate
    @Reflect.metadata("design:type", Point)
    set p0(value: Point) { this._p0 = value; }
    get p0() { return this._p0; }

    @validate
    @Reflect.metadata("design:type", Point)
    set p1(value: Point) { this._p1 = value; }
    get p1() { return this._p1; }
}

二、Mixins

mixin是一种创建可重用组件创建类的方式：

// Disposable Mixin
class Disposable {
    isDisposed: boolean;
    dispose() {
        this.isDisposed = true;
    }

}

// Activatable Mixin
class Activatable {
    isActive: boolean;
    activate() {
        this.isActive = true;
    }
    deactivate() {
        this.isActive = false;
    }
}

class SmartObject implements Disposable, Activatable {
    constructor() {
        setInterval(() => console.log(this.isActive + " : " + this.isDisposed), 500);
    }

    interact() {
        this.activate();
    }

    // Disposable
    isDisposed: boolean = false;
    dispose: () => void;
    // Activatable
    isActive: boolean = false;
    activate: () => void;
    deactivate: () => void;
}
applyMixins(SmartObject, [Disposable, Activatable]);

let smartObj = new SmartObject();
setTimeout(() => smartObj.interact(), 1000);

function applyMixins(derivedCtor: any, baseCtors: any[]) {
    baseCtors.forEach(baseCtor => {
        Object.getOwnPropertyNames(baseCtor.prototype).forEach(name => {
            derivedCtor.prototype[name] = baseCtor.prototype[name];
        });
    });
}

上述示例中定义了两个类，作为mixins，每个类都有自己的行为和功能：

// Disposable Mixin
class Disposable {
    isDisposed: boolean;
    dispose() {
        this.isDisposed = true;
    }

}
// Activatable Mixin
class Activatable {
    isActive: boolean;
    activate() {
        this.isActive = true;
    }
    deactivate() {
        this.isActive = false;
    }
}

创建一个新的类，让其具有所有属性：

class SmartObject implements Disposable, Activatable {
// Disposable
isDisposed: boolean = false;
dispose: () => void;
// Activatable
isActive: boolean = false;
activate: () => void;
deactivate: () => void;
}

示例中使用implements，把类当做接口使用，仅使用类的类型不继承具体的声明，为mixin创建出占位属性，在通过mixins混入定义的类，完成实现部分，这样就不用实现可以直接使用：

applyMixins(SmartObject, [Disposable, Activatable]);

applyMixins会遍历mixins上的所有属性，并复制到目标上去，把之前的占位符属性替换成真正的实现代码：

function applyMixins(derivedCtor: any, baseCtors: any[]) {
    baseCtors.forEach(baseCtor => {
        Object.getOwnPropertyNames(baseCtor.prototype).forEach(name => {
            derivedCtor.prototype[name] = baseCtor.prototype[name];
        })
    });
}

三、三斜线指令

三斜线指令包含单个XML标签的单个注释，会做为编译器指令使用，三斜线指令只能放在包含它的文件的顶端，一个三斜线指令的前面只能出现单行或多行注释，如果出现在一个语句或声明之后，会被当做普通的单行注释，并不具有特殊含义。 /// <reference path="..." />用于声明文件间的依赖，用于告诉编译器在编译过程中要引入的额外的文件。使用--out或--outFile时，可以作为调整输出内容属性的一种方法。

预处理输入文件编译器会对输入文件进行预处理，预处理时解析所有的三斜线引用指令，此过程中额外的文件会加到编译过程中。引用不存在的文件会报错，一个文件用三斜线指令引用自己也会报错。
使用 --noResolve 指定了--noResolve编译选项，三斜线引用将被忽略，不会增加新文件也不会改变改定文件的顺序。 /// <reference no-default-lib="true"/>: 此指令把一个文件标记成默认库，告诉编译器在编译过程中不要包含这个默认库，和命令行上使用--noLib相似，当传递了--skipDefaultLibCheck时，编译器只会忽略检查带有/// <reference no-default-lib="true"/>的文件。

/// <amd-module />： 默认情况下生成的amd模块是匿名的，amd-module指令允许给编译器传入一个可选的模块名。 amdModule.ts：

///<amd-module name='NamedModule'/>
export class C {
}

编译后：

define("NamedModule", ["require", "exports"], function (require, exports) {
    var C = (function () {
        function C() {
        }
        return C;
    })();
    exports.C = C;
});