About writing typescript. d.ts files

Article reproduced from: HTTPS://GITHUB.COM/ZHONGSP

It is recommended that you jump directly to the above URL to view the latest version. introduce

When using an external JavaScript library or a new hosting API, you need a declaration file (. d.ts) to define the library's shape. This manual contains advanced concepts for writing. d.ts files, with some examples that show you how to write a declaration file. Guidance and Instructions Process

It is a good idea to start writing the. d.ts file from the documentation for the library instead of the code. This ensures that the implementation will not be interfered with, and is easier to read than JS code. The following example assumes that you are referencing a document to write a declaration file. name Space

When defining interfaces (for example, "Options" objects), you will choose whether to put these types into the namespace. This is primarily a subjective judgment-the main use of these types is to declare variables and parameters, and type naming does not cause naming conflicts, and is better placed in the global namespace. Use namespaces to avoid conflicts with other types if the type is not used directly or cannot have a unique name. callback function

Many JavaScript libraries receive a function as a parameter and then call it by passing in a known parameter. When signing for these types and functions, do not mark this argument as an optional parameter. The right way to think is "what kind of parameters will be provided." ", not" what parameters will be used. ”。 Typescript 0.9.7+ does not force the use of this optional parameter, and the optional bidirectional covariance of the parameters can be enforced by an external linter. extension and declaration merging

When writing a declaration file, remember how typescript extends existing objects. You can choose to declare a variable in the form of an anonymous type or an interface type: anonymous type var

DECLARE var mypoint: {x:number; y:number;};

interface type var

Interface Somepoint {x:number; y:number;}
declare var mypoint:somepoint;

They are the same from the consumer's point of view, but the Somepoint type can be extended through interface merging:

Interface Somepoint {z:number;}
Mypoint.z = 4; Ok

Whether or not you want your statement to be extensible depends on the subjective judgment. In general, try to conform to the library's intentions. Decomposition of Classes

The Typescript class creates two types: the instance type, defines which members the instance of the type has, the constructor type, and defines what types the class constructor has. The constructor type is also called the static part type of the class, because it contains static members of the class.

You can use the TypeOf keyword to get the class static part type, and it is useful and necessary to explicitly decompose the class into the instance type and the static type when writing the declaration file.

The following is an example, from the user's point of view, the two statements are equivalent: Standard Edition

Class A {
    static st:string;
    Inst:number;
    Constructor (M:any) {}
}

exploded version

Interface A_static {
    new (M:any): a_instance;
    st:string;
}
Interface A_instance {
    inst:number;
}
declare var a:a_static;

The pros and cons are as follows: The standard method can be inherited using extends, and the decomposed class cannot. This may change in a future version of Typescript: whether any extends expression is allowed to be allowed to add static members to the class to allow the addition of instance members for the exploded class, the Standard Edition does not allow the use of decomposition classes, for members of the reasonable naming rules

Generally, do not add an I prefix to the interface (for example: Icolor). The type of interface in Typescript is more extensive than in C # or Java, and IFoo naming is bad for this feature. Example

Here is an example section. For each example, first use the use method, then the type declaration. If there are multiple good declaration representations, multiple will be listed. Parameter Object How to use

Animalfactory.create ("dog");
Animalfactory.create ("Giraffe", {name: "Ronald"});
Animalfactory.create ("Panda", {name: "Bob", height:400});
Invalid:name must be provided if options are given
animalfactory.create ("Cat", {height:32});

type

Namespace Animalfactory {
    interface animaloptions {
        name:string;
        Height?: number;
        Weight?: number;
    }
    function Create (name:string, animaloptions?: animaloptions): Animal;
}

functions with Attributes How to use

Zookeeper.workschedule = "Morning";
Zookeeper (giraffecage);

type

Note:function must precede namespace
Function zookeeper (cage:animalcage);
Namespace Zookeeper {
    var workschedule:string;
}

a method that can be invoked with new or directly How to use

var w = widget (m);
var y = new Widget ("sprocket");
W and y are both widgets
W.sprock ();
Y.sprock ();

type

Interface Widget {
    sprock (): void;
}

Interface Widgetfactory {
    new (name:string): Widget;
    (Width:number, Height:number): Widget;
}

declare var widget:widgetfactory;

Global/unclear libraries How to use

Either
import x = require (' zoo ');
X.open ();
or
zoo.open ();

type

Declare namespace Zoo {
  function open (): void;
}

DECLARE module "Zoo" {
    export = Zoo;
}

a single Complex object for an external module How to use

Super-chainable Library for Eagles
Import Eagle = require ('./eagle ');
Call directly
Eagle (' bald '). Fly ();
Invoke with new
var eddie = new Eagle (' Mille ');
Set properties
eddie.favorite = ' golden ';

type

Note:can use "Here", but has to is the same throughout this file
Declare Function Eagle (name:string): Eag Le;
Declare namespace Eagle {
    var favorite:string;
    Function Fly (): void;
}
Interface Eagle {
    new (Awesomeness:number): eagle;
}

Export = Eagle;

callback function How to use

Addlater (3, 4, x => console.log (' x = ' + x '));

type

Note: ' Void ' return type are preferred here
function Addlater (X:number, Y:number, (sum:number) => void): void;