TypeScript 备忘清单

TypeScript 是具有类型语法的 JavaScript。Interface 是为了匹配它们的运行时行为而构建的。

• JavaScript 备忘清单 (jaywcjlove.github.io)
• TypeScript 官网 (typescriptlang.org)

any, void,
boolean, string, number,
undefined, null,
unknown, never,
bigint, symbol

Date, Error,
Array, Map, Set,
Regexp, Promise

interface Expect {
  (matcher: boolean): string
  (matcher: string): boolean;
}

一个可调用 Interface 可以对不同的参数集有多个定义。

interface Syncable {
  sync(): void
}
class Account implements Syncable { ... }

您可以通过实现确保类 class 符合 Interface。

对象可以有自定义的 getter 或 setter。

interface Ruler {
  get size(): number
  set size(value: number | string);
}

用法

const r: Ruler = ...
r.size = 12
r.size = "36"

interface APICall {
  data: Response
}

interface APICall {
  error?: Error
}

Interface 被合并，多个声明将向类型定义添加新字段。

type SanitizedInput = string;
type MissingNo = 404;

主要用于文档

type Location = {
  x: number;
  y: number;
};

type Size = "small" | "medium" | "large"

描述许多选项中的一个类型，例如已知字符串的列表。

type Location = { x: number }
              & { y: number }
// { x: number, y: number }

一种合并/扩展类型的方法

const data = { ... }
type Data = typeof data

通过 typeof 运算符重用来自现有 JavaScript 运行时值的类型。

const createFixtures = () => { ... }
type Fixtures = ReturnType<typeof createFixtures>
function test(fixture: Fixtures) {}

将函数的返回值重新用作类型。

const data: import("./data").data

这些功能非常适合构建库、描述现有的 JavaScript 代码，您可能会发现在大多数 TypeScript 应用程序中很少使用它们。

type Artist = {
  name: string, bio: string
}

type Subscriber<Type> = {
  [Property in keyof Type]: 
      (newValue: Type[Property]) => void
}
type ArtistSub = Subscriber<Artist>
// { name: (nv: string) => 
//    void, bio: (nv: string) => void }

类似于类型系统的映射语句，允许输入类型更改新类型的结构。

CFA 几乎总是采用联合，并根据代码中的逻辑减少联合内的类型数量。

大多数时候 CFA 在自然 JavaScript 布尔逻辑中工作，但是有一些方法可以定义您自己的函数，这些函数会影响 TypeScript 如何缩小类型。

const input = getUserInput()
input // string | number
const inputLength =
  (typeof input === "string" && input.length)
  || input
   // input: string

在进行布尔运算时，缩窄也发生在与代码相同的行上

interface A {
  x: number;
}
interface B {
  y: string;
}

function doStuff(q: A | B) {
  if ('x' in q) {
    // q: A
  } else {
    // q: B
  }
}

操作符可以安全的检查一个对象上是否存在一个属性，它通常也被作为类型保护使用

声明一个可以在你的类方法中改变的类型。

class Box<Type> {
  contents: Type
  constructor(value: Type) {
    this.contents = value;
  }
}
const stringBox = new Box("a package")

这些功能是 TypeScript 特定的语言扩展，可能永远无法使用当前语法进入 JavaScript。

class Location {
  constructor(
    public x: number,
    public y: number
  ) {}
}
const loc = new Location(20, 40);

loc.x // 20
loc.y // 40

TypeScript 特定于类的扩展，可自动将实例字段设置为输入参数。

abstract class Animal {
  abstract getName(): string;
  printName() {
   console.log("Hello, " + this.getName());
  }
}
class Dog extends Animal {
  getName(): { ... }
}

一个类可以被声明为不可实现，但可以在类型系统中被子类化。 class 成员也可以。

import {
  Syncable, triggersSync, preferCache,
  required
} from "mylib"

@Syncable
class User {
  @triggersSync()
  save() { ... }
  @preferCache(false)
  get displayName() { ... }
  update(@required info: Partial<User>) {
    //...
  }
}

您可以在类、类方法、访问器、属性和方法参数上使用装饰器。

class MyClass {
  // 最好将索引数据存储在另一个地方
  // 而不是类实例本身。
  [s: string]:
    boolean | ((s: string) => boolean);

  check(s: string) {
    return this[s] as boolean;
  }
}

类可以声明索引签名，与其他对象类型的索引签名相同。

export const Wrapper = forwardRef(
  <T extends object>
(
  props: RootNodeProps<T>,
  ref: React.LegacyRef<HTMLDivElement>
) => {
  return (
    <div ref={ref}></div>
  );
}

type A = Awaited<Promise<string>>;
// type A = string

type B = Awaited<Promise<Promise<number>>>;
// type B = number

type C = Awaited<boolean|Promise<number>>;
// type C = number | boolean

这种类型旨在模拟异步函数中的 await 或 Promises 上的 .then() 方法等操作 - 特别是它们递归解包 Promises 的方式。

interface Props {
  a?: number;
  b?: string;
}

const obj: Props = { a: 5 }; 
const obj2: Required<Props> = { a: 5 };
// ❌ 类型“{ a: number;”中缺少属性“b” }' 
// 但在 'Required<Props>' 类型中是必需的。

使 Type 中的所有属性成为必需

interface Todo {
  title: string;
}
const todo: Readonly<Todo> = {
  title: "Delete inactive users",
};
todo.title = "Hello";
// ❌ 无法分配给“title”，因为它是只读属性。

function freeze<Type>(obj: Type)
            : Readonly<Type>;

将 Type 中的所有属性设为只读

interface Todo {
  title: string;
  description: string;
}
function updateTodo(
  todo: Todo,
  fieldsToUpdate: Partial<Todo>
) {
  return { ...todo, ...fieldsToUpdate };
}
const todo1 = {
  title: "organize desk",
  description: "clear clutter",
};
const todo2 = updateTodo(todo1, {
  description: "throw out trash",
});

将 Type 中的所有属性设为可选

interface CatInfo {
  age: number;
  breed: string;
}

type CatName = "miffy" | "boris";
const cats: Record<CatName, CatInfo> = {
  miffy: {age:10, breed: "Persian" },
  boris: {age:5, breed: "Maine Coon" },
};

cats.boris; 
// 👉 const cats: Record<CatName, CatInfo>

构造一个具有一组 Keys 类型的属性 Type 的类型

interface Todo {
  name: string;
  description: string;
  completed: boolean;
}
type TodoPreview = Pick<
  Todo, "name" | "load"
>;
const todo: TodoPreview = {
  name: "Clean room",
  load: false,
};

todo;
 // 👉 const todo: TodoPreview

从 Type 中选择一组其键在并集 Keys 中的属性

type T0 = Exclude<"a" | "b" | "c", "a">;
// 👉 type T0 = "b" | "c"

type T1 = Exclude<"a"|"b"|"c", "a" | "b">;
// 👉 type T1 = "c"

type T2 = Exclude<string | number |
    (() => void), Function>;
// 👉 type T2 = string | number

从 UnionType 中排除那些可分配给 ExcludedMembers 的类型

type T0 = Extract<
  "a" | "b" | "c", "a" | "f"
>;
// type T0 = "a"
type T1 = Extract<
  string | number | (() => void),
  Function
>;
// type T1 = () => void

通过从 Type 中提取所有可分配给 Union 的联合成员来构造一个类型。

type T0 = NonNullable<
  string | number | undefined
>;
// type T0 = string | number

type T1 = NonNullable<
  string[] | null | undefined
>;
// type T1 = string[]

通过从 Type 中排除 null 和 undefined 来构造一个类型。

interface Todo {
  name: string;
  completed: boolean;
  createdAt: number;
}
 
type TodoPreview = Omit<Todo, "name">;

const todo: TodoPreview = {
  completed: false,
  createdAt: 1615544252770,
};
 
todo;
 // 👉 const todo: TodoPreview

构造一个具有 Type 属性的类型，但类型 Keys 中的属性除外。

declare function f1(
  arg: { a: number; b: string }
): void;

type T0 = Parameters<() => string>;
// type T0 = []
type T1 = Parameters<(s: string) => void>;
// type T1 = [s: string]
type T2 = Parameters<<T>(arg: T) => T>;
// type T2 = [arg: unknown]
type T3 = Parameters<typeof f1>;
// type T3 = [arg: {
//     a: number;
//     b: string;
// }]
type T4 = Parameters<any>;
// type T4 = unknown[]
type T5 = Parameters<never>;
// type T5 = never

从函数类型 Type 的参数中使用的类型构造元组类型。

type T0 = ConstructorParameters<
  ErrorConstructor
>;
// type T0 = [message?: string]
type T1 = ConstructorParameters<
  FunctionConstructor
>;
// type T1 = string[]
type T2 = ConstructorParameters<
  RegExpConstructor
>;
// type T2 = [
//    pattern: string | RegExp,
//    flags?: string
// ]
type T3 = ConstructorParameters<any>;
// type T3 = unknown[]

从构造函数类型的类型构造元组或数组类型。它产生一个包含所有参数类型的元组类型（如果 Type 不是函数，则类型 never ）。

declare function f1(): {
  a: number; b: string
};

type T0 = ReturnType<() => string>;
// type T0 = string

type T1 = ReturnType<(s: string) => void>;
// type T1 = void

type T2 = ReturnType<<T>() => T>;
// type T2 = unknown

type T3 = ReturnType<<
  T extends U, U extends number[]
>() => T>;
// type T3 = number[]

type T4 = ReturnType<typeof f1>;
// type T4 = {
//     a: number;
//     b: string;
// }

type T5 = ReturnType<any>;
// type T5 = any

type T6 = ReturnType<never>;
// type T6 = never

构造一个由函数 Type 的返回类型组成的类型。

type ObjectDescriptor<D, M> = {
  data?: D;
  // 方法中“this”的类型是 D & M
  methods?: M & ThisType<D & M>;
};
 
function makeObject<D, M>(
  desc: ObjectDescriptor<D, M>
): D & M {
  let data: object = desc.data || {};
  let methods: object = desc.methods || {};
  return { ...data, ...methods } as D & M;
}
 
let obj = makeObject({
  data: { x: 0, y: 0 },
  methods: {
    moveBy(dx: number, dy: number) {
      this.x += dx; // Strongly typed this
      this.y += dy; // Strongly typed this
    },
  },
});
 
obj.x = 10;
obj.y = 20;
obj.moveBy(5, 5);

此实用程序不返回转换后的类型。 相反，它用作上下文 this 类型的标记。 请注意，必须启用 noImplicitThis 标志才能使用此实用程序。

class C {
  x = 0;
  y = 0;
}
type T0 = InstanceType<typeof C>;
// type T0 = C
type T1 = InstanceType<any>;
// type T1 = any
type T2 = InstanceType<never>;
// type T2 = never

构造一个由 Type 中构造函数的实例类型组成的类型。

function toHex(this: Number) {
  return this.toString(16);
}
 
function numberToString(
  n: ThisParameterType<typeof toHex>
) {
  return toHex.apply(n);
}

提取函数类型的 this 参数的类型，如果函数类型没有 this 参数，则为未知。

function toHex(this: Number) {
  return this.toString(16);
}
const fiveToHex
  : OmitThisParameter<typeof toHex>
  = toHex.bind(5);

console.log(fiveToHex());

从 Type 中移除 this 参数。 如果 Type 没有显式声明此参数，则结果只是 Type。 否则，从 Type 创建一个不带此参数的新函数类型。 泛型被删除，只有最后一个重载签名被传播到新的函数类型中。

JSX 规范是对 ECMAScript 的类似 XML 的语法扩展。

• 使用 .tsx 扩展名命名您的文件
• 启用 jsx 选项
• 不允许在 .tsx 文件中使用尖括号类型断言。
• JSX 规范

const foo = <foo>bar;
// ❌ 不允许在 .tsx 👆 文件中使用尖括号类型断言。

const foo = bar as foo;

as 运算符在 .ts 和 .tsx 文件中都可用，并且在行为上与尖括号类型断言样式相同。

import MyComponent from "./myComponent";

<MyComponent />; // ok
<SomeOtherComponent />; // ❌ error

基于值的元素只是由范围内的标识符查找。

declare namespace JSX {
  interface IntrinsicElements {
    foo: any;
  }
}
<foo />; // ok
<bar />; // error

<bar /> 没有在 JSX.IntrinsicElements 上指定。

declare namespace JSX {
  interface IntrinsicElements {
    [elemName: string]: any;
  }
}

interface CeProps {
  children: JSX.Element[] | JSX.Element;
}
 
interface HomeProps extends CeProps {
  home: JSX.Element;
}
 
interface SideProps extends CeProps {
  side: JSX.Element | string;
}
 
function Dog(prop:HomeProps): JSX.Element;
function Dog(prop:SideProps): JSX.Element;
function Dog(prop:CeProps): JSX.Element {
  // ...
}

type RowProps = {
  element: React.ElementType<{
    className?: string;
  }>;
}
const Row = (props: RowProps) => {
  return (
    <props.element className="h-8 w-8" />
  );
};
 
<Row element={"div"} />;
<Row element={UserIcon} />;

interface Point { x: number; y: number; }
 
// type keys = "x" | "y"
type keys = keyof Point;

type Arrayish = {
    [n: number]: unknown;
};
type A = keyof Arrayish; 
// type A = number

interface NumberOrString {
  [index: string]: string | number;
  length: number;
  name: string;
}

const point = [3, 4] as const
// type 'readonly [3, 4]'

type Point = { x: number; y: number; }
type Data = Point[];
// Data 是个数组，提取里面的元素类型
type PointDetail = Data[number];
// type PointDetail = { x: number; y: number; }

declare global {
  interface String {
    fancyFormat(opts: FancyOption): string;
  }
}
export interface FancyOption {
  fancinessLevel: number;
}

const MyArray = [
  { name: "Alice", age: 15 },
  { name: "Bob", age: 23 },
  { name: "Eve", age: 38 },
];
 
type Person = typeof MyArray[number];
// type Person = {
//   name: string;
//   age: number;
// }

type Age = typeof MyArray[number]["age"];
// type Age = number

type Age2 = Person["age"];
// type Age2 = number

const a = <T extends string>(t: T) => t;
const b = <T extends number>(t: T) => t;
const c = <T extends boolean>(t: T) => t;
const d = a("a");  // const d: 'a'
const e = b(1);    // const d: 1
const f = c(true); // const d: true

// 这里t的类型用了一个展开运算
const g = 
  <T extends string[]>(t: [...T]) => t;
// 类型变成["111", "222"]了
const h = g(["111", "222"]);

例如，当您想使用扩展另一个库的 JavaScript 代码时

import { greeter } from "super-greeter";
// 普通欢迎 API
greeter(2);
greeter("Hello world");
// 现在我们在运行时用一个新函数扩展对象
import "hyper-super-greeter";
greeter.hyperGreet();

"super-greeter" 的定义：

/* 此示例说明如何为您的函数设置多个重载 */
export interface GreeterFunction {
  (name: string): void
  (time: number): void
}
/* 此示例显示如何导出接口指定的函数 */
export const greeter: GreeterFunction;

我们可以像下面这样扩展现有模块：

/* 导入这个模块添加到的模块 */
import { greeter } from "super-greeter";
/* 声明与上面导入的模块相同的模块，然后我们扩展 greeter 函数的现有声明 */
export module "super-greeter" {
  export interface GreeterFunction {
    /** Greets even better! */
    hyperGreet(): void;
  }
}

例如，当您想要使用如下所示的 JavaScript 代码时：

const Greeter = require("super-greeter");
const greeter = new Greeter();
greeter.greet();

要处理通过 UMD 和模块导入：

export as namespace "super-greeter";
/* 此声明指定类构造函数是从文件中导出的对象 */
export = Greeter;
/* 在此类中编写模块的方法和属性 */
declare class Greeter {
  constructor(customGreeting?: string);
  greet: void;
  myMethod(opts: MyClass.MyClassMethodOptions): number;
}

如果你也想从你的模块中公开类型，你可以把它们放在这个块中，如果您决定包含此命名空间，则模块可能会被错误地导入为命名空间对象，除非 --esModuleInterop 已打开： import * as x from '[~THE MODULE~]'; 错误的！ 不要这样做！

declare namespace MyClass {
  export interface MyClassMethodOptions {
    width?: number;
    height?: number;
  }
}

// @filename: types.d.ts
export type Pet = {
  name: string,
};
// @filename: main.js
/** @param { import("./types").Pet } p */
function walk(p) {
  console.log(`Walking ${p.name}...`);
}

导入类型可以在类型别名声明中使用

/**
 * @typedef {import("./types").Pet} Pet
 */
/** @type {Pet} */
var myPet;
myPet.name;

如果您不知道类型，或者如果它有一个很烦人的大类型，import types 可以用来从模块中获取值的类型：

/**
 * @type {typeof import("./accounts").userAccount}
 */
var x = require("./accounts").userAccount;

/**
 * @param {string}  p1 - 一个字符串参数
 * @param {string=} p2 - 可选参数（Google Closure 语法）
 * @param {string} [p3] - 另一个可选参数（JSDoc 语法）
 * @param {string} [p4="test"] - 具有默认值的可选参数
 * @returns {string} 这是结果
 */
function stringsStrings(p1, p2, p3, p4) {
  // TODO
}

同样，对于函数的返回类型：

/**
 * @return {PromiseLike<string>}
 */
function ps() {}
 
/**
 * @returns {{ a: string, b: number }} - 可以使用“@returns”和“@return”
 */
function ab() {}

您可以使用 @template 标记声明类型参数。 这使您可以创建通用的函数、类或类型：

/**
 * @template T
 * @param {T} x - 流向返回类型的通用参数
 * @returns {T}
 */
function id(x) {
  return x;
}
 
const a = id("string");
const b = id(123);
const c = id({});

使用逗号或多个标签来声明多个类型参数：

/**
 * @template T,U,V
 * @template W,X
 */

您还可以在类型参数名称之前指定类型约束。 只有列表中的第一个类型参数受到约束：

/**
 * @template {string} K - K 必须是字符串或字符串文字
 * @template {{ serious(): string }} Seriousalizable - 一定要有 serious 的方法
 * @param {K} key
 * @param {Seriousalizable} object
 */
function seriousalize(key, object) {
  // ????
}

最后，您可以为类型参数指定默认值：

/** @template [T=object] */
class Cache {
  /** @param {T} initial */
  constructor(T) {
  }
}
let c = new Cache()

# 基于向后查看 tsconfig.json 的 fs 运行编译
$ tsc
# 使用编译器默认值仅为 index.ts 发射 JS
$ tsc index.ts
# 使用默认设置为文件夹 src 中的任何 .ts 文件发出 JS
$ tsc src/*.ts
# 使用 tsconfig.production.json 中的编译器设置发出引用的文件
$ tsc --project tsconfig.production.json
# 为 js 文件发出 d.ts 文件，显示布尔值的编译器选项
$ tsc index.js --declaration --emitDeclarationOnly
# 通过采用字符串参数的编译器选项从两个文件发出单个 .js 文件
$ tsc app.ts util.ts --target esnext --outfile index.js

{
  "extends": "./tsconfig",
  "compilerOptions": {
    "strictNullChecks": false
  }
}