书写 .d.ts 文件

    最佳的书写.d.ts文件的方式是照着库的文档来写，而不是源码。照着文档写描述文件，保证了你所写的并没有牵涉到具体的实现细节，并且文档往往比源码更为易懂。下面的例子都将假设你正在照着文档书写描述文件。

    命名空间

    当定义接口时，你可以选择是否将这些类型放入一个模块里。如果使用者经常声明这种类型的变量或参数，并且这个类型没有和其他类型有命名冲突，那么可以将其放入全局命名空间里。但是，如果这个类型常常并不是被直接引用的，而且不能够很好地被唯一命名，那么将其放入模块中更为合适。

    回调

    许多JavaScript库的API接受一个函数作为参数，并且在晚些时候以固定的参数执行它。当为这类API定义类型时，不要将函数参数设置为可选的。你应该站在提供者的角度，而不是使用者的角度。

    扩展性和声明合并

    以匿名类型描述的变量：

    以接口类型描述的变量：

    1. interface SomePoint { x: number; y: number; }
    2. declare var MyPoint: SomePoint;

    对于使用方来说，它们两个的效果是一样的。但是SomePoint接口，可以在之后以合并的方式被扩展：

    1. interface SomePoint { z: number; }
    2. MyPoint.z = 4; // OK

    你是否扩展它完全取决于你的需求。目的仅仅是为了明确地表达库的意图。

    TypeScript中的类创建了两种不同的类型：第一种是实例类型，它定义了类的实例拥有的成员，还有一种是构造函数类型，它定义了类构造函数拥有的成员。构造函数类型又被成为“静态部分”类型。

    以下两个例子的效果，在使用者的角度几乎都是一样的：

    标准写法

    1.     static st: string;
    2.     inst: number;
    3.     constructor(m: any) {}
    4. }

    分解写法

    1. interface A_Static {
    2.     new(m: any): A_Instance;
    3.     st: string;
    4. }
    5. interface A_Instance {
    6.     inst: number;
    7. }
    8. declare var A: A_Static;

    区别如下：

    • 标准类可以使用extends继承。而分解类不可以。这在以后的TypeScript版本里可能会有所改变。
    • 标准和分解类在之后都可以通过声明合并来进行拓展。
    • 分解类可以添加实例成员，标准类不可。
    • 使用分解类时，你需要为它多起一些合理的类型名。

    命名准则

    大体上，不需要在接口前添加前缀I（如IColor）。因为在中，接口的概念比在C#和Java中都宽泛，所以I前缀往往不是那么有用。

    例子

    可选对象

    示例

    描述

    1. module animalFactory {
    2.     interface AnimalOptions {
    3.         name: string;
    4.         height?: number;
    5.         weight?: number;
    6.     }
    7.     function create(name: string, animalOptions?: AnimalOptions): Animal;
    8. }

    带属性的函数

    示例

    1. zooKeeper.workSchedule = "morning";
    2. zooKeeper(giraffeCage);

    描述

    1. // Note: Function must precede module
    2. function zooKeeper(cage: AnimalCage);
    3. module zooKeeper {
    4.     var workSchedule: string;
    5. }

    示例

    1. var w = widget(32, 16);
    2. var y = new widget("sprocket");
    3. // w and y are both widgets
    4. y.sprock();

    描述

    全局或外部未知的库

    示例

    1. // Either
    2. import x = require('zoo');
    3. x.open();
    4. // or

    描述

    1. module zoo {
    2.   function open(): void;
    3. }
    5. declare module "zoo" {
    6.     export = zoo;
    7. }

    外部模块里的单个复杂对象

    示例

    1. // Super-chainable library for eagles
    2. import eagle = require('./eagle');
    3. // Call directly
    4. eagle('bald').fly();
    5. // Invoke with new
    6. var eddie = new eagle(1000);
    7. // Set properties
    8. eagle.favorite = 'golden';

    描述

    1. // Note: can use any name here, but has to be the same throughout this file
    2. declare function eagle(name: string): eagle;
    3. declare module eagle {
    4.     var favorite: string;
    5.     function fly(): void;
    6. }
    7. interface eagle {
    8.     new(awesomeness: number): eagle;
    9. }
    11. export = eagle;

    回调

    示例

    描述

    1. // Note: 'void' return type is preferred here
    2. function addLater(x: number, y: number, (sum: number) => void): void;