4 TypeScript 如何運作？鳥瞰圖

本章節提供 TypeScript 運作方式的鳥瞰圖：一般 TypeScript 專案的結構為何？如何編譯以及如何編譯？我們如何使用 IDE 編寫 TypeScript？

4.1 TypeScript 專案的結構

這是 TypeScript 專案可能有的檔案結構

typescript-project/
  dist/
  ts/
    src/
      main.ts
      util.ts
    test/
      util_test.ts
  tsconfig.json

說明

• 目錄 ts/ 包含 TypeScript 檔案
  • 子目錄 ts/src/ 包含實際程式碼。
  • 子目錄 ts/test/ 包含程式碼的測試。
• 目錄 dist/ 是編譯器輸出結果的儲存位置。
• TypeScript 編譯器會將 ts/ 中的 TypeScript 檔案編譯成 dist/ 中的 JavaScript 檔案。例如
  • ts/src/main.ts 編譯成 dist/src/main.js（以及其他可能的檔案）
• tsconfig.json 用於設定 TypeScript 編譯器。

4.1.1 tsconfig.json

tsconfig.json 的內容如下

{
  "compilerOptions": {
    "rootDir": "ts",
    "outDir": "dist",
    "module": "commonjs",
    ···
  }
}

我們已指定

• TypeScript 程式碼的根目錄為 ts/。
• TypeScript 編譯器儲存其輸出的目錄為 dist/。
• 輸出檔案的模組格式為 CommonJS。

4.2 透過整合開發環境 (IDE) 編寫 TypeScript

兩個流行的 JavaScript IDE 是

• Visual Studio Code（免費）
• WebStorm（需購買）

本節的觀察結果是關於 Visual Studio Code，但也可能適用於其他 IDE。

要了解的一個重要事實是，Visual Studio Code 以兩種獨立的方式處理 TypeScript 原始碼

• 檢查開啟檔案是否有錯誤：這透過所謂的 語言伺服器 來執行。語言伺服器獨立於特定編輯器，並提供 Visual Studio Code 與語言相關的服務：偵測錯誤、重構、自動完成等。與伺服器的通訊透過基於 JSON-RPC 的通訊協定進行（RPC 代表遠端程序呼叫）。該通訊協定提供的獨立性表示伺服器幾乎可以用任何程式語言撰寫。
  • 要記住的重要事實：語言伺服器只列出目前開啟檔案的錯誤，不會編譯 TypeScript，它只會靜態分析。
• 建立（將 TypeScript 檔案編譯成 JavaScript 檔案）：在此，我們有兩個選擇。
  • 我們可以透過外部命令列執行建置工具。例如，TypeScript 編譯器 tsc 有 --watch 模式，會監控輸入檔案，並在檔案變更時將其編譯成輸出檔案。因此，每當我們在 IDE 中儲存 TypeScript 檔案時，我們會立即取得對應的輸出檔案。
  • 我們可以在 Visual Studio Code 中執行 tsc。為此，它必須安裝在我們目前正在處理的專案內部或全域（透過 Node.js 套件管理員 npm）。
  透過建立，我們會取得完整的錯誤清單。如需關於在 Visual Studio Code 中編譯 TypeScript 的更多資訊，請參閱 該 IDE 的官方文件。

4.3 TypeScript 編譯器產生的其他檔案

給定 TypeScript 檔案 main.ts，TypeScript 編譯器可以產生數種成品。最常見的是

• JavaScript 檔案：main.js
• 宣告檔案：main.d.ts（包含類型資訊；想成減去 JavaScript 程式碼的 .ts 檔案）
• 原始碼對應檔案：main.js.map

TypeScript 通常不是透過 .ts 檔案傳遞，而是透過 .js 檔案和 .d.ts 檔案

• JavaScript 程式碼包含實際功能，且可透過純 JavaScript 使用。
• 宣告檔案有助於程式編輯器進行自動完成和類似服務。此資訊使純 JavaScript 能透過 TypeScript 使用。不過，即使我們使用純 JavaScript，我們也能從中獲益，因為它能提供更好的自動完成等功能。

原始碼清單會針對 main.js 中輸出的程式碼各部分，說明 main.ts 中輸入程式碼的哪一部分產生了它。除了其他資訊外，此資訊還能讓執行時間環境執行 JavaScript 程式碼，同時在錯誤訊息中顯示 TypeScript 程式碼的行號。

4.3.1 若要從 TypeScript 使用 npm 套件，我們需要類型資訊

npm 登錄資料庫是 JavaScript 程式碼的龐大存放庫。如果我們要從 TypeScript 使用 JavaScript 套件，我們需要它的類型資訊

• 套件本身可能包含 .d.ts 檔案，甚至包含完整的 TypeScript 程式碼。
• 如果沒有，我們可能仍然可以使用它：DefinitelyTyped 是存放宣告檔案的存放庫，這些檔案是由人們為純 JavaScript 套件編寫的。

DefinitelyTyped 的宣告檔案位於 @types 名稱空間中。因此，如果我們需要套件的宣告檔案，例如 lodash，我們必須安裝套件 @types/lodash。

4.4 將 TypeScript 編譯器用於純 JavaScript 檔案

TypeScript 編譯器也可以處理純 JavaScript 檔案

• 使用選項 --allowJs，TypeScript 編譯器會將輸入目錄中的 JavaScript 檔案複製到輸出目錄中。好處：從 JavaScript 移轉到 TypeScript 時，我們可以從 JavaScript 和 TypeScript 檔案的組合開始，然後慢慢將更多 JavaScript 檔案轉換為 TypeScript。

• 使用選項 --checkJs，編譯器會另外類型檢查 JavaScript 檔案（--allowJs 必須開啟才能使用此選項）。它會盡可能執行，考量到可用的資訊有限。哪些檔案會被檢查，可以透過檔案內的註解進行設定

  • 明確排除：如果 JavaScript 檔案包含註解 // @ts-nocheck，它將不會被類型檢查。
  • 明確包含：沒有 --checkJs，註解 // @ts-check 可用於類型檢查個別 JavaScript 檔案。

• TypeScript 編譯器使用透過 JSDoc 註解指定的靜態類型資訊（請參閱下方範例）。如果我們徹底執行，我們可以完全靜態類型化純 JavaScript 檔案，甚至從中衍生宣告檔案。

• 使用選項 --noEmit，編譯器不會產生任何輸出，它只會類型檢查檔案。

以下是 JSDoc 註解的範例，它提供函式 add() 的靜態類型資訊

/**
 * @param {number} x - The first operand
 * @param {number} y - The second operand
 * @returns {number} The sum of both operands
 */
function add(x, y) {
  return x + y;
}

更多資訊：TypeScript 手冊中的「類型檢查 JavaScript 檔案」。