使用 JavaScript
本文件介紹了一些 Visual Studio Code 支援的高階 JavaScript 功能。透過使用 TypeScript 語言服務，VS Code 可以為 JavaScript 提供智慧程式碼補全 (IntelliSense) 以及型別檢查。
IntelliSense
Visual Studio Code 的 JavaScript IntelliSense 提供智慧程式碼補全、引數資訊、引用搜索以及許多其他高階語言功能。我們的 JavaScript IntelliSense 由 TypeScript 團隊開發的 JavaScript 語言服務提供支援。雖然 IntelliSense 對大多數 JavaScript 專案無需任何配置即可正常工作，但您可以透過 JSDoc 或配置 jsconfig.json 專案來使其更加實用。
有關 JavaScript IntelliSense 工作原理的詳細資訊，包括基於型別推斷、JSDoc 註釋、TypeScript 宣告以及混合 JavaScript 和 TypeScript 專案，請參閱 JavaScript 語言服務文件。
當型別推斷無法提供所需資訊時，可以透過 JSDoc 註釋顯式提供型別資訊。本文件介紹了當前支援的 JSDoc 註釋。
除了物件、方法和屬性之外，JavaScript IntelliSense 視窗還提供對檔案中符號的基本單詞補全。
型別定義和自動型別獲取
JavaScript 庫和框架的 IntelliSense 由 TypeScript 型別宣告 (typings) 檔案提供支援。型別宣告檔案是用 TypeScript 編寫的，因此可以表達引數和函式的資料型別，從而使 VS Code 能夠以高效能的方式提供豐富的 IntelliSense 體驗。
許多流行的庫都附帶型別定義檔案，因此您可以自動獲得它們的 IntelliSense。對於不包含型別定義的庫，VS Code 的 自動型別獲取 將自動為您安裝社群維護的型別定義檔案。
自動型別獲取需要 npmjs，即 Node.js 包管理器，它包含在 Node.js 執行時中。在此影像中，您可以看到流行的 lodash 庫的 IntelliSense，包括方法簽名、引數資訊和方法文件。
Visual Studio Code 會自動下載並管理專案中 package.json 中列出或您匯入到 JavaScript 檔案中的包的型別宣告檔案。
{
"dependencies": {
"lodash": "^4.17.0"
}
}
您也可以在 jsconfig.json 中顯式列出要為其獲取型別宣告檔案的包。
{
"typeAcquisition": {
"include": ["jquery"]
}
}
大多數常見的 JavaScript 庫都附帶宣告檔案或有可用的型別宣告檔案。
修復自動型別獲取的 npm 未安裝警告
自動型別獲取使用 Node.js 包管理器 npm 來安裝和管理型別宣告 (typings) 檔案。為確保自動型別獲取正常工作，請首先確保您的計算機上已安裝 npm。
從終端或命令提示符執行 npm --version 以快速檢查 npm 是否已安裝並可用。
npm 隨 Node.js 執行時一起安裝，可從 Nodejs.org 下載。安裝當前的 LTS (長期支援) 版本，npm 可執行檔案將預設新增到您的系統路徑。
如果您已安裝 npm 但仍看到警告訊息，則可以透過 typescript.npm 設定顯式告訴 VS Code npm 的安裝位置。這應該設定為您計算機上 npm 可執行檔案的完整路徑，並且不必與您用於管理工作區中包的 npm 版本相匹配。typescript.npm 需要 TypeScript 2.3.4+。
例如，在 Windows 上，您將新增如下路徑到您的 settings.json 檔案中
{
"typescript.npm": "C:\\Program Files\\nodejs\\npm.cmd"
}
JavaScript 專案 (jsconfig.json)
目錄中存在 jsconfig.json 檔案表明該目錄是 JavaScript 專案的根目錄。jsconfig.json 指定了 JavaScript 語言服務提供的語言功能的根檔案和選項。對於常見設定，通常不需要 jsconfig.json 檔案，但是，在某些情況下，您會想新增一個 jsconfig.json。
- 並非所有檔案都應包含在您的 JavaScript 專案中 (例如，您可能希望排除某些檔案，使其不顯示 IntelliSense)。這種情況在前端和後端程式碼中很常見。
- 您的工作區包含多個專案上下文。在這種情況下，您應該為每個專案在根資料夾中新增一個
jsconfig.json檔案。 - 您正在使用 TypeScript 編譯器向下編譯 JavaScript 原始碼。
jsconfig.json 的位置
要將我們的程式碼定義為 JavaScript 專案，請在您的 JavaScript 程式碼的根目錄建立 jsconfig.json，如下所示。JavaScript 專案是專案的原始檔，不應包含派生檔案或打包檔案 (如 dist 目錄)。
在更復雜的專案中，您可能在一個工作區中有多個 jsconfig.json 檔案。您需要這樣做，以便一個專案的原始碼不會出現在另一個專案的 IntelliSense 中。
下圖展示了一個包含 client 和 server 資料夾的專案，其中顯示了兩個獨立的 JavaScript 專案
編寫 jsconfig.json
下面是 jsconfig.json 檔案的簡單模板，它將 JavaScript target 定義為 ES6，並且 exclude 屬性排除 node_modules 資料夾。您可以將此程式碼複製並貼上到您的 jsconfig.json 檔案中。
{
"compilerOptions": {
"module": "CommonJS",
"target": "ES6"
},
"exclude": ["node_modules", "**/node_modules/*"]
}
exclude 屬性告訴語言服務哪些檔案不屬於您的原始碼。如果 IntelliSense 速度很慢，請將資料夾新增到您的 exclude 列表中 (如果 VS Code 檢測到緩慢的補全，它會提示您這樣做)。您需要 exclude 由構建過程生成的檔案 (例如 dist 目錄)。這些檔案會導致建議重複顯示並減慢 IntelliSense 的速度。
您可以使用 include 屬性顯式設定專案中的檔案。如果不存在 include 屬性，則預設包含包含目錄及其子目錄中的所有檔案。當指定 include 屬性時，僅包含這些檔案。
下面是一個帶有顯式 include 屬性的示例
{
"compilerOptions": {
"module": "CommonJS",
"target": "ES6"
},
"include": ["src/**/*"]
}
最佳實踐，也是最不容易出錯的方法，是使用 include 屬性配合單個 src 資料夾。請注意，exclude 和 include 中的檔案路徑相對於 jsconfig.json 的位置。
有關更多資訊，請參閱完整的 jsconfig.json 文件。
遷移到 TypeScript
可以擁有混合 TypeScript 和 JavaScript 專案。要開始遷移到 TypeScript，請將您的 jsconfig.json 檔案重新命名為 tsconfig.json 並將 allowJs 屬性設定為 true。有關更多資訊，請參閱 從 JavaScript 遷移。
注意：
jsconfig.json與tsconfig.json檔案相同，只是將allowJs設定為 true。有關tsconfig.json的更多可用選項，請參閱tsconfig.json文件。
JavaScript 型別檢查
VS Code 允許您在常規 JavaScript 檔案中利用 TypeScript 的一些高階型別檢查和錯誤報告功能。這是捕獲常見程式設計錯誤的好方法。這些型別檢查還為 JavaScript 提供了一些令人興奮的快速修復，包括新增缺失的匯入和新增缺失的屬性。
TypeScript 可以像在 .ts 檔案中一樣在 .js 檔案中推斷型別。當無法推斷型別時，可以使用 JSDoc 註釋進行指定。您可以在 型別檢查 JavaScript 檔案中閱讀有關 TypeScript 如何使用 JSDoc 進行 JavaScript 型別檢查的更多資訊。
JavaScript 的型別檢查是可選的，需要使用者選擇加入。現有的 JavaScript 驗證工具 (如 ESLint) 可以與新的內建型別檢查功能一起使用。
您可以根據需要通過幾種不同的方式開始型別檢查。
按檔案
在 JavaScript 檔案中啟用型別檢查的最簡單方法是在檔案頂部新增 // @ts-check。
// @ts-check
let itsAsEasyAs = 'abc';
itsAsEasyAs = 123; // Error: Type '123' is not assignable to type 'string'
如果您只想在少數幾個檔案中嘗試型別檢查，而不是為整個程式碼庫啟用它，那麼使用 // @ts-check 是一個好方法。
使用設定
要為所有 JavaScript 檔案啟用型別檢查而不更改任何程式碼，只需將 "js/ts.implicitProjectConfig.checkJs": true 新增到您的工作區或使用者設定中。這會為任何不屬於 jsconfig.json 或 tsconfig.json 專案的 JavaScript 檔案啟用型別檢查。
您可以使用檔案頂部的 // @ts-nocheck 註釋來選擇不進行單個檔案的型別檢查
// @ts-nocheck
let easy = 'abc';
easy = 123; // no error
您還可以使用錯誤前一行上的 // @ts-ignore 註釋來停用 JavaScript 檔案中的單個錯誤
let easy = 'abc';
// @ts-ignore
easy = 123; // no error
使用 jsconfig 或 tsconfig
要為屬於 jsconfig.json 或 tsconfig.json 的 JavaScript 檔案啟用型別檢查，請將 "checkJs": true 新增到專案的編譯器選項中
jsconfig.json:
{
"compilerOptions": {
"checkJs": true
},
"exclude": ["node_modules", "**/node_modules/*"]
}
tsconfig.json:
{
"compilerOptions": {
"allowJs": true,
"checkJs": true
},
"exclude": ["node_modules", "**/node_modules/*"]
}
這會為專案中的所有 JavaScript 檔案啟用型別檢查。您可以使用 // @ts-nocheck 來按檔案停用型別檢查。
JavaScript 型別檢查需要 TypeScript 2.3。如果您不確定當前工作區中活動的是哪個版本的 TypeScript，請執行 TypeScript: Select TypeScript Version 命令進行檢查。要執行此命令，您必須在編輯器中開啟一個 .js/.ts 檔案。如果您開啟一個 TypeScript 檔案，版本會顯示在右下角。
全域性變數和型別檢查
假設您正在處理使用全域性變數或非標準 DOM API 的舊 JavaScript 程式碼
window.onload = function() {
if (window.webkitNotifications.requestPermission() === CAN_NOTIFY) {
window.webkitNotifications.createNotification(null, 'Woof!', '🐶').show();
} else {
alert('Could not notify');
}
};
如果您嘗試將 // @ts-check 與上述程式碼一起使用，您將看到許多關於使用全域性變數的錯誤
第 2 行-'Window' 上不存在屬性 'webkitNotifications'。第 2 行-找不到名稱 'CAN_NOTIFY'。第 3 行-'Window' 上不存在屬性 'webkitNotifications'。
如果您想繼續使用 // @ts-check，但確信這些不是您的應用程式的實際問題，那麼您必須讓 TypeScript 瞭解這些全域性變數。
首先，在專案根目錄 建立一個 jsconfig.json
{
"compilerOptions": {},
"exclude": ["node_modules", "**/node_modules/*"]
}
然後重新載入 VS Code 以確保更改已應用。jsconfig.json 的存在會讓 TypeScript 知道您的 Javascript 檔案是一個大型專案的一部分。
現在，在工作區中的某個位置建立一個 globals.d.ts 檔案
interface Window {
webkitNotifications: any;
}
declare var CAN_NOTIFY: number;
d.ts 檔案是型別宣告。在這種情況下，globals.d.ts 告訴 TypeScript 存在一個全域性變數 CAN_NOTIFY，並且 window 上存在一個 webkitNotifications 屬性。您可以在 TypeScript 文件中閱讀有關編寫 d.ts 的更多資訊。d.ts 檔案不會改變 JavaScript 的求值方式，它們僅用於提供更好的 JavaScript 語言支援。
使用任務
使用 TypeScript 編譯器
TypeScript 的一個關鍵特性是能夠使用最新的 JavaScript 語言特性，並生成可在尚未理解這些新特性的 JavaScript 執行時中執行的程式碼。由於 JavaScript 使用相同的語言服務，因此它也可以利用此相同的功能。
TypeScript 編譯器 tsc 可以將 ES6 的 JavaScript 檔案降級編譯到另一個語言級別。使用所需的選項配置 jsconfig.json，然後使用 -p 引數使 tsc 使用您的 jsconfig.json 檔案，例如 tsc -p jsconfig.json 進行降級編譯。
有關降級編譯的編譯器選項的更多資訊，請參閱 jsconfig 文件。
執行 Babel
Babel 轉譯器可以將 ES6 檔案轉換為可讀的 ES5 JavaScript，並帶有 Source Maps。您可以透過將下面的配置新增到 tasks.json 檔案中 (位於工作區的 .vscode 資料夾下) 來輕鬆地將 Babel 整合到您的工作流中。group 設定使此任務成為預設的 Task: Run Build Task 手勢。isBackground 告訴 VS Code 在後臺繼續執行此任務。要了解更多資訊，請訪問 任務。
{
"version": "2.0.0",
"tasks": [
{
"label": "watch",
"command": "${workspaceFolder}/node_modules/.bin/babel",
"args": ["src", "--out-dir", "lib", "-w", "--source-maps"],
"type": "shell",
"group": { "kind": "build", "isDefault": true },
"isBackground": true
}
]
}
新增此內容後，您可以透過 ⇧⌘B (Windows、Linux Ctrl+Shift+B) (執行構建任務) 命令啟動 Babel，它將把 src 目錄中的所有檔案編譯到 lib 目錄中。
提示： 有關 Babel CLI 的幫助，請參閱 使用 Babel 中的說明。上面的示例使用了 CLI 選項。
停用 JavaScript 支援
如果您更喜歡使用其他 JavaScript 語言工具 (如 Flow) 支援的 JavaScript 語言功能，則可以停用 VS Code 的內建 JavaScript 支援。您可以透過停用內建的 TypeScript 語言擴充套件 TypeScript and JavaScript Language Features (vscode.typescript-language-features) 來實現此目的，該擴充套件也提供 JavaScript 語言支援。
要停用 JavaScript/TypeScript 支援，請轉到 Extensions 檢視 (⇧⌘X (Windows、Linux Ctrl+Shift+X))，然後篩選內建擴充套件 (在 ... 更多操作下拉選單中選擇 顯示內建擴充套件)，然後鍵入 'typescript'。選擇 TypeScript and JavaScript Language Features 擴充套件，然後按 停用 按鈕。VS Code 內建擴充套件無法解除安裝，只能停用，並且可以隨時重新啟用。
IntelliSense 區域性模式
VS Code 嘗試為 JavaScript 和 TypeScript 提供專案範圍的 IntelliSense，這使得自動匯入和轉到定義等功能成為可能。但是，在某些情況下，VS Code 只能處理您當前開啟的檔案，而無法載入構成您的 JavaScript 或 TypeScript 專案的其他檔案。
這可能在幾種情況下發生
- 您正在 vscode.dev 或 github.dev 上使用 JavaScript 或 TypeScript 程式碼，並且 VS Code 在瀏覽器中執行。
- 您從虛擬檔案系統開啟一個檔案 (例如，在使用 GitHub Repositories 擴充套件時)。
- 專案正在載入中。載入完成後，您將開始獲得專案的專案範圍 IntelliSense。
在這些情況下，VS Code 的 IntelliSense 將以 區域性模式 執行。區域性模式會盡力為您開啟的任何 JavaScript 或 TypeScript 檔案提供 IntelliSense，但功能有限，無法提供任何跨檔案 IntelliSense 功能。
受影響的功能有哪些？
以下是區域性模式下停用或功能受限的功能的不完整列表
- 所有開啟的檔案都視為單個專案的一部分。
- 來自
jsconfig或tsconfig的配置選項 (例如target) 不會被尊重。 - 只報告語法錯誤。語義錯誤 — 例如訪問未知屬性或將錯誤型別傳遞給函式 — 不會被報告。
- 語義錯誤的快速修復被停用。
- 符號只能在當前檔案中解析。從其他檔案中匯入的任何符號都將被視為
any型別。 - 轉到定義和查詢所有引用等命令只能在開啟的檔案中工作，而不能在整個專案中工作。這也意味著
node_module下安裝的任何包中的符號都將無法解析。 - 工作區符號搜尋將僅包含當前開啟檔案中的符號。
- 自動匯入被停用。
- 重新命名被停用。
- 許多重構功能被停用。
在 vscode.dev 和 github.dev 上停用了一些附加功能
- 目前不支援自動型別獲取。
檢查是否處於區域性模式
要檢查當前檔案是否正在使用區域性模式 IntelliSense 而不是專案範圍 IntelliSense，請將狀態列中的 JavaScript 或 TypeScript 語言狀態項懸停在上面
如果當前檔案處於區域性模式，狀態項將顯示 Partial mode。