填寫這份《一分鐘調查》,幫我們(開發組)做得更好!去填寫Home

TypeScript 配置

TypeScript configuration

TypeScript 是 Angular 應用開發中使用的主語言。 它是 JavaScript 的“方言”之一,為型別安全和工具化而做了設計期支援。

TypeScript is a primary language for Angular application development. It is a superset of JavaScript with design-time support for type safety and tooling.

瀏覽器不能直接執行 TypeScript。它得先用 tsc 編譯器轉譯(transpile)成 JavaScript,而且編譯器需要進行一些配置。

Browsers can't execute TypeScript directly. Typescript must be "transpiled" into JavaScript using the tsc compiler, which requires some configuration.

本頁面會涵蓋 TypeScript 配置與環境的某些方面,這些對 Angular 開發者是很重要的。具體來說包括下列檔案:

This page covers some aspects of TypeScript configuration and the TypeScript environment that are important to Angular developers, including details about the following files:

配置檔案

Configuration files

一個 Angular 工作空間中包含多個 TypeScript 配置檔案。在根一級,有兩個主要的 TypeScript 配置檔案:tsconfig.json 檔案和 tsconfig.base.json 檔案。

A given Angular workspace contains several TypeScript configuration files. At the root tsconfig.json file specifies the base TypeScript and Angular compiler options that all projects in the workspace inherit.

請參閱 Angular 編譯器選項一章,以瞭解可以使用哪些 Angular 特有的選項。

See the Angular compiler options guide for information about what Angular specific options are available.

TypeScript 和 Angular 提供了很多選項,可以用來配置型別檢查功能和要產生的輸出。更多資訊,請參閱 TypeScript 文件中的使用 extends 進行配置繼承部分。

The TypeScript and Angular have a wide range of options which can be used to configure type-checking features and generated output. For more information, see the Configuration inheritance with extends section of the TypeScript documentation.

要了解 TypeScript 配置檔案的詳情,請參閱官方提供的 TypeScript wiki。要了解配置繼承的詳情,參閱使用 extends 進行配置繼承部分。

For more information TypeScript configuration files, see the official TypeScript wiki For details about configuration inheritance, see the Configuration inheritance with extends section.

Angular 工作空間的初始 tsconfig.base.json 通常是這樣的。

The initial tsconfig.json for an Angular workspace typically looks like the following example.

{ "compileOnSave": false, "compilerOptions": { "baseUrl": "./", "outDir": "./dist/out-tsc", "sourceMap": true, "declaration": false, "downlevelIteration": true, "experimentalDecorators": true, "moduleResolution": "node", "importHelpers": true, "target": "es2015", "module": "es2020", "lib": [ "es2018", "dom" ] } }
tsconfig.json
      
      {
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    "outDir": "./dist/out-tsc",
    "sourceMap": true,
    "declaration": false,
    "downlevelIteration": true,
    "experimentalDecorators": true,
    "moduleResolution": "node",
    "importHelpers": true,
    "target": "es2015",
    "module": "es2020",
    "lib": [
      "es2018",
      "dom"
    ]
  }
}
    

嚴格模式

Strict mode

當你建立新的工作空間和專案時,你可以選擇使用 Angular 的嚴格模式,它會幫助你寫出更好、更容易維護的程式碼。 欲知詳情,參閱嚴格模式

When you create new workspaces and projects, you have the option to use Angular's strict mode, which can help you write better, more maintainable code. For more information, see Strict mode.

noImplicitAnysuppressImplicitAnyIndexErrors

noImplicitAny and suppressImplicitAnyIndexErrors

TypeScript 開發者們在 noImplicitAny 標誌應該是 true 還是 false 上存在分歧。 這沒有標準答案,你以後還可以修改這個標誌。 但是你的選擇會在大專案中產生顯著差異,所以它值得討論一番。

TypeScript developers disagree about whether the noImplicitAny flag should be true or false. There is no correct answer and you can change the flag later. But your choice now can make a difference in larger projects, so it merits discussion.

noImplicitAny 標誌是 false(預設值)時, 如果編譯器無法根據變數的用途推斷出變數的型別,它就會悄悄的把變數型別預設為 any。這就是隱式 any的含義。

When the noImplicitAny flag is false (the default), and if the compiler cannot infer the variable type based on how it's used, the compiler silently defaults the type to any. That's what is meant by implicit any.

noImplicitAny 標誌是 true 並且 TypeScript 編譯器無法推斷出型別時,它仍然會產生 JavaScript 檔案。 但是它也會報告一個錯誤。 很多飽經滄桑的程式設計師更喜歡這種嚴格的設定,因為型別檢查能在編譯期間捕獲更多意外錯誤。

When the noImplicitAny flag is true and the TypeScript compiler cannot infer the type, it still generates the JavaScript files, but it also reports an error. Many seasoned developers prefer this stricter setting because type checking catches more unintentional errors at compile time.

即使 noImplicitAny 標誌被設定成了 true,你也可以把變數的型別設定為 any

You can set a variable's type to any even when the noImplicitAny flag is true.

如果把 noImplicitAny 標誌設定為了 true,你可能會得到隱式索引錯。 大多數程式設計師可能覺得這種錯誤是個煩惱而不是助力。 你可以使用另一個標誌來禁止它們。

When the noImplicitAny flag is true, you may get implicit index errors as well. Most developers feel that this particular error is more annoying than helpful. You can suppress them with the following additional flag:

"suppressImplicitAnyIndexErrors": true
      
      "suppressImplicitAnyIndexErrors": true
    

要了解 TypeScript 配置如何影響編譯的更多資訊,請參閱 Angular 編譯器選項範本型別檢查 兩章。

For more information about how the TypeScript configuration affects compilation, see Angular Compiler Options and Template Type Checking.

TypeScript 型別定義(typings)

TypeScript typings

很多 JavaScript 函式庫,比如 jQuery、Jasmine 測試函式庫和 Angular,會透過新的特性和語法來擴充套件 JavaScript 環境。 而 TypeScript 編譯器並不能原生的識別它們。 當編譯器不能識別時,它就會丟擲一個錯誤。

Many JavaScript libraries, such as jQuery, the Jasmine testing library, and Angular, extend the JavaScript environment with features and syntax that the TypeScript compiler doesn't recognize natively. When the compiler doesn't recognize something, it throws an error.

可以使用TypeScript 型別定義檔案 —— .d.ts 檔案 —— 來告訴編譯器你要載入的函式庫的型別定義。

Use TypeScript type definition filesd.ts files—to tell the compiler about the libraries you load.

TypeScript 敏感的編輯器藉助這些定義檔案來顯示這些函式庫中各個特性的型別定義。

TypeScript-aware editors leverage these same definition files to display type information about library features.

很多函式庫在自己的 npm 套件中都包含了它們的型別定義檔案,TypeScript 編譯器和編輯器都能找到它們。Angular 函式庫也是這樣的。 任何 Angular 應用程式的 node_modules/@angular/core/ 目錄下,都包含幾個 d.ts 檔案,它們描述了 Angular 的各個部分。

Many libraries include definition files in their npm packages where both the TypeScript compiler and editors can find them. Angular is one such library. The node_modules/@angular/core/ folder of any Angular application contains several d.ts files that describe parts of Angular.

你不需要為那些包含了 d.ts 檔案的函式庫獲取型別定義檔案 —— Angular 的所有套件都是如此。

You don't need to do anything to get typings files for library packages that include d.ts files. Angular packages include them already.

lib.d.ts 檔案

lib.d.ts

TypeScript 帶有一個特殊的宣告檔案,名為 lib.d.ts。該檔案包含了 JavaScript 執行函式庫和 DOM 的各種常用 JavaScript 環境宣告。

TypeScript includes a special declaration file called lib.d.ts. This file contains the ambient declarations for various common JavaScript constructs present in JavaScript runtimes and the DOM.

基於 --target,TypeScript 新增額外的環境宣告,例如如果目標為 es6 時將新增 Promise

Based on the --target, TypeScript adds additional ambient declarations like Promise if the target is es6.

預設情況下,目標是 es2015。如果你把目標改為 es5,那麼由於包含了宣告檔案列表,你仍然擁有較新的型別宣告:

By default, the target is es2015. If you are targeting es5, you still have newer type declarations due to the list of declaration files included:

"lib": [ "es2018", "dom" ]
tsconfig.json (lib excerpt)
      
      "lib": [
  "es2018",
  "dom"
]
    

安裝型別定義檔案

Installable typings files

遺憾的是,很多函式庫 —— jQuery、Jasmine 和 Lodash 等函式庫 —— 都沒有在它們自己的 npm 套件中包含 d.ts 檔案。 幸運的是,它們的作者或社群中的貢獻者已經為這些函式庫建立了獨立的 d.ts 檔案,並且把它們發佈到了一個眾所周知的位置。

Many libraries—jQuery, Jasmine, and Lodash among them—do not include d.ts files in their npm packages. Fortunately, either their authors or community contributors have created separate d.ts files for these libraries and published them in well-known locations.

你還可以透過 npm 來使用@types/* 範圍化套件來安裝這些型別資訊, 而 TypeScript 自從 2.0 開始,可以自動識別它們。

You can install these typings via npm using the @types/* scoped package and Typescript, starting at 2.0, automatically recognizes them.

比如,要安裝 jasmine 的型別資訊,你可以執行 npm install @types/jasmine --save-dev

For instance, to install typings for jasmine you run npm install @types/jasmine --save-dev.

編譯目標(target)

target

預設情況下,編譯目標是 es2015,只有現代瀏覽器才支援它。 你可以把編譯目標配置為 es5 以指定支援老式瀏覽器。 Angular CLI 還提供了差異化載入功能,以便使用不同的包來分別支援現代瀏覽器和老式瀏覽器。

By default, the target is es2015, which is supported only in modern browsers. You can configure the target to es5 to specifically support legacy browsers. Differential loading is also provided by the Angular CLI to support modern, and legacy browsers with separate bundles.