Merge pull request #1304 from Kingwl/project_options

(zh) Add project options

Author: github-actions[bot]

packages/tsconfig-reference/copy/zh/categories/Basic_Options_6172.md

@@ -0,0 +1,5 @@
+---
+display: "工程选项"
+---
+
+这些设置将用于指定你的工程的运行时配置，你希望 JavaScript 怎样被生成和生成在哪里，以及你希望与现有 JavaScript 代码的集成程度。

packages/tsconfig-reference/copy/zh/options/allowJs.md

@@ -0,0 +1,39 @@
+---
+display: "允许 JS"
+oneline: "允许你的程序包含 JS 文件。使用 checkJS 来检查在这些文件中的错误。"
+---
+
+允许 JavaScript 文件在你的工程中被引入，而不是仅仅允许 `.ts` 和 `.tsx` 文件。例如这个 JS 文件：
+
+```js twoslash
+// @filename: card.js
+export const defaultCardDeck = "Heart";
+```
+
+当你引入到一个 TypeScript 文件时将会抛出一个错误：
+
+```ts twoslash
+// @errors: 2307
+// @filename: card.js
+module.exports.defaultCardDeck = "Heart";
+// ---cut---
+// @filename: index.ts
+import { defaultCardDeck } from "./card";
+
+console.log(defaultCardDeck);
+```
+
+当启用 `allowJs` 后它将被正常引入：
+
+```ts twoslash
+// @filename: card.js
+module.exports.defaultCardDeck = "Heart";
+// ---cut---
+// @allowJs
+// @filename: index.ts
+import { defaultCardDeck } from "./card";
+
+console.log(defaultCardDeck);
+```
+
+这个选项是一种可以允许 `.ts` 和 `.tsx` 与现有的 JavaScript 文件共存的方式。可以用于逐步将 TypeScript 文件逐步添加到 JS 工程中。

packages/tsconfig-reference/copy/zh/options/checkJs.md

@@ -0,0 +1,39 @@
+---
+display: "检查 JS"
+oneline: "在经过类型检查的 JavaScript 中报告错误。"
+---
+
+与 `allowJs` 配合使用，当 `checkJs` 被启用时，JavaScript 文件中会报告错误。也就是相当于在项目中所有 JavaScript 文件顶部包含 `// @ts-check`。
+
+例如，根据 TypeScript 自带的 `parseFloat` 类型定义，这是不正确的 JavaScript：
+
+```js
+// parseFloat 仅接受一个字符串作为参数
+module.exports.pi = parseFloat(3.124);
+```
+
+当引入到一个 TypeScript 模块：
+
+```ts twoslash
+// @allowJs
+// @filename: constants.js
+module.exports.pi = parseFloat(3.124);
+
+// @filename: index.ts
+import { pi } from "./constants";
+console.log(pi);
+```
+
+你将不会得到任何错误。但是如果你开启了 `checkJs` 选项，那么你可以从 JavaScript 文件中得到错误信息。
+
+```ts twoslash
+// @errors: 2345
+// @allowjs: true
+// @checkjs: true
+// @filename: constants.js
+module.exports.pi = parseFloat(3.124);
+
+// @filename: index.ts
+import { pi } from "./constants";
+console.log(pi);
+```

packages/tsconfig-reference/copy/zh/options/composite.md

@@ -0,0 +1,16 @@
+---
+display: "组合"
+oneline: "启用约束以使工程可以引用其他工程来用于构建。"
+---
+
+`composite` 选项会强制执行某些约束，使得构建工具（包括 在 `--build` 模式下的 TypeScript 本身）可以快速确定一个工程是否已经建立。
+
+当此设置开启时：
+
+- 如果没有明确指定 `rootDir`，则默认为包含 `tsconfig.json` 文件的目录。
+
+- 所有实现的文件必须由 `include` 来匹配，或在 `files` 数组中指定。如果违反了这一约束，`tsc` 将告诉你哪些文件没有被指定。
+
+- `declaration` 默认为 `true`。
+
+你可以在[手册](https://www.typescriptlang.org/docs/handbook/project-references.html)中找到关于 TypeScript 工程的文档。

packages/tsconfig-reference/copy/zh/options/declaration.md

@@ -0,0 +1,32 @@
+---
+display: "声明"
+oneline: "为你工程中的 TypeScript 以及 JavaScript 文件生成 .d.ts 文件。"
+---
+
+为你工程中的每个 TypeScript 或 JavaScript 文件生成 `.d.ts` 文件。
+这些 `.d.ts` 文件是描述模块外部 API 的类型定义文件。
+像 TypeScript 这样的哦你根据可以通过 `.d.ts` 文件为非类型化的代码提供 intellisense 和精确的类型。
+
+当 `declaration` 设置为 `true` 时，用编译器执行下面的 TypeScript 代码：
+
+```ts twoslash
+export let helloWorld = "hi";
+```
+
+将会生成如下这样的 `index.js` 文件：
+
+```ts twoslash
+// @showEmit
+export let helloWorld = "hi";
+```
+
+以及一个相应的 `helloWorld.d.ts`：
+
+```ts twoslash
+// @showEmittedFile: index.d.ts
+// @showEmit
+// @declaration
+export let helloWorld = "hi";
+```
+
+当使用 `.d.ts` 文件处理 JavaScript 文件时，你可能需要使用 [`emitDeclarationOnly`](#emitDeclarationOnly) 或 [`outDir`](#outDir) 来确保 JavaScript 文件不会被覆盖。

packages/tsconfig-reference/copy/zh/options/downlevelIteration.md

@@ -0,0 +1,96 @@
+---
+display: "迭代器降级"
+oneline: "为迭代器对象生成更符合要求但更复杂的 JavaScript。"
+---
+
+‘降级’ 是 TypeScript 的术语，指用于转换到旧版本的 JavaScript。
+这个选项是为了在旧版 Javascript 运行时上更准确的实现现代 JavaScript 迭代器的概念。
+
+ECMAScript 6 增加了几个新的迭代器原语：`for / of` 循环（`for (el of arr)`），数组展开（`[a, ...b]`），参数展开（`fn(...args)`）和 `Symbol.iterator`。
+
+如果 `Symbol.iterator` 存在的话，`--downlevelIteration` 将允许在 ES5 环境更准确的使用这些迭代原语。
+
+#### 例：`for / of` 的效果
+
+对于 TypeScript 代码：
+
+```ts twoslash
+const str = "Hello!";
+for (const s of str) {
+  console.log(s);
+}
+```
+
+如果没有启用 `downlevelIteration`，`for / of` 循环将被降级为传统的 `for` 循环：
+
+```ts twoslash
+// @target: ES5
+// @showEmit
+const str = "Hello!";
+for (const s of str) {
+  console.log(s);
+}
+```
+
+这通常是人们所期望的，但是它并不是 100% 符合 ECMAScript 迭代器协议。
+某些字符串，例如 emoji （😜），其 `.length` 为 2（甚至更多），但在 `for-of` 循环中应只有一次迭代。
+可以在 [Jonathan New 的这篇文章中](https://blog.jonnew.com/posts/poo-dot-length-equals-two) 找到更详细的解释。
+
+当 `downlevelIteration` 启用时，TypeScript 将会使用辅助函数来检查 `Symbol.iterator` 的实现（无论是原生实现还是polyfill）。
+如果没有实现，则将会回退到基于索引的迭代。
+
+```ts twoslash
+// @target: ES5
+// @downlevelIteration
+// @showEmit
+const str = "Hello!";
+for (const s of str) {
+  console.log(s);
+}
+```
+
+你也可以通过 [`importHelpers`](#importHelpers) 来使用 [tslib](https://www.npmjs.com/package/tslib) 以减少被内联的 JavaScript 的数量：
+
+```ts twoslash
+// @target: ES5
+// @downlevelIteration
+// @importHelpers
+// @showEmit
+const str = "Hello!";
+for (const s of str) {
+  console.log(s);
+}
+```
+
+**注：** 如果在运行时不存在 `Symbol.iterator`，启用 `downlevelIteration` 将不会提高合规性。
+
+#### 例：数组展开的效果
+
+这是一个数组展开：
+
+```js
+// 构建一个新的数组，其元素首先为 1，然后是 arr2 的元素。 
+const arr = [1, ...arr2];
+```
+根据描述，听起来很容易降级到 ES5：
+
+```js
+// The same, right?
+const arr = [1].concat(arr2);
+```
+
+但是在某些罕见的情况下会明显不同。例如如果数组中有一个“洞”，缺失的索引在展开时将创建一个 _自己的_ 属性，但若使用 `concat` 则不会： 
+
+```js
+// 构建一个元素 `1` 不存在的数组
+let missing = [0, , 1];
+let spreaded = [...missing];
+let concated = [].concat(missing);
+
+// true
+"1" in spreaded;
+// false
+"1" in concated;
+```
+
+就像 `for / of` 一样，`downlevelIteration` 将使用 `Symbol.iterator`（如果存在的话）来更准确的模拟 ES6 的行为。

packages/tsconfig-reference/copy/zh/options/importHelpers.md

@@ -0,0 +1,47 @@
+---
+display: "导入辅助"
+oneline: "允许每个项目从 tslib 中导入一次辅助函数，而不是在每个文件中都包含他们。"
+---
+
+对于某些降级行为，TypeScript 使用一些辅助代码来进行操作。例如继承类，展开数组或对象，以及异步操作。
+默认情况下，这些辅助代码被插入到使用它们的文件中。
+如果在许多不同的模块中使用相同的辅助代码，则可能会导致代码重复。
+
+如果启用了 `importHelpers` 选项，这些辅助函数将从 [tslib](https://www.npmjs.com/package/tslib) 中被导入。
+你需要确保 `tslib` 模块在运行时可以被导入。
+这只影响模块，全局脚本文件不会尝试导入模块。
+
+例如，对于如下 TypeScript 代码：
+
+```ts
+export function fn(arr: number[]) {
+  const arr2 = [1, ...arr];
+}
+```
+
+开启 [`downlevelIteration`](#downlevelIteration) 并且 `importHelpers` 仍为 `false`：
+
+```ts twoslash
+// @showEmit
+// @target: ES5
+// @downleveliteration
+export function fn(arr: number[]) {
+  const arr2 = [1, ...arr];
+}
+```
+
+同时开始 [`downlevelIteration`](#downlevelIteration) 和 `importHelpers`：
+
+```ts twoslash
+// @showEmit
+// @target: ES5
+// @downleveliteration
+// @importhelpers
+// @noErrors
+export function fn(arr: number[]) {
+  const arr2 = [1, ...arr];
+}
+```
+
+当你提供了自行实现的这些函数时，你可以使用 [`noEmitHelpers`](#noEmitHelpers)。
+

packages/tsconfig-reference/copy/zh/options/incremental.md

@@ -0,0 +1,10 @@
+---
+display: "增量"
+oneline: "为支持增量编译工程，保存 .tsbuildinfo 文件"
+---
+
+使 TypeScript 将上次编译的工程图信息保存到磁盘上的文件中。这将会在您编译输出的同一文件夹中创建一系列 `.tsbuildinfo` 文件。
+它们不会再运行时被您的 JavaScript 使用，并且可以被安全的删除。
+你可以在 [3.4 发布日志](/docs/handbook/release-notes/typescript-3-4.html#faster-subsequent-builds-with-the---incremental-flag) 中获取更多关于该选项的内容。
+
+可以使用 [`tsBuildInfoFile`](#tsBuildInfoFile) 来控制 `.tsbuildinfo` 文件被编译到哪个文件夹。

packages/tsconfig-reference/copy/zh/options/isolatedModules.md

@@ -0,0 +1,75 @@
+---
+display: "孤立模块"
+oneline: "确保每个文件都可以不依赖于其他导入而被安全转译。"
+---
+
+虽然你可以使用 TypeScript 来从 TypeScript 中生成 JavaScript 代码，但是使用其他转译器例如 [Babel](https://babeljs.io) 也很常见。
+但其他转译器一次只能在一个文件上操作，这意味着它们不能进行基于完全理解类型系统后的代码转译。
+这个限制也同样适用于被一些构建工具使用的 TypeScript 的 `ts.transpileModule` 接口。
+
+这些限制可能会导致一些 TypeScript 特性的运行时问题，例如 `const enum` 和 `namespace`。
+设置 `isolatedModules` 选项后，TypeScript 将会在当你写的某些代码不能被单文件转译的过程正确处理时警告你。
+
+它不会改变你代码的行为，也不会影响 TypeScript 的检查和代码生成过程。
+
+一些当 `isolatedModules` 被启用时不工作的例子：
+
+#### 导出非值标识符
+
+在 TypeScript 中，你可以引入一个 _类型_，然后再将其导出：
+
+```ts twoslash
+// @noErrors
+import { someType, someFunction } from "someModule";
+
+someFunction();
+
+export { someType, someFunction };
+```
+
+由于 `someType` 并没有值，所以生成的 `export` 将不会导出它（否则将导致 JavaScript 运行时的错误）：
+
+```js
+export { someFunction };
+```
+
+单文件转译器并不知道 `someType` 是否会产生一个值，所以导出一个只指向类型的名称会是一个错误。
+
+#### 非模块文件
+
+如果设置了 `isolatedModules`，则所有的实现文件必须是 _模块_ （也就是它有某种形式的 `import`/`export`）。如果任意文件不是模块就会发生错误：
+
+```ts twoslash
+// @errors: 1208
+// @isolatedModules
+function fn() {}
+```
+
+此限制不适用于 `.d.ts` 文件
+
+#### 指向 `const enum` 成员
+
+在 TypeScript 中，当你引用一个 `const enum` 的成员时，该引用在生成的 JavaScript 中将会被其实际值所代替。这会将这样的 TypeScript 代码： 
+
+```ts twoslash
+declare const enum Numbers {
+  Zero = 0,
+  One = 1,
+}
+console.log(Numbers.Zero + Numbers.One);
+```
+
+转换为这样的 JavaScript：
+
+```ts twoslash
+// @showEmit
+// @removeComments
+declare const enum Numbers {
+  Zero = 0,
+  One = 1,
+}
+console.log(Numbers.Zero + Numbers.One);
+```
+
+在不知道这些成员值的情况下，其他转译器不能替换对 `Numbers` 的引用。如果无视的话则会导致运行时错误（运行时没有 `Numbers`） 对象。
+正因如此，当启用 `isolatedModules` 时，引用环境中的 `const enum` 成员将会是一个错误。