使用 JavaScript
本主题介绍 Visual Studio Code 支持的一些高级 JavaScript 功能。借助 TypeScript 语言服务，VS Code 可以为 JavaScript 提供智能补全（智能感知）以及类型检查。
智能感知
Visual Studio Code 的 JavaScript 智能感知提供智能代码补全、参数信息、引用搜索以及许多其他高级语言功能。我们的 JavaScript 智能感知由 TypeScript 团队开发的JavaScript 语言服务提供支持。虽然智能感知对于大多数 JavaScript 项目来说应该不需要任何配置即可工作，但你可以通过 JSDoc 或配置 jsconfig.json 项目来使智能感知更加有用。
有关 JavaScript 智能感知如何工作的详细信息，包括其基于类型推断、JSDoc 注解、TypeScript 声明以及 JavaScript 和 TypeScript 项目的混合，请参阅JavaScript 语言服务文档。
当类型推断无法提供所需信息时，可以使用 JSDoc 注解明确提供类型信息。本文档介绍了目前支持的JSDoc 注解。
除了对象、方法和属性外，JavaScript 智能感知窗口还为文件中的符号提供基本单词补全。
类型定义和自动类型获取
JavaScript 库和框架的智能感知由 TypeScript 类型声明（类型定义）文件提供支持。类型声明文件以 TypeScript 编写，因此它们可以表达参数和函数的数据类型，从而使 VS Code 能够以高性能的方式提供丰富的智能感知体验。
许多流行的库都附带类型定义文件，因此你可以自动获取它们的智能感知。对于不包含类型定义的库，VS Code 的自动类型获取将自动为你安装社区维护的类型定义文件。
自动类型获取需要 npmjs，即 Node.js 包管理器，它随 Node.js 运行时一起安装。在此图中，你可以看到智能感知，包括方法签名、参数信息以及流行的 lodash 库的方法文档。
对于项目中 package.json 中列出的或你导入到 JavaScript 文件中的包，Visual Studio Code 会自动下载并管理其类型声明文件。
{
"dependencies": {
"lodash": "^4.17.0"
}
}
你也可以在 jsconfig.json 中明确列出需要获取类型声明文件的包。
{
"typeAcquisition": {
"include": ["jquery"]
}
}
大多数常用的 JavaScript 库都附带声明文件或有可用的类型声明文件。
修复自动类型获取提示“npm 未安装”的警告
自动类型获取使用 npm，即 Node.js 包管理器，来安装和管理类型声明文件。为了确保自动类型获取正常工作，首先请确保你的计算机上安装了 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 项目中（例如，你希望排除某些文件不显示智能感知）。这种情况在前端和后端代码中很常见。
- 你的工作区包含多个项目上下文。在这种情况下，你应该在每个项目的根文件夹中添加一个
jsconfig.json文件。 - 你正在使用 TypeScript 编译器向下编译 JavaScript 源代码。
jsconfig.json 的位置
要将代码定义为 JavaScript 项目，请在 JavaScript 代码的根目录创建 jsconfig.json，如下所示。JavaScript 项目是项目的源文件，不应包含派生或打包文件（例如 dist 目录）。
在更复杂的项目中，你可能会在工作区内定义多个 jsconfig.json 文件。你这样做是为了避免一个项目中的源代码出现在另一个项目的智能感知中。
下图展示了一个包含 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 属性告诉语言服务哪些文件不是源代码的一部分。如果智能感知很慢，请将文件夹添加到 exclude 列表中（如果 VS Code 检测到补全速度慢，会提示你执行此操作）。你会想要exclude 由构建过程生成的文件（例如 dist 目录）。这些文件会导致建议出现两次，并会减慢智能感知速度。
你可以使用 include 属性明确设置项目中的文件。如果不存在 include 属性，则默认包含包含目录及其子目录中的所有文件。指定 include 属性时，仅包含这些文件。
这是一个带有明确 include 属性的示例
{
"compilerOptions": {
"module": "CommonJS",
"target": "ES6"
},
"include": ["src/**/*"]
}
最佳实践且最不容易出错的方法是使用带有单个 src 文件夹的 include 属性。请注意，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文档以了解其他可用选项。
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: 选择 TypeScript 版本命令进行检查。你必须在编辑器中打开一个 .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，你会看到许多关于使用全局变量的错误
Line 2-属性 'webkitNotifications' 在类型 'Window' 上不存在。Line 2-找不到名称 'CAN_NOTIFY'。Line 3-属性 'webkitNotifications' 在类型 'Window' 上不存在。
如果你想继续使用 // @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 可以将 JavaScript 文件从 ES6 向下编译到另一个语言级别。使用所需的选项配置 jsconfig.json，然后使用 –p 参数让 tsc 使用你的 jsconfig.json 文件，例如 tsc -p jsconfig.json 进行向下编译。
在jsconfig 文档中阅读更多关于向下编译的编译器选项的信息。
运行 Babel
Babel 转译器将 ES6 文件转换为带 Source Maps 的可读 ES5 JavaScript。你可以通过在 tasks.json 文件（位于工作区的 .vscode 文件夹下）中添加以下配置，轻松地将 Babel 集成到你的工作流程中。group 设置将此任务设为默认的任务：运行构建任务手势。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 支持，请转到扩展视图（⇧⌘X (Windows, Linux Ctrl+Shift+X)），然后筛选内置扩展（在 ... 更多操作下拉菜单中选择显示内置扩展），然后输入 'typescript'。选择 TypeScript and JavaScript Language Features 扩展并按下禁用按钮。VS Code 内置扩展无法卸载，只能禁用，并且随时可以重新启用。
部分智能感知模式
VS Code 尝试为 JavaScript 和 TypeScript 提供项目范围的智能感知，这使得自动导入和转到定义等功能成为可能。但是，在某些情况下，VS Code 仅限于处理当前打开的文件，无法加载组成 JavaScript 或 TypeScript 项目的其他文件。
这可能在以下几种情况下发生
- 你在 vscode.dev 或 github.dev 上处理 JavaScript 或 TypeScript 代码，并且 VS Code 在浏览器中运行。
- 你从虚拟文件系统打开文件（例如使用 GitHub 仓库扩展时）。
- 项目当前正在加载。加载完成后，你将开始获取该项目的项目范围智能感知。
在这些情况下，VS Code 的智能感知将以部分模式运行。部分模式会尽最大努力为你打开的任何 JavaScript 或 TypeScript 文件提供智能感知，但功能有限，无法提供任何跨文件智能感知功能。
哪些功能会受到影响？
以下是在部分模式下被禁用或功能受限的功能列表（不完整）
- 所有打开的文件都被视为单个项目的一部分。
- 你的
jsconfig或tsconfig中的配置选项（例如target）将不受尊重。 - 仅报告语法错误。不报告语义错误——例如访问未知属性或向函数传递错误类型。
- 语义错误的快速修复被禁用。
- 符号只能在当前文件中解析。从其他文件导入的任何符号将被视为
any类型。 - 诸如转到定义和查找所有引用之类的命令仅适用于打开的文件，而不适用于整个项目。这也意味着无法解析从
node_module下安装的任何包中的符号。 - 工作区符号搜索将仅包含当前打开文件中的符号。
- 自动导入被禁用。
- 重命名被禁用。
- 许多重构被禁用。
在 vscode.dev 和 github.dev 上还禁用了一些附加功能
- 自动类型获取当前不支持。
检查你是否处于部分模式
要检查当前文件是否使用部分模式智能感知而不是项目范围智能感知，请将鼠标悬停在状态栏中的 JavaScript 或 TypeScript 语言状态项上
如果当前文件处于部分模式，状态项将显示 Partial mode。