码迷,mamicode.com
首页 > 其他好文 > 详细

TypeScript手册翻译系列12-编写.d.ts文件

时间:2015-10-08 10:42:17      阅读:385      评论:0      收藏:0      [点我收藏+]

标签:

Writing .d.ts files

When using an external JavaScript library, or new host API, you‘ll need to use a declaration file (.d.ts) to describe the shape of that library. This guide covers a few high-level concepts specific to writing definition files, then proceeds with a number of examples that show how to transcribe various concepts to their matching definition file descriptions.

Guidelines and Specifics

Workflow

The best way to write a .d.ts file is to start from the documentation of the library, not the code. Working from the documentation ensures the surface you present isn‘t muddied with implementation details, and is typically much easier to read than JS code. The examples below will be written as if you were reading documentation that presented example calling code.

Namespacing

When defining interfaces (for example, "options" objects), you have a choice about whether to put these types inside a module or not. This is largely a judgement call -- if the consumer is likely to often declare variables or parameters of that type, and the type can be named without risk of colliding with other types, prefer placing it in the global namespace. If the type is not likely to be referenced directly, or can‘t be named with a reasonably unique name, do use a module to prevent it from colliding with other types.

Callbacks

Many JavaScript libraries take a function as a parameter, then invoke that function later with a known set of arguments. When writing the function signatures for these types, do not mark those parameters as optional. The right way to think of this is"What parameters will be provided?", not "What parameters will be consumed?". While TypeScript 0.9.7 and above does not enforce that the optionality, bivariance on argument optionality might be enforced by an external linter.

Extensibility and Declaration Merging

When writing definition files, it‘s important to remember TypeScript‘s rules for extending existing objects. You might have a choice of declaring a variable using an anonymous type or an interface type:

Anonymously-typed var

declare var MyPoint: { x: number; y: number; };


Interfaced-typed var

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


From a consumption side these declarations are identical, but the type SomePoint can be extended through interface merging:

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


Whether or not you want your declarations to be extensible in this way is a bit of a judgement call. As always, try to represent the intent of the library here.

Class Decomposition

Classes in TypeScript create two separate types: the instance type, which defines what members an instance of a class has, and the constructor function type, which defines what members the class constructor function has. The constructor function type is also known as the "static side" type because it includes static members of the class.

While you can reference the static side of a class using the typeof keyword, it is sometimes useful or necessary when writing definition files to use the decomposed class pattern which explicitly separates the instance and static types of class.

As an example, the following two declarations are nearly equivalent from a consumption perspective:


Standard

class A {    static st: string;
   inst: number;
   constructor(m: any) {}
}


Decomposed

interface A_Static {    new(m: any): A_Instance;
   st: string;
}interface A_Instance {
   inst: number;
}
declare var A: A_Static;


The trade-offs here are as follows:

  • Standard classes can be inherited from using extends; decomposed classes cannot. This might change in later version of TypeScript if arbitrary extends expressions are allowed.

  • It is possible to add members later (through declaration merging) to the static side of both standard and decomposed classes

  • It is possible to add instance members to decomposed classes, but not standard classes

  • You‘ll need to come up with sensible names for more types when writing a decomposed class

Naming Conventions

In general, do not prefix interfaces with I (e.g. IColor). Because the concept of an interface in TypeScript is much more broad than in C# or Java, the IFoo naming convention is not broadly useful.

Examples

Let‘s jump in to the examples section. For each example, sample usage of the library is provided, followed by the definition code that accurately types the usage. When there are multiple good representations, more than one definition sample might be listed.

Options Objects

Usage

animalFactory.create("dog");
animalFactory.create("giraffe", { name: "ronald" });
animalFactory.create("panda", { name: "bob", height: 400 });// Invalid: name must be provided if options is givenanimalFactory.create("cat", { height: 32 });


Typing

module animalFactory {    interface AnimalOptions {
       name: string;
       height?: number;
       weight?: number;
   }    function create(name: string, animalOptions?: AnimalOptions): Animal;
}

Functions with Properties

Usage

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


Typing

// Note: Function must precede modulefunction zooKeeper(cage: AnimalCage);
module zooKeeper {    var workSchedule: string;
}

New + callable methods

Usage

var w = widget(32, 16);var y = new widget("sprocket");// w and y are both widgetsw.sprock();
y.sprock();


Typing

interface Widget {
   sprock(): void;
}interface WidgetFactory {    new(name: string): Widget;
   (width: number, height: number): Widget;
}

declare var widget: WidgetFactory;

Global / External-agnostic Libraries

Usage

// Eitherimport x = require(‘zoo‘);
x.open();// orzoo.open();


Typing

module zoo {  function open(): void;
}

declare module "zoo" {    export = zoo;
}

Single Complex Object in External Modules

Usage

// Super-chainable library for eaglesimport eagle = require(‘./eagle‘);// Call directlyeagle(‘bald‘).fly();// Invoke with newvar eddie = new eagle(1000);// Set propertieseagle.favorite = ‘golden‘;


Typing

// Note: can use any name here, but has to be the same throughout this filedeclare function eagle(name: string): eagle;
declare module eagle {    var favorite: string;    function fly(): void;
}interface eagle {    new(awesomeness: number): eagle;
}export = eagle;

Callbacks

Usage

addLater(3, 4, (x) => console.log(‘x = ‘ + x));


Typing

// Note: ‘void‘ return type is preferred herefunction addLater(x: number, y: number, (sum: number) => void): void;


Please post a comment here if there‘s a pattern you‘d like to see documented! We‘ll add to this as we can.

参考资料

[1] http://www.typescriptlang.org/Handbook#writing-dts-files

[2] TypeScript系列1-简介及版本新特性, http://my.oschina.net/1pei/blog/493012

[3] TypeScript系列2-手册-基础类型, http://my.oschina.net/1pei/blog/493181

[4] TypeScript系列3-手册-接口, http://my.oschina.net/1pei/blog/493388

[5] TypeScript系列4-手册-类, http://my.oschina.net/1pei/blog/493539

[6] TypeScript系列5-手册-模块, http://my.oschina.net/1pei/blog/495948

[7] TypeScript系列6-手册-函数, http://my.oschina.net/1pei/blog/501273

[8] TypeScript手册翻译系列7-泛型, http://my.oschina.net/1pei/blog/513483

[9] TypeScript手册翻译系列8-常见错误与mixins, http://my.oschina.net/1pei/blog/513499

[10] TypeScript手册翻译系列9-声明合并, http://my.oschina.net/1pei/blog/513649

[11] TypeScript手册翻译系列10-类型推断, http://my.oschina.net/1pei/blog/513652

[12] TypeScript手册翻译系列11-类型兼容性, http://my.oschina.net/1pei/blog/513833

TypeScript手册翻译系列12-编写.d.ts文件

标签:

原文地址:http://my.oschina.net/1pei/blog/514046

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!