TypeScript 3.7

可选链式调用

🌐 Optional Chaining

游乐场

可选链在我们的问题追踪器上是 问题 #16。作为背景，自那以后，TypeScript 问题追踪器上已经有超过 23,000 个问题。

🌐 Optional chaining is issue #16 on our issue tracker. For context, there have been over 23,000 issues on the TypeScript issue tracker since then.

从根本上说，可选链让我们可以编写这样的代码：如果遇到 null 或 undefined，TypeScript 可以立即停止运行某些表达式。可选链的核心是用于_可选属性访问_的新 ?. 运算符。当我们编写如下代码时

🌐 At its core, optional chaining lets us write code where TypeScript can immediately stop running some expressions if we run into a null or undefined. The star of the show in optional chaining is the new ?. operator for optional property accesses. When we write code like

ts
let x = foo?.bar.baz();

这是一种表达方式，意思是当 foo 被定义时，foo.bar.baz() 将被计算；但当 foo 是 null 或 undefined 时，停止我们正在做的事情，直接返回 undefined。

🌐 this is a way of saying that when foo is defined, foo.bar.baz() will be computed; but when foo is null or undefined, stop what we’re doing and just return undefined.”

更直白地说，该代码片段与编写以下内容相同。

🌐 More plainly, that code snippet is the same as writing the following.

ts
let x = foo === null || foo === undefined ? undefined : foo.bar.baz();

请注意，如果 bar 是 null 或 undefined，我们的代码在访问 baz 时仍然会出错。同样，如果 baz 是 null 或 undefined，我们在调用处也会遇到错误。?. 只检查它左侧的值是否为 null 或 undefined——而不会检查后续的任何属性。

🌐 Note that if bar is null or undefined, our code will still hit an error accessing baz. Likewise, if baz is null or undefined, we’ll hit an error at the call site. ?. only checks for whether the value on the left of it is null or undefined - not any of the subsequent properties.

你可能会发现自己使用 ?. 来替换大量使用 && 运算符进行重复空值检查的代码。

🌐 You might find yourself using ?. to replace a lot of code that performs repetitive nullish checks using the && operator.

ts
// Before
if (foo && foo.bar && foo.bar.baz) {
  // ...
}
// After-ish
if (foo?.bar?.baz) {
  // ...
}

请记住，?. 的行为与那些 && 操作不同，因为 && 会对“假值”（例如空字符串、0、NaN，以及 false）有特殊处理，但这是该结构的一个有意设计特性。它不会像 0 或空字符串那样在有效数据上进行短路处理。

🌐 Keep in mind that ?. acts differently than those && operations since && will act specially on “falsy” values (e.g. the empty string, 0, NaN, and, well, false), but this is an intentional feature of the construct. It doesn’t short-circuit on valid data like 0 or empty strings.

可选链还包括另外两个操作。首先是_可选元素访问_，它的作用类似于可选属性访问，但允许我们访问非标识符属性（例如任意字符串、数字和符号）:

🌐 Optional chaining also includes two other operations. First there’s the optional element access which acts similarly to optional property accesses, but allows us to access non-identifier properties (e.g. arbitrary strings, numbers, and symbols):

ts
/**
 * Get the first element of the array if we have an array.
 * Otherwise return undefined.
 */
function tryGetFirstElement<T>(arr?: T[]) {
  return arr?.[0];
  // equivalent to
  //   return (arr === null || arr === undefined) ?
  //       undefined :
  //       arr[0];
}

还有一个 可选调用，它允许我们在表达式不是 null 或 undefined 时有条件地调用它们。

🌐 There’s also optional call, which allows us to conditionally call expressions if they’re not null or undefined.

ts
async function makeRequest(url: string, log?: (msg: string) => void) {
  log?.(`Request started at ${new Date().toISOString()}`);
  // roughly equivalent to
  //   if (log != null) {
  //       log(`Request started at ${new Date().toISOString()}`);
  //   }
  const result = (await fetch(url)).json();
  log?.(`Request finished at ${new Date().toISOString()}`);
  return result;
}

可选链的“短路”行为仅限于属性访问、函数调用和元素访问——它不会进一步扩展到这些表达式之外。换句话说，

🌐 The “short-circuiting” behavior that optional chains have is limited property accesses, calls, element accesses - it doesn’t expand any further out from these expressions. In other words,

ts
let result = foo?.bar / someComputation();

不会阻止除法或 someComputation() 调用的发生。 它等同于

🌐 doesn’t stop the division or someComputation() call from occurring. It’s equivalent to

ts
let temp = foo === null || foo === undefined ? undefined : foo.bar;
let result = temp / someComputation();

这可能会导致划分 undefined，这就是为什么在 strictNullChecks 中，以下内容是错误的。

🌐 That might result in dividing undefined, which is why in strictNullChecks, the following is an error.

ts
function barPercentage(foo?: { bar: number }) {
  return foo?.bar / 100;
  //     ~~~~~~~~
  // Error: Object is possibly undefined.
}

更多详细信息，你可以阅读提案并查看原始拉取请求。

🌐 More more details, you can read up on the proposal and view the original pull request.

空值合并

🌐 Nullish Coalescing

游乐场

“空值合并运算符”是另一个即将推出的 ECMAScript 特性，它与可选链操作符密切相关，我们团队一直在 TC39 中积极推动这一特性。

🌐 The nullish coalescing operator is another upcoming ECMAScript feature that goes hand-in-hand with optional chaining, and which our team has been involved with championing in TC39.

你可以把这个功能——?? 操作符——看作是在处理 null 或 undefined 时“回退”到默认值的一种方式。当我们编写这样的代码时

🌐 You can think of this feature - the ?? operator - as a way to “fall back” to a default value when dealing with null or undefined. When we write code like

ts
let x = foo ?? bar();

这是一种新的说法，用来表示当值为 foo 时将使用它；但当值为 null 或 undefined 时，则计算 bar() 代替它。

🌐 this is a new way to say that the value foo will be used when it’s “present”; but when it’s null or undefined, calculate bar() in its place.

同样，上述代码等同于以下代码。

🌐 Again, the above code is equivalent to the following.

ts
let x = foo !== null && foo !== undefined ? foo : bar();

?? 操作符可以在尝试使用默认值时替代 || 的使用。例如，以下代码片段尝试获取最后保存在 localStorage 中的音量（如果曾经保存过）；然而，它存在一个错误，因为它使用了 ||。

🌐 The ?? operator can replace uses of || when trying to use a default value. For example, the following code snippet tries to fetch the volume that was last saved in localStorage (if it ever was); however, it has a bug because it uses ||.

ts
function initializeAudio() {
  let volume = localStorage.volume || 0.5;
  // ...
}

当 localStorage.volume 设置为 0 时，页面会将音量设置为 0.5，这是非预期的行为。 ?? 避免了 0、NaN 和 "" 被视为假值而导致的一些非预期行为。

🌐 When localStorage.volume is set to 0, the page will set the volume to 0.5 which is unintended. ?? avoids some unintended behavior from 0, NaN and "" being treated as falsy values.

我们非常感谢社区成员Wenlu Wang和Titian Cernicova Dragomir实现了这一功能！ 更多详情，请查看他们的拉取请求以及空值合并运算符提案仓库。

🌐 We owe a large thanks to community members Wenlu Wang and Titian Cernicova Dragomir for implementing this feature! For more details, check out their pull request and the nullish coalescing proposal repository.

断言函数

🌐 Assertion Functions

游乐场

有一组特定的函数，当发生意外情况时会让 throw 抛出错误。它们被称为“断言”函数。举个例子，Node.js 有一个专门用于此的函数，叫做 assert。

🌐 There’s a specific set of functions that throw an error if something unexpected happened. They’re called “assertion” functions. As an example, Node.js has a dedicated function for this called assert.

js
assert(someValue === 42);

在这个例子中，如果 someValue 不等于 42，那么 assert 将抛出一个 AssertionError。

🌐 In this example if someValue isn’t equal to 42, then assert will throw an AssertionError.

在 JavaScript 中，断言通常用于防止传入不正确的类型。例如，

🌐 Assertions in JavaScript are often used to guard against improper types being passed in. For example,

js
function multiply(x, y) {
  assert(typeof x === "number");
  assert(typeof y === "number");
  return x * y;
}

不幸的是，在 TypeScript 中这些检查永远无法被正确编码。对于类型松散的代码，这意味着 TypeScript 检查得较少，而对于稍微保守的代码，它通常会迫使用户使用类型断言。

🌐 Unfortunately in TypeScript these checks could never be properly encoded. For loosely-typed code this meant TypeScript was checking less, and for slightly conservative code it often forced users to use type assertions.

ts
function yell(str) {
  assert(typeof str === "string");
  return str.toUppercase();
  // Oops! We misspelled 'toUpperCase'.
  // Would be great if TypeScript still caught this!
}

另一种方法是重写代码，以便语言可以分析它，但这并不方便。

🌐 The alternative was to instead rewrite the code so that the language could analyze it, but this isn’t convenient.

ts
function yell(str) {
  if (typeof str !== "string") {
    throw new TypeError("str should have been a string.");
  }
  // Error caught!
  return str.toUppercase();
}

最终，TypeScript 的目标是在尽可能不干扰现有 JavaScript 构造的情况下进行类型化。为此，TypeScript 3.7 引入了一个称为“断言签名”的新概念，用于建模这些断言函数。

🌐 Ultimately the goal of TypeScript is to type existing JavaScript constructs in the least disruptive way. For that reason, TypeScript 3.7 introduces a new concept called “assertion signatures” which model these assertion functions.

第一种类型的断言签名模拟了 Node 的 assert 函数的工作方式。它确保正在检查的条件在包含范围的其余部分必须为真。

🌐 The first type of assertion signature models the way that Node’s assert function works. It ensures that whatever condition is being checked must be true for the remainder of the containing scope.

ts
function assert(condition: any, msg?: string): asserts condition {
  if (!condition) {
    throw new AssertionError(msg);
  }
}

asserts condition 说，传入 condition 参数的任何值都必须为真，如果 assert 返回（因为否则会抛出错误）。
这意味着在其余的作用域中，该条件必须为真值。
例如，使用这个断言函数意味着我们确实捕获了最初的 yell 示例。

ts
function yell(str) {
  assert(typeof str === "string");
  return str.toUppercase();
  //         ~~~~~~~~~~~
  // error: Property 'toUppercase' does not exist on type 'string'.
  //        Did you mean 'toUpperCase'?
}
function assert(condition: any, msg?: string): asserts condition {
  if (!condition) {
    throw new AssertionError(msg);
  }
}

另一种断言签名不会检查条件，而是告诉 TypeScript 特定变量或属性具有不同的类型。

🌐 The other type of assertion signature doesn’t check for a condition, but instead tells TypeScript that a specific variable or property has a different type.

ts
function assertIsString(val: any): asserts val is string {
  if (typeof val !== "string") {
    throw new AssertionError("Not a string!");
  }
}

这里 asserts val is string 确保在任何对 assertIsString 的调用之后，传入的任何变量都将被明确认定为 string。

🌐 Here asserts val is string ensures that after any call to assertIsString, any variable passed in will be known to be a string.

ts
function yell(str: any) {
  assertIsString(str);
  // Now TypeScript knows that 'str' is a 'string'.
  return str.toUppercase();
  //         ~~~~~~~~~~~
  // error: Property 'toUppercase' does not exist on type 'string'.
  //        Did you mean 'toUpperCase'?
}

这些断言签名与编写类型谓词签名非常相似：

🌐 These assertion signatures are very similar to writing type predicate signatures:

ts
function isString(val: any): val is string {
  return typeof val === "string";
}
function yell(str: any) {
  if (isString(str)) {
    return str.toUppercase();
  }
  throw "Oops!";
}

就像类型谓词签名一样，这些断言签名也非常有表现力。我们可以用它们表达一些相当复杂的想法。

🌐 And just like type predicate signatures, these assertion signatures are incredibly expressive. We can express some fairly sophisticated ideas with these.

ts
function assertIsDefined<T>(val: T): asserts val is NonNullable<T> {
  if (val === undefined || val === null) {
    throw new AssertionError(
      `Expected 'val' to be defined, but received ${val}`
    );
  }
}

要了解更多关于断言签名的信息，请查看原始拉取请求。

🌐 To read up more about assertion signatures, check out the original pull request.

更好地支持返回 never 的函数

🌐 Better Support for never-Returning Functions

作为断言签名工作的一个部分，TypeScript 需要更多地编码有关函数被调用的位置和类型的信息。这给了我们扩展对另一类函数支持的机会：返回 never 的函数。

🌐 As part of the work for assertion signatures, TypeScript needed to encode more about where and which functions were being called. This gave us the opportunity to expand support for another class of functions: functions that return never.

任何返回 never 的函数的意图是它永远不会返回。它表示抛出了异常、发生了致命错误，或者程序已退出。例如，process.exit(...) 在 @types/node 被规定返回 never。

🌐 The intent of any function that returns never is that it never returns. It indicates that an exception was thrown, a halting error condition occurred, or that the program exited. For example, process.exit(...) in @types/node is specified to return never.

为了确保一个函数永远不会潜在地返回 undefined 或实际上从所有代码路径返回，TypeScript 需要某种语法信号——要么在函数末尾使用 return，要么使用 throw。 因此，用户发现自己在对他们的失败函数进行 return。

🌐 In order to ensure that a function never potentially returned undefined or effectively returned from all code paths, TypeScript needed some syntactic signal - either a return or throw at the end of a function. So users found themselves return-ing their failure functions.

ts
function dispatch(x: string | number): SomeType {
  if (typeof x === "string") {
    return doThingWithString(x);
  } else if (typeof x === "number") {
    return doThingWithNumber(x);
  }
  return process.exit(1);
}

现在，当这些返回 never 的函数被调用时，TypeScript 会识别它们会影响控制流图并进行相应处理。

🌐 Now when these never-returning functions are called, TypeScript recognizes that they affect the control flow graph and accounts for them.

ts
function dispatch(x: string | number): SomeType {
  if (typeof x === "string") {
    return doThingWithString(x);
  } else if (typeof x === "number") {
    return doThingWithNumber(x);
  }
  process.exit(1);
}

与断言函数一样，你可以在同一个拉取请求中查看更多内容。

🌐 As with assertion functions, you can read up more at the same pull request.

（更多）递归类型别名

🌐 (More) Recursive Type Aliases

游乐场

类型别名在如何“递归”引用方面一直存在限制。原因是对类型别名的任何使用都需要能够将其自身替换为它所别名的类型。在某些情况下，这是不可能的，因此编译器会拒绝某些递归别名，例如以下情况：

🌐 Type aliases have always had a limitation in how they could be “recursively” referenced. The reason is that any use of a type alias needs to be able to substitute itself with whatever it aliases. In some cases, that’s not possible, so the compiler rejects certain recursive aliases like the following:

ts
type Foo = Foo;

这是一个合理的限制，因为任何对 Foo 的使用都需要被替换为 Foo，而 Foo 又需要被替换为 Foo，Foo 又需要被替换为 Foo……嗯，希望你能明白我的意思！ 最终，没有一种类型可以合理地替代 Foo。

🌐 This is a reasonable restriction because any use of Foo would need to be replaced with Foo which would need to be replaced with Foo which would need to be replaced with Foo which… well, hopefully you get the idea! In the end, there isn’t a type that makes sense in place of Foo.

这与其他语言处理类型别名的方式相当一致，但它确实会引出一些用户使用该功能时稍显意外的情景。例如，在 TypeScript 3.6 及以前版本中，以下代码会导致错误。

🌐 This is fairly consistent with how other languages treat type aliases, but it does give rise to some slightly surprising scenarios for how users leverage the feature. For example, in TypeScript 3.6 and prior, the following causes an error.

ts
type ValueOrArray<T> = T | Array<ValueOrArray<T>>;
//   ~~~~~~~~~~~~
// error: Type alias 'ValueOrArray' circularly references itself.

这很奇怪，因为从技术上讲，用户可以通过引入接口来编写实际上相同的代码，这本身并没有错。

🌐 This is strange because there is technically nothing wrong with any use users could always write what was effectively the same code by introducing an interface.

ts
type ValueOrArray<T> = T | ArrayOfValueOrArray<T>;
interface ArrayOfValueOrArray<T> extends Array<ValueOrArray<T>> {}

由于接口（以及其他对象类型）引入了一层间接层，并且其完整结构无需急切构建，因此 TypeScript 可以轻松处理这种结构。

🌐 Because interfaces (and other object types) introduce a level of indirection and their full structure doesn’t need to be eagerly built out, TypeScript has no problem working with this structure.

但引入接口的变通方法对用户来说并不直观。原则上，直接使用 Array 的原始 ValueOrArray 版本实际上没有任何问题。如果编译器稍微“懒惰”一点，仅在必要时才计算 Array 的类型参数，那么 TypeScript 就可以正确表达这些内容。

🌐 But workaround of introducing the interface wasn’t intuitive for users. And in principle there really wasn’t anything wrong with the original version of ValueOrArray that used Array directly. If the compiler was a little bit “lazier” and only calculated the type arguments to Array when necessary, then TypeScript could express these correctly.

这正是 TypeScript 3.7 引入的功能。在类型别名的“顶层”，TypeScript 会延迟解析类型参数，以允许这些模式。

🌐 That’s exactly what TypeScript 3.7 introduces. At the “top level” of a type alias, TypeScript will defer resolving type arguments to permit these patterns.

这意味着像下面这样的代码试图表示 JSON……

🌐 This means that code like the following that was trying to represent JSON…

ts
type Json = string | number | boolean | null | JsonObject | JsonArray;
interface JsonObject {
  [property: string]: Json;
}
interface JsonArray extends Array<Json> {}

最终可以在没有辅助接口的情况下重写。

🌐 can finally be rewritten without helper interfaces.

ts
type Json =
  | string
  | number
  | boolean
  | null
  | { [property: string]: Json }
  | Json[];

这种新的放宽也允许我们在元组中递归引用类型别名。之前会报错的以下代码现在是有效的 TypeScript 代码。

🌐 This new relaxation also lets us recursively reference type aliases in tuples as well. The following code which used to error is now valid TypeScript code.

ts
type VirtualNode = string | [string, { [key: string]: any }, ...VirtualNode[]];
const myNode: VirtualNode = [
  "div",
  { id: "parent" },
  ["div", { id: "first-child" }, "I'm the first child"],
  ["div", { id: "second-child" }, "I'm the second child"],
];

欲了解更多信息，你可以阅读原始拉取请求。

🌐 For more information, you can read up on the original pull request.

--declaration 和 --allowJs

🌐 --declaration and --allowJs

TypeScript 中的 declaration 标志允许我们从 TypeScript 源文件（即 .ts 和 .tsx 文件）生成 .d.ts 文件（声明文件）。这些 .d.ts 文件之所以重要，有几个原因。

🌐 The declaration flag in TypeScript allows us to generate .d.ts files (declaration files) from TypeScript source files (i.e. .ts and .tsx files). These .d.ts files are important for a couple of reasons.

首先，它们很重要，因为它们允许 TypeScript 在不重新检查原始源代码的情况下，对其他项目进行类型检查。它们也很重要，因为它们允许 TypeScript 与那些在设计时没有考虑 TypeScript 的现有 JavaScript 库进行互操作。最后，一个经常被低估的好处是：当使用由 TypeScript 提供支持的编辑器时，TypeScript 和 JavaScript 用户都可以从这些文件中受益，比如获得更好的自动补全功能。

🌐 First of all, they’re important because they allow TypeScript to type-check against other projects without re-checking the original source code. They’re also important because they allow TypeScript to interoperate with existing JavaScript libraries that weren’t built with TypeScript in mind. Finally, a benefit that is often underappreciated: both TypeScript and JavaScript users can benefit from these files when using editors powered by TypeScript to get things like better auto-completion.

不幸的是，declaration 不能与允许混合 TypeScript 和 JavaScript 输入文件的 allowJs 标志一起使用。这是一个令人沮丧的限制，因为这意味着用户在迁移代码库时，即使使用了 JSDoc 注释，也无法使用 declaration 标志。TypeScript 3.7 改变了这一点，现在允许这两个选项一起使用！

🌐 Unfortunately, declaration didn’t work with the allowJs flag which allows mixing TypeScript and JavaScript input files. This was a frustrating limitation because it meant users couldn’t use the declaration flag when migrating codebases, even if they were JSDoc-annotated. TypeScript 3.7 changes that, and allows the two options to be used together!

这个功能最有影响力的结果可能有些微妙：在 TypeScript 3.7 中，用户可以用带有 JSDoc 注释的 JavaScript 编写库，同时支持 TypeScript 用户。

🌐 The most impactful outcome of this feature might a bit subtle: with TypeScript 3.7, users can write libraries in JSDoc annotated JavaScript and support TypeScript users.

其工作原理是，当使用 allowJs 时，TypeScript 会尽最大努力分析以理解常见的 JavaScript 模式；然而，有些模式在 JavaScript 中的表达方式不一定看起来像它们在 TypeScript 中的对应形式。 当 declaration 输出启用时，TypeScript 会找出将 JSDoc 注释和 CommonJS 导出转换为输出 .d.ts 文件中有效类型声明等内容的最佳方式。

🌐 The way that this works is that when using allowJs, TypeScript has some best-effort analyses to understand common JavaScript patterns; however, the way that some patterns are expressed in JavaScript don’t necessarily look like their equivalents in TypeScript. When declaration emit is turned on, TypeScript figures out the best way to transform JSDoc comments and CommonJS exports into valid type declarations and the like in the output .d.ts files.

例如，以下代码片段

🌐 As an example, the following code snippet

js
const assert = require("assert");
module.exports.blurImage = blurImage;
/**
 * Produces a blurred image from an input buffer.
 *
 * @param input {Uint8Array}
 * @param width {number}
 * @param height {number}
 */
function blurImage(input, width, height) {
  const numPixels = width * height * 4;
  assert(input.length === numPixels);
  const result = new Uint8Array(numPixels);
  // TODO
  return result;
}

将生成一个类似 .d.ts 的文件

🌐 Will produce a .d.ts file like

ts
/**
 * Produces a blurred image from an input buffer.
 *
 * @param input {Uint8Array}
 * @param width {number}
 * @param height {number}
 */
export function blurImage(
  input: Uint8Array,
  width: number,
  height: number
): Uint8Array;

这也可以超越基本功能，使用 @param 标签，例如以下示例：

🌐 This can go beyond basic functions with @param tags too, where the following example:

js
/**
 * @callback Job
 * @returns {void}
 */
/** Queues work */
export class Worker {
  constructor(maxDepth = 10) {
    this.started = false;
    this.depthLimit = maxDepth;
    /**
     * NOTE: queued jobs may add more items to queue
     * @type {Job[]}
     */
    this.queue = [];
  }
  /**
   * Adds a work item to the queue
   * @param {Job} work
   */
  push(work) {
    if (this.queue.length + 1 > this.depthLimit) throw new Error("Queue full!");
    this.queue.push(work);
  }
  /**
   * Starts the queue if it has not yet started
   */
  start() {
    if (this.started) return false;
    this.started = true;
    while (this.queue.length) {
      /** @type {Job} */ (this.queue.shift())();
    }
    return true;
  }
}

将被转换为以下 .d.ts 文件：

🌐 will be transformed into the following .d.ts file:

ts
/**
 * @callback Job
 * @returns {void}
 */
/** Queues work */
export class Worker {
  constructor(maxDepth?: number);
  started: boolean;
  depthLimit: number;
  /**
   * NOTE: queued jobs may add more items to queue
   * @type {Job[]}
   */
  queue: Job[];
  /**
   * Adds a work item to the queue
   * @param {Job} work
   */
  push(work: Job): void;
  /**
   * Starts the queue if it has not yet started
   */
  start(): boolean;
}
export type Job = () => void;

请注意，当同时使用这些标志时，TypeScript 并不一定需要将 .js 文件降级。如果你只是想让 TypeScript 创建 .d.ts 文件，可以使用 emitDeclarationOnly 编译器选项。

🌐 Note that when using these flags together, TypeScript doesn’t necessarily have to downlevel .js files. If you simply want TypeScript to create .d.ts files, you can use the emitDeclarationOnly compiler option.

欲了解更多详情，你可以查看原始拉取请求。

🌐 For more details, you can check out the original pull request.

useDefineForClassFields 标志和 declare 属性修饰符

🌐 The useDefineForClassFields Flag and The declare Property Modifier

当 TypeScript 实现公共类字段时，我们尽力假设以下代码：

🌐 Back when TypeScript implemented public class fields, we assumed to the best of our abilities that the following code

ts
class C {
  foo = 100;
  bar: string;
}

相当于在构造函数体内进行类似的赋值。

🌐 would be equivalent to a similar assignment within a constructor body.

ts
class C {
  constructor() {
    this.foo = 100;
  }
}

不幸的是，尽管这一提案在早期似乎朝着这个方向发展，但公共类字段很可能会以不同的方式被标准化。相反，原始代码示例可能需要去糖处理，接近下面的形式：

🌐 Unfortunately, while this seemed to be the direction that the proposal moved towards in its earlier days, there is an extremely strong chance that public class fields will be standardized differently. Instead, the original code sample might need to de-sugar to something closer to the following:

ts
class C {
  constructor() {
    Object.defineProperty(this, "foo", {
      enumerable: true,
      configurable: true,
      writable: true,
      value: 100,
    });
    Object.defineProperty(this, "bar", {
      enumerable: true,
      configurable: true,
      writable: true,
      value: void 0,
    });
  }
}

虽然 TypeScript 3.7 默认不会更改任何现有的输出，但我们一直在逐步推出更改，以帮助用户降低未来可能出现的问题。 我们提供了一个名为 useDefineForClassFields 的新标志，用于启用这种带有一些新检查逻辑的输出模式。

🌐 While TypeScript 3.7 isn’t changing any existing emit by default, we’ve been rolling out changes incrementally to help users mitigate potential future breakage. We’ve provided a new flag called useDefineForClassFields to enable this emit mode with some new checking logic.

最大的两个变化如下：

🌐 The two biggest changes are the following:

  • 声明使用 Object.defineProperty 初始化。
  • 声明总是被初始化为 undefined，即使它们没有初始化器。

这可能会对使用继承的现有代码造成相当大的影响。首先，基类中的 set 访问器将不会被触发——它们会被完全覆盖。

🌐 This can cause quite a bit of fallout for existing code that use inheritance. First of all, set accessors from base classes won’t get triggered - they’ll be completely overwritten.

ts
class Base {
  set data(value: string) {
    console.log("data changed to " + value);
  }
}
class Derived extends Base {
  // No longer triggers a 'console.log'
  // when using 'useDefineForClassFields'.
  data = 10;
}

其次，使用类字段来特化基类的属性也行不通。

🌐 Secondly, using class fields to specialize properties from base classes also won’t work.

ts
interface Animal {
  animalStuff: any;
}
interface Dog extends Animal {
  dogStuff: any;
}
class AnimalHouse {
  resident: Animal;
  constructor(animal: Animal) {
    this.resident = animal;
  }
}
class DogHouse extends AnimalHouse {
  // Initializes 'resident' to 'undefined'
  // after the call to 'super()' when
  // using 'useDefineForClassFields'!
  resident: Dog;
  constructor(dog: Dog) {
    super(dog);
  }
}

归根结底，混合使用属性和访问器会导致问题，重新声明没有初始化器的属性也会导致问题。

🌐 What these two boil down to is that mixing properties with accessors is going to cause issues, and so will re-declaring properties with no initializers.

为了检测访问器相关的问题，TypeScript 3.7 现在将在 .d.ts 文件中发出 get/set 访问器，以便 TypeScript 可以检查被重写的访问器。

🌐 To detect the issue around accessors, TypeScript 3.7 will now emit get/set accessors in .d.ts files so that in TypeScript can check for overridden accessors.

受类字段更改影响的代码可以通过将字段初始化器转换为构造函数主体中的赋值来解决这个问题。

🌐 Code that’s impacted by the class fields change can get around the issue by converting field initializers to assignments in constructor bodies.

ts
class Base {
  set data(value: string) {
    console.log("data changed to " + value);
  }
}
class Derived extends Base {
  constructor() {
    this.data = 10;
  }
}

为帮助缓解第二个问题，你可以添加一个显式初始化器，或者添加一个 declare 修饰符来表示某个属性不应生成代码。

🌐 To help mitigate the second issue, you can either add an explicit initializer or add a declare modifier to indicate that a property should have no emit.

ts
interface Animal {
  animalStuff: any;
}
interface Dog extends Animal {
  dogStuff: any;
}
class AnimalHouse {
  resident: Animal;
  constructor(animal: Animal) {
    this.resident = animal;
  }
}
class DogHouse extends AnimalHouse {
  declare resident: Dog;
  //  ^^^^^^^
  // 'resident' now has a 'declare' modifier,
  // and won't produce any output code.
  constructor(dog: Dog) {
    super(dog);
  }
}

目前 useDefineForClassFields 仅在目标为 ES5 及以上时可用，因为 Object.defineProperty 在 ES3 中不存在。要实现类似的问题检查，你可以创建一个单独的项目，目标为 ES5，并使用 noEmit 来避免完全构建。

🌐 Currently useDefineForClassFields is only available when targeting ES5 and upwards, since Object.defineProperty doesn’t exist in ES3. To achieve similar checking for issues, you can create a separate project that targets ES5 and uses noEmit to avoid a full build.

欲了解更多信息，你可以查看这些更改的原始拉取请求。

🌐 For more information, you can take a look at the original pull request for these changes.

我们强烈鼓励用户尝试 useDefineForClassFields 标志，并在我们的问题跟踪器或下方评论中反馈。这包括关于采用该标志的难易程度的反馈，以便我们了解如何使迁移更容易。

🌐 We strongly encourage users to try the useDefineForClassFields flag and report back on our issue tracker or in the comments below. This includes feedback on difficulty of adopting the flag so we can understand how we can make migration easier.

使用项目引用进行免编译编辑

🌐 Build-Free Editing with Project References

TypeScript 的项目引用为我们提供了一种简单的方法来拆分代码库，从而加快编译速度。不幸的是，编辑一个依赖尚未构建（或输出已过期）的项目时，编辑体验会不太顺畅。

🌐 TypeScript’s project references provide us with an easy way to break codebases up to give us faster compiles. Unfortunately, editing a project whose dependencies hadn’t been built (or whose output was out of date) meant that the editing experience wouldn’t work well.

在 TypeScript 3.7 中，当打开一个带有依赖的项目时，TypeScript 将自动改为使用源 .ts/.tsx 文件。 这意味着使用项目引用的项目现在将获得改进的编辑体验，其中语义操作是最新的并且“可以正常工作”。 你可以使用编译器选项 disableSourceOfProjectReferenceRedirect 禁用此行为，这在处理非常大的项目时可能是适用的，因为此更改可能会影响编辑性能。

🌐 In TypeScript 3.7, when opening a project with dependencies, TypeScript will automatically use the source .ts/.tsx files instead. This means projects using project references will now see an improved editing experience where semantic operations are up-to-date and “just work”. You can disable this behavior with the compiler option disableSourceOfProjectReferenceRedirect which may be appropriate when working in very large projects where this change may impact editing performance.

你可以通过阅读它的拉取请求了解更多关于此更改的信息。

🌐 You can read up more about this change by reading up on its pull request.

未调用函数检查

🌐 Uncalled Function Checks

一个常见且危险的错误是忘记调用函数，尤其是在函数没有参数或命名方式暗示它可能是一个属性而不是函数的情况下。

🌐 A common and dangerous error is to forget to invoke a function, especially if the function has zero arguments or is named in a way that implies it might be a property rather than a function.

ts
interface User {
  isAdministrator(): boolean;
  notify(): void;
  doNotDisturb?(): boolean;
}
// later...
// Broken code, do not use!
function doAdminThing(user: User) {
  // oops!
  if (user.isAdministrator) {
    sudo();
    editTheConfiguration();
  } else {
    throw new AccessDeniedError("User is not an admin");
  }
}

在这里，我们忘记调用 isAdministrator，并且代码错误地允许非管理员用户编辑配置！

🌐 Here, we forgot to call isAdministrator, and the code incorrectly allows non-administrator users to edit the configuration!

在 TypeScript 3.7 中，这被识别为可能的错误：

🌐 In TypeScript 3.7, this is identified as a likely error:

ts
function doAdminThing(user: User) {
    if (user.isAdministrator) {
    //  ~~~~~~~~~~~~~~~~~~~~
    // error! This condition will always return true since the function is always defined.
    //        Did you mean to call it instead?

此检查属于重大更改，但正因如此，这些检查非常谨慎。 此错误仅在 if 条件下发出，并且不会在可选属性上发出，如果 strictNullChecks 关闭，或者函数随后在 if 的主体中被调用时，也不会发出此错误：

🌐 This check is a breaking change, but for that reason the checks are very conservative. This error is only issued in if conditions, and it is not issued on optional properties, if strictNullChecks is off, or if the function is later called within the body of the if:

ts
interface User {
  isAdministrator(): boolean;
  notify(): void;
  doNotDisturb?(): boolean;
}
function issueNotification(user: User) {
  if (user.doNotDisturb) {
    // OK, property is optional
  }
  if (user.notify) {
    // OK, called the function
    user.notify();
  }
}

如果你打算在不调用函数的情况下测试它，你可以修改它的定义以包含 undefined/null，或者使用 !! 来写类似 if (!!user.isAdministrator) 的内容，以表示类型转换是故意的。

🌐 If you intended to test the function without calling it, you can correct the definition of it to include undefined/null, or use !! to write something like if (!!user.isAdministrator) to indicate that the coercion is intentional.

我们要非常感谢 GitHub 用户 @jwbay，他主动创建了一个 概念验证 并不断迭代，最终为我们提供了 当前版本。

🌐 We owe a big thanks to GitHub user @jwbay who took the initiative to create a proof-of-concept and iterated to provide us with the current version.

// @ts-nocheck 在 TypeScript 文件中

🌐 // @ts-nocheck in TypeScript Files

TypeScript 3.7 允许我们在 TypeScript 文件顶部添加 // @ts-nocheck 注释以禁用语义检查。历史上，这种注释仅在存在 checkJs 的情况下在 JavaScript 源文件中有效，但我们已经将其支持扩展到 TypeScript 文件，以便为所有用户更轻松地进行迁移。

🌐 TypeScript 3.7 allows us to add // @ts-nocheck comments to the top of TypeScript files to disable semantic checks. Historically this comment was only respected in JavaScript source files in the presence of checkJs, but we’ve expanded support to TypeScript files to make migrations easier for all users.

分号格式化程序选项

🌐 Semicolon Formatter Option

TypeScript 内置的格式化工具现在支持在由于 JavaScript 自动分号插入（ASI）规则而分号可选的位置插入或移除分号。该设置现在可在 Visual Studio Code Insiders 中使用，并将在 Visual Studio 16.4 预览版 2 的工具选项菜单中提供。

🌐 TypeScript’s built-in formatter now supports semicolon insertion and removal at locations where a trailing semicolon is optional due to JavaScript’s automatic semicolon insertion (ASI) rules. The setting is available now in Visual Studio Code Insiders, and will be available in Visual Studio 16.4 Preview 2 in the Tools Options menu.

New semicolon formatter option in VS Code

选择“insert”或“remove”的值也会影响 TypeScript 服务提供的自动导入、提取类型和其他生成代码的格式。将该设置保持为默认值“ignore”会使生成的代码与当前文件中检测到的分号偏好一致。

🌐 Choosing a value of “insert” or “remove” also affects the format of auto-imports, extracted types, and other generated code provided by TypeScript services. Leaving the setting on its default value of “ignore” makes generated code match the semicolon preference detected in the current file.

3.7 重大变更

🌐 3.7 Breaking Changes

DOM 变更

🌐 DOM Changes

lib.dom.d.ts 中的类型已更新。 这些更改主要是与可空性相关的正确性更改，但其影响最终将取决于你的代码库。

类字段缓解措施

🌐 Class Field Mitigations

如上所述，TypeScript 3.7 在 .d.ts 文件中会生成 get/set 访问器，这可能会对使用较旧版本 TypeScript（如 3.5 及以前版本）的用户造成破坏性更改。TypeScript 3.6 用户不会受到影响，因为该版本已经为此功能进行了前瞻性兼容。

虽然本身不是故障，但选择启用 useDefineForClassFields 标志可能会在以下情况下导致故障：

🌐 While not a breakage per se, opting in to the useDefineForClassFields flag can cause breakage when:

  • 使用属性声明覆盖派生类中的访问器
  • 重新声明没有初始化器的属性声明

要了解全部影响，请阅读上文关于useDefineForClassFields标志的部分。

🌐 To understand the full impact, read the section above on the useDefineForClassFields flag.

函数真值检查

🌐 Function Truthy Checks

如上所述，当函数在 if 语句条件中看似未被调用时，TypeScript 会报错。 当在 if 条件中检查函数类型时，会发出错误，除非以下任一情况适用：

🌐 As mentioned above, TypeScript now errors when functions appear to be uncalled within if statement conditions. An error is issued when a function type is checked in if conditions unless any of the following apply:

  • 被检查的值来自可选属性。
  • strictNullChecks 已被禁用
  • 该函数随后在 if 的主体内被调用

本地和导入类型声明现在冲突

🌐 Local and Imported Type Declarations Now Conflict

由于一个 bug，TypeScript 之前允许使用以下构造：

🌐 Due to a bug, the following construct was previously allowed in TypeScript:

ts
// ./someOtherModule.ts
interface SomeType {
  y: string;
}
// ./myModule.ts
import { SomeType } from "./someOtherModule";
export interface SomeType {
  x: number;
}
function fn(arg: SomeType) {
  console.log(arg.x); // Error! 'x' doesn't exist on 'SomeType'
}

这里，SomeType 似乎既源自 import 声明，又源自本地 interface 声明。或许令人惊讶的是，在模块内部，SomeType 专门指向 import 的定义，而本地声明 SomeType 只有在从另一个文件导入时才能使用。这非常令人困惑，我们对实际中极少数类似代码的案例的审查显示，开发者通常认为发生了不同的事情。

🌐 Here, SomeType appears to originate in both the import declaration and the local interface declaration. Perhaps surprisingly, inside the module, SomeType refers exclusively to the imported definition, and the local declaration SomeType is only usable when imported from another file. This is very confusing and our review of the very small number of cases of code like this in the wild showed that developers usually thought something different was happening.

在 TypeScript 3.7 中，这现在被正确地识别为重复标识符错误。 正确的修复方法取决于作者的原始意图，应根据具体情况处理。 通常，命名冲突是无意的，最好的解决方法是重命名导入的类型。 如果目的是扩展导入的类型，则应该编写合适的模块扩展。

🌐 In TypeScript 3.7, this is now correctly identified as a duplicate identifier error. The correct fix depends on the original intent of the author and should be addressed on a case-by-case basis. Usually, the naming conflict is unintentional and the best fix is to rename the imported type. If the intent was to augment the imported type, a proper module augmentation should be written instead.

3.7 API 变更

🌐 3.7 API Changes

为了启用上述描述的递归类型别名模式，TypeReference 接口中的 typeArguments 属性已被移除。用户应改为在 TypeChecker 实例上使用 getTypeArguments 函数。

🌐 To enable the recursive type alias patterns described above, the typeArguments property has been removed from the TypeReference interface. Users should instead use the getTypeArguments function on TypeChecker instances.