[TypeScript] 编程实践之1: Google的TypeScript代码风格12：Ambients

12 Ambients

环境声明用于在现有JavaScript代码上提供静态类型。 环境声明与常规声明的不同之处在于，不会为它们生成JavaScript代码。 环境声明不是引入新的变量，函数，类，枚举或命名空间，而是提供“存在”并通过外部方式（例如通过引用

12.1 Ambients声明

环境声明是使用define关键字编写的，可以声明变量，函数，类，枚举，命名空间或模块。

AmbientDeclaration:
	declare AmbientVariableDeclaration
	declare AmbientFunctionDeclaration
	declare AmbientClassDeclaration
	declare AmbientEnumDeclaration
	declare AmbientNamespaceDeclaration

12.1.1 Ambient变量声明

环境变量声明在包含声明空间中引入了一个变量。

AmbientVariableDeclaration:
	var AmbientBindingList ;
	let AmbientBindingList ;
	const AmbientBindingList ;

AmbientBindingList:
	AmbientBinding
	AmbientBindingList , AmbientBinding

AmbientBinding:
	BindingIdentifier TypeAnnotationopt

环境变量声明可以选择包含类型注释。 如果不存在类型注释，则假定变量的类型为Any。

环境变量声明不允许存在初始化程序表达式。

12.1.2 Ambient函数声明

环境函数声明在包含声明空间中引入了一个函数。

AmbientFunctionDeclaration:
	function BindingIdentifier CallSignature ;

可以通过指定多个具有相同名称的环境函数声明来重载环境函数，但是声明多个被视为相同（第3.11.2节）或仅其返回类型不同的重载是错误的。

环境函数声明不能指定函数体，也不允许默认参数值。

12.1.3 Ambient类声明

环境类声明在包含的声明空间中声明类类型和构造函数。

AmbientClassDeclaration:
	class BindingIdentifier TypeParametersopt ClassHeritage { AmbientClassBody }

AmbientClassBody:
	AmbientClassBodyElementsopt

AmbientClassBodyElements:
	AmbientClassBodyElement
	AmbientClassBodyElements AmbientClassBodyElement

AmbientClassBodyElement:
	AmbientConstructorDeclaration
	AmbientPropertyMemberDeclaration
	IndexSignature

AmbientConstructorDeclaration:
	constructor ( ParameterListopt ) ;

AmbientPropertyMemberDeclaration:
	AccessibilityModifieropt staticopt PropertyName TypeAnnotationopt ;
	AccessibilityModifieropt staticopt PropertyName CallSignature ;

12.1.4 Ambient枚举声明

一个环境枚举在语法上等效于一个非环境枚举声明。

AmbientEnumDeclaration:
	EnumDeclaration

环境枚举声明与非环境枚举声明在两个方面有所不同：

• 在环境枚举声明中，枚举成员声明中指定的所有值都必须归类为常量枚举表达式。
• 在未指定const修饰符的环境枚举声明中，忽略值的枚举成员声明被视为计算成员（与分配自动递增的值相反）。

否则，以与非环境枚举声明相同的方式处理环境枚举声明。

12.1.5 Ambient命名空间声明

环境命名空间声明声明一个命名空间。

AmbientNamespaceDeclaration:
	namespace IdentifierPath { AmbientNamespaceBody }

AmbientNamespaceBody:
	AmbientNamespaceElementsopt

AmbientNamespaceElements:
	AmbientNamespaceElement
	AmbientNamespaceElements AmbientNamespaceElement

AmbientNamespaceElement:
	exportopt AmbientVariableDeclaration
	exportopt AmbientLexicalDeclaration
	exportopt AmbientFunctionDeclaration
	exportopt AmbientClassDeclaration
	exportopt InterfaceDeclaration
	exportopt AmbientEnumDeclaration
	exportopt AmbientNamespaceDeclaration
	exportopt ImportAliasDeclaration

除了ImportAliasDeclarations之外，AmbientNamespaceElements始终声明导出的实体，无论它们是否包括可选的export修饰符。

12.2 Ambient模块声明

AmbientModuleDeclaration声明一个模块。仅在有助于全局命名空间的源文件的顶层允许这种类型的声明（第11.1节）。 StringLiteral必须指定顶级模块名称。不允许使用相对模块名称。

AmbientModuleDeclaration:
	declare module StringLiteral {  DeclarationModule }

AmbientModuleDeclaration中的ImportRequireDeclaration只能通过顶级模块名称引用其他模块。不允许使用相对模块名称。

如果环境模块声明包括导出分配，则模块内的任何声明指定导出修饰符都是错误的。如果环境模块声明不包含导出分配，则将导出模块中声明的实体，无论其声明是否包括可选的export修饰符。

环境模块是“开放式”的，具有相同字符串文字名称的环境模块声明构成单个模块。例如，模块“ io”的以下两个声明可能位于单独的源文件中。

declare module "io" {  
    export function readFile(filename: string): string;  
}

declare module "io" {  
    export function writeFile(filename: string, data: string): void;  
}

这与单个组合声明具有相同的效果：

declare module "io" {  
    export function readFile(filename: string): string;  
    export function writeFile(filename: string, data: string): void;  
}