引入 d.ts#

d.ts 文件是 TypeScript 的类型声明文件。与 C/C++ 中类的声明与实现分离类似，我们可以为任意 js 文件创建一个同名的 d.ts 文件，然后在 d.ts 中声明这个 js 中有哪些组件及其类型。在使用 JavaScript 编写的 React 项目中，编译阶段 webpack 的编译器会完全忽略 d.ts 文件（貌似），因此引入 d.ts 文件不会对现有项目的运行造成任何影响。

虽然编译器会忽略 d.ts 文件，但是 VSCode 和 WebStorm 自带的 TypeScript 静态检查器可以根据 d.ts 指出潜在的类型错误，帮助我们发现 bug ，保证类型安全，从而提升代码质量。以下内容对前端常用开发工具 VSCode 和 WebStorm 均有效。

假设你写的应用中有某一个登录组件，它大概长这样：

// App.jsx
import React from "react";
import Login from "./Login";

const App = () => {
  const user = {
    username: "Admin",
    password: "123456",
  };
  const permission = "Tier1";

  return (
    <div>
      <Login user={user} permision={permission} />
    </div>
  );
};

export default App;

// Login.jsx
import React from "react";

const Login = (props) => {
const { user, permission } = props;

  return (
    <div>
      {permission.toLowerCase() == "tier1" && <button>Edit</button>}
      <p>{user.uesrname}</p>
      <p>{user.password}</p>
    </div>
  );
};

export default Login;

为了实践本文所述内容，我们强烈建议您拷贝上述代码至本地，按照上述内容组织好文件布局，然后继续。

很明显，这样的组件是类型不安全的，实际上此处给出的代码存在类型问题，将会导致 bug ，乃至中断渲染 （想一想为什么）。这些 bug 往往很难排查。

创建类型声明#

这两个组件对应的 d.ts 分别是：

// App.d.ts
// 暂无内容

// Login.d.ts
export interface LoginProps {
  user?: {
    username: string;
    password: string;
  };
  permission: "tier1" | "tier2";
}

如果你不会写 TypeScript 这里介绍几个 TypeScript 的概念：

• 类型系统：TypeScript 允许我们为所有变量声明类型，语法为 const/let/var <变量名>: <类型> 。变量名写作 <变量名>? 时表示它的类型为 <类型> | undefine 。

• interface 与 type ：TypeScript 中的 interface 与一般编程语言的 interface 很不一样，它可以用于定义变量的类型。type 是 TypeScript 中更接近 interface 本质的东西，定义好的 interface 和 type 在使用上差别不大，大部分场景中 type 与 interface 可以混用，通常认为应该主要使用其中一种。如果你有选择困难症，可以遵循以下规则：能用 interface 时就用 interface ，interface 实现不了你的需求时就用 type 。上述 LoginProps 用 type 可以定义为：

  export type LoginProps = {
    user?: {
      username: string;
      password: string;
    };
    permission: "tier1" | "tier2";
  }

• 联合类型（Union Type）：注意 LoginProps 的 permission 类型为 "tier1" | "tier2" ，这表示 permission 可以从 "tier1" 和 "tier2" 中任取一种类型。TypeScript 认为任何特定字符串都是一个类型，他们都是类型 string 的子集。const permissionTier1: "tier1"; 表明 permissionTier1 的类型为 "tier1" ，其值只能是 "tier1" 。

编写 JSDoc#

以 Login.jsx 为例，可以将代码修改为：

// @ts-check
import React from "react";

/**
 *
 * @param {import("./Login").LoginProps} props
 * @returns
 */
const Login = (props) => {
const { user, permission } = props;

  return (
    <div>
      {permission.toLowerCase() == "tier1" && <button>Edit</button>}
      <p>{user?.username}</p>
      <p>{user?.password}</p>
    </div>
  );
};

export default Login;

这种形式的注释被称为 JSDoc ，编辑器自带的 TypeScript 静态检查器可以通过 JSDoc 实现类型检查。这时候如果你在编辑器中将鼠标悬浮在 user 上方可以清晰地看见它的类型：

同时注意到代码的最开始我们添加了一行 // @ts-check 这在告诉 TS 静态检查器我们需要为这个文件启用静态检查。添加完成后代码中对 user 的引用会出现红色警告，表明这里存在类型错误。此处的错误是，因为 user 可能为 undefined ，对 undefined 引用 username 属性将引发渲染中断造成白屏，TS 静态检查器发现了这一潜在错误，我们需要为 user 变量的引用可选链运算符 ? 使得当 user 为 undefined 时直接返回 undefined ，避免错误。

如果你希望 TS 静态检查器忽略某一行，可以在前一行写上 // @ts-ignore .

提示：如果你创建 d.ts 文件后发现对应 js 文件并没有识别出 d.ts 中的类型，请尝试在 VSCode 中关闭 js 文件后再打开。

使用 declare 语句#

回到 App.tsx ，现在我们为组件的调用应用类型检查。因为 App 组件没有 props 因此不需要在组件开头声明类型，不过还是要在文件开头添加 // @ts-check 开静态检查。

但是注意到此时 Login 组件下方和红色报错，这是因为一旦为 Login 创建 d.ts 文件，TS 静态检查器将以 Login.d.ts 文件为准获取组件信息，而不是 Login.jsx ，而 Login.d.ts 中没有包含任何 Login 组件的信息，因此导致报错，注意此时项目仍然可以正常编译运行，因为正如前文所述，在使用 JavaScript 的 React 项目中 Webpack 编译器只关注 .js/.jsx 文件，爆红仅仅是静态检查器的行为。

为了修正错误，我们需要在 Login.d.ts 声明 Login 组件，告诉 TS 静态检查器 Login 是什么：现在将 App.d.ts 和 Login.d.ts 文件改为：

// App.d.ts
import * as React from "react";

declare const App: React.FC<{}>;
export default App;

// Login.d.ts
import * as React from "react";

export interface LoginProps {
  user?: {
    username: string;
    password: string;
  };
  permission: "tier1" | "tier2";
}

declare const Login: React.FC<LoginProps>;
export default Login;

在 App 和 Login 前添加 declare 关键字是因为 d.ts 中应该只包含 Login 或 App 的类型而没有具体实现，因此需要使用 declare 关键字告诉 TS 静态检查器这里有一个名为 Login 的 React 组件，其 Props 的类型为 LoginProps ，真正的实现在项目的某处，由编译器自己去找。React.FC<LoginProps> 实际上是 React.FunctionComponent<LoginProps> 的别名，等价于：

declare const Login: (props: LoginProps) => React.ReactElement<LoginProps>

在不涉及泛型的情况下，使用 React.FC<> 即可。

为 Login 组件添加类型声明后，我们将发现，TS 静态检查器在 App 中了解到 Login 组件的 Props 信息，知道所有 Props 应该类型，同时发现先前的代码中对 Login 组件的 permision 属性传入是一个拼写错误。因为 TS 了解类型信息，所以可以给出可靠的代码提示，根据代码提示修改错误即可：

最后给出最终修改好的所有代码：

App.jsx

// @ts-check
import React from "react";
import Login from "./Login";

const App = () => {
  const user = {
    username: "Admin",
    password: "123456",
  };
  const permission = "tier1";

  return (
    <div>
      <Login user={user} permission={permission} />
    </div>
  );
};

export default App;

App.d.ts

import * as React from "react";

declare const App: React.FC<{}>;
export default App;

Login.jsx

// @ts-check
import React from "react";

/**
 *
 * @param {import("./Login").LoginProps} props
 * @returns
 */
const Login = (props) => {
  const { user, permission } = props;

  return (
    <div>
      {permission.toLowerCase() === "tier1" && <button>Edit</button>}
      <p>{user?.username}</p>
      <p>{user?.password}</p>
    </div>
  );
};

export default Login;

Login.d.ts

import * as React from "react";

export interface LoginProps {
  user?: {
    username: string;
    password: string;
  };
  permission: "tier1" | "tier2";
}

declare const Login: React.FC<LoginProps>;
export default Login;

定义 Action#

上述 Redux 示例里有两个 action ，均在 TestLoginAction.js 下，和之前做类型检查的步骤一样，添加对应的 TestLoginAction.d.ts 如下：

export declare const TEST_LOGIN_LOGIN: "testLogin/login";
export type TEST_LOGIN_LOGIN = typeof TEST_LOGIN_LOGIN;

interface User {
  username: string;
  password: string;
}

export interface ITestLoginLoginAction {
  type: TEST_LOGIN_LOGIN;
  payload: {
    user: User;
    timeStamp: string;
  };
}

export declare const TEST_LOGIN_LOGOUT: "testLogin/logout";
export type TEST_LOGIN_LOGOUT = typeof TEST_LOGIN_LOGOUT;

export interface ITestLoginLogoutAction {
  type: TEST_LOGIN_LOGOUT;
}

export type TestLoginAction = ITestLoginLoginAction | ITestLoginLogoutAction;

我们想要为每一种 action 都指定对应的 payload ，这可以使用 interface 实现，这里有两种 action —— TEST_LOGIN_LOGIN 和 TEST_LOGIN_LOGOUT ，其中 TEST_LOGIN_LOGIN 这个 action 需要特定类型的 payload ，而另一个不需要，TestLogin 的所有 Action 类型被汇总为 TestLoginAction 这种类型，它是所有 Action 的联合类型。

声明 State 的类型#

TestLogin 的 state 也需要确定类型，从上可知 user 和 loginTime 都可以是 null ，实际上让它默认是 undefined 也问题不大，除非需要和后端传来的数据做匹配，不过更好的做法是初始化 username 和 password 为 ""。可以先在 TestLoginReducer.d.ts 加上：

export interface TestLoginState {
  user?: {
    username: string;
    password: string;
  };
  loginTime?: string;
}

然后在 TestLoginReducer.js 中声明：

/**
 * @typedef {import("./TestLoginReducer").TestLoginState} TestLoginState
 */

/**
 * @type {TestLoginState}
 */
const initialState = {
  user: {
    username: "",
    password: "",
  },
  loginTime: "",
};

类型安全的 Reducer#

Redux 中的 Reducer 是一种泛型，其原型为 Reducer<S, A> = (prevState: S, action: A) => S ，源于 $\lambda$ 演算，意思是给定初始的 state ，输入一个 action 序列，最终得到另外一个 state 。JavaScript 中的 reduce 函数式接口概念与此类似。

对于 testLoginReducer 这个函数，可以直接将其声明为：

/**
 * @type {import("react").Reducer<TestLoginState, TestLoginAction>}
 */
export const testLoginReducer = (state = initialState, action) => {
  switch (action.type) {
	// ...
  }
};

然后在 testLoginReducer 中启用 // @ts-check ，上述 reducer 中的 switch 语句是故意留空的，这时候代码会爆红，别急，稍后我们会来处理。接着还需要在 TestLoginReducer.d.ts 中声明 testLoginReducer 的存在，即添加代码：

import { Reducer } from "react";
import { TestLoginAction } from "./TestLoginAction";
export declare const testLoginReducer: Reducer<TestLoginState, TestLoginAction>;

此时 testLoginReducer 就是类型安全的了。

现在我们可以试着写一下 testLoginReducer 具体内容，将代码修改为：

// @ts-check
import * as actions from "./TestLoginAction";
/**
 * @typedef {import("./TestLoginReducer").TestLoginState} TestLoginState
 * @typedef {import("./TestLoginAction").TestLoginAction} TestLoginAction
 */

// ...

/**
 * @type {import("react").Reducer<TestLoginState, TestLoginAction>}
 */
export const testLoginReducer = (state = initialState, action) => {
  switch (action.type) {
    case actions.TEST_LOGIN_LOGIN:
      const payload = action.payload;
      return {
        ...state,
        user: payload.user,
      };
    case actions.TEST_LOGIN_LOGOUT:
      return {
        ...state,
        user: undefined,
      };
  }
};

此时爆红消失了。我们建议你手动编写这段代码而不是直接复制，然后你会发现，TS 静态检查器会在每个分支智能地判断出 action 的类型，从而让 VSCode 给出可靠的代码提示。

带类型封装的 useSelector 与 useDispatch#

最后，我们需要在使用 dipsatch 和 selector 时也能享受到类型静态类型检查的好处，提升代码质量。为实现这一点，我们需要封装自己的 useSelector 和 useDispatch 。

首先创建 store.d.js ，添加如下代码：

import { EmptyObject, Store } from "redux";
import { TestLoginState } from "./TestLoginReducer";
import { TypedUseSelectorHook, useDispatch } from "react-redux";
import { Dispatch } from "react";
import { TestLoginAction } from "./TestLoginAction";

export type RootState = {
  testLogin: TestLoginState;
};

export type RootAction = TestLoginAction;

export type AppDispatch = Dispatch<RootAction>;

export declare const store: Store<EmptyObject>;

我们先定义好整个 state 的类型，因为在 combineReducers 里我们写道：testLogin: testLoginReducer ，那么 TestLoginState 在所谓 RootState 的属性名就是 testLogin ，将来引入其他 Reducer 时同理。

然后定义 RootAction 的类型，这是整个项目所有 Action 的联合类型（此处只有一类 Action 即 TestLoginAction）。接着定义自己的 dispatch 类型，即 AppDispatch: Dispatch<RootAction> ，这里的意思是凡是使用这种类型的 dispatch 时，传入的 Action 都必须是 RootAction 中的某一个实例，即在 RootAction 中注册的任意一种 Action 。

接着，注意到我们在 store.js中 export 了 store 这种变量，因此需要在 store.d.ts 中声明这个变量。由于 createStore 方法是一个过时的 API ，store 的类型变得无关紧要，所以简单声明为 Store<EmptyObject> 即可。

最后，创建 hooks.js 和 hooks.d.ts ，内容分别为：

hooks.js

import { useDispatch, useSelector } from "react-redux";

export const useAppSelector = useSelector;
export const useAppDispatch = useDispatch;

hooks.d.ts

import { TypedUseSelectorHook } from "react-redux";
import { AppDispatch, RootState } from "./store";

export declare const useAppSelector: TypedUseSelectorHook<RootState>;
export declare const useAppDispatch: () => AppDispatch;

现在，我们可以在组件中使用类型安全的 useAppSelector 和 useAppDispatch 来与 Redux 交互了。

回到 App.jsx ，将代码修改为：

// @ts-check
import React from "react";
import Login from "./Login";
import { useAppSelector } from "./hooks";

const App = () => {
  const { user } = useAppSelector((state) => ({
    user: state.testLogin.user,
  }));

  const permission = "tier1";

  return (
    <div>
      <Login user={user} permission={permission} />
    </div>
  );
};

export default App;

你将会惊奇地发现使用 useAppSelector 时 state 是包含类型信息的：

同样地在 Login.jsx 中使用全新的 useAppDispatch ：

// @ts-check
import React from "react";
import { TEST_LOGIN_LOGIN } from "./TestLoginAction";
import { useAppDispatch } from "./hooks";

/**
 *
 * @param {import("./Login").LoginProps} props
 * @returns
 */
const Login = (props) => {
  const { user, permission } = props;
  const dispatch = useAppDispatch();

  const handleLogin = () => {
    dispatch({
      type: TEST_LOGIN_LOGIN,
      payload: {
        user: {
          username: "Admin",
          password: "123456",
        },
        timeStamp: new Date().toISOString(),
      },
    });
  };

  return (
    <div>
      {permission.toLowerCase() == "tier1" && <button>Edit</button>}
      <p>{user?.username}</p>
      <p>{user?.password}</p>
    </div>
  );
};

export default Login;

在这里使用 dispatch 时也可以给出可靠的代码提示。

实现 ActionCreator#

比起本文所述的 Redux 的使用方法，Redux 官方目前更加推荐另一种写法，即前文数次提到的 Redux Toolkit。Redux Toolkit 是一种对 Redux 更高层次的封装，要使用它实现上述 TestLoginState 需求，代码可以是：

// TestLoginSlice.ts
import { createSlice, PayloadAction } from "@reduxjs/toolkit";

interface User {
  username: string;
  password: string;
}

interface TestLoginState {
  user?: User;
  loginTime?: string;
}

const initialState: TestLoginState = {
  user: {
    username: "",
    password: "",
  },
  loginTime: "",
};

export const testLoginSlice = createSlice({
  name: "testLogin",
  initialState,
  reducers: {
    login: (
      state,
      action: PayloadAction<{
        user: User;
        timeStamp: string;
      }>
    ) => {
      const payload = action.payload;
      state.user = payload.user;
      state.loginTime = payload.timeStamp;
    },
    logout: (state) => {
      state.user = undefined;
    },
  },
});

export const { login, logout } = testLoginSlice.actions;

export default testLoginSlice.reducer;

我们注意到，传统的 Redux 写法需要手动编写 Reducer<S, A> 函数，形成大量模板代码，有时候这是难以维护的。Redux Toolkit 的开发者注意到 action.type 大部分时候是可以对开发者隐藏的，因此使用 Slice 来将 Reducer 和 Action 统一起来。

上述代码中 export 的 login 和 logout 并不是带有 type 属性的 action 实例，而是生成 action 的函数，称为 ActionCreator 。以 login 为例，注意到 reducers 中写着 login 的函数签名为 ：

(state, action: PayloadAction<{user: User; timeStamp: string;}>) => void

action 的类型实际上是：

{
  type: string;
  payload: {
    user: User; 
    timeStamp: string;
  };
}

而下方 export 的 login 是一个类型为：

(payload: { user: User; timeStamp: string; }) => { 
  type: string; 
  payload: { user: User; timeStamp: string; }; 
}

的 ActionCreator ，返回的正是一个 action ，一般来说，实际执行的时候 type 的值将满足 Redux Toolkit 的命名规范： testLogin/login ，dispatch 再根据这个 type 选择 reducers 中的某个方法执行。

虽然 Redux Toolkit 有诸多好处，既可以化简代码，又保证了类型安全，但是很可惜，从原生 Redux 写法迁移到 Redux Toolkit 的难度不会比一次性从 JavaScript 迁移到 TypeScript 低多少，因为直接迁移意味着所有显示构造 action 并执行 dispatch 的语句都需要进行修改，还需要改写所有 Reducer<S, A> 。就目前我正在尝试引入静态检查的项目而言，这类 dispatch 的调用超过 $2,200$ 处，未来还将持续增加。因此直接迁移到 Redux Toolkit 几乎不可行。

不过我们还是可以通过手动创建 ActionCreator 来简化 dispatch 的调用。以前文提到的 login 和 logout 为例。我们只需要在 TestLoginAction.js 中添加两个函数 loginAction 和 logoutAction：

// @ts-check
export const TEST_LOGIN_LOGIN = "testLogin/login";
export const TEST_LOGIN_LOGOUT = "testLogin/logout";

/**
 * @type {import("./TestLoginAction").LoginAction}
 */
export const loginAction = (user) => ({
  type: TEST_LOGIN_LOGIN,
  payload: {
    user: user,
    timeStamp: new Date().toISOString(),
  },
});

/**
 * @type {import("./TestLoginAction").LogoutAction}
 */
export const logoutAction = () => ({
  type: TEST_LOGIN_LOGOUT,
});

然后在 TestLoginAction.d.ts 中将其声明为：

export type LoginAction = (user: User) => ITestLoginLoginAction;
export declare const loginAction: LoginAction;
export type LogoutAction = () => ITestLoginLogoutAction;
export declare const logoutAction: LogoutAction;

我们就完成了 ActionCreator 的手动创建。

之后就可以使用形如 dispatch(loginAction(...)) 的写法修改 Redux State 的状态了。

一些常用的 Typescript 类型声明示例#

因为这不是一本字典，所以这里采用 Q&A 的形式给出一些示例：

import * as React from "react";
import { BoxProps } from "@mui/material";

export interface LoginProps extends BoxProps {
  user?: {
    username: string;
    password: string;
  };
  permission: "tier1" | "tier2";
}

declare const Login: React.FC<LoginProps>;
export default Login;

// @ts-check
import React from "react";
import { Box } from "@mui/material";
import { TEST_LOGIN_LOGIN } from "./TestLoginAction";

/**
 *
 * @param {import("./Login").LoginProps} props
 * @returns
 */
const Login = (props) => {
  const { user, permission, sx, children, ...oterhs } = props;
  return (
    <Box
      sx={{
        padding: "1.6rem",
        ...sx,
      }}
      {...oterhs}
    >
      {permission.toLowerCase() == "tier1" && <button>Edit</button>}
      <p>{user?.username}</p>
      <p>{user?.password}</p>
      {children}
    </Box>
  );
};

export default Login;

import * as React from "react";
export interface LoginProps {
  user?: {
    username: string;
    password: string;
  };
  permission: "tier1" | "tier2";
  children?: React.ReactNode;
}

interface AutocompleteProps<T, Multiple extends boolean | undefined, DisableClearable extends boolean | undefined, FreeSolo extends boolean | undefined, ChipComponent extends React.ElementType<any> = "div">

export type CustomAutocompleteProps<T> = 
    AutocompleteProps<T, boolean, boolean, boolean, "div">;
export declare const CustomAutocomplete: <T>(
  props: CustomAutocompleteProps<T>
) => React.ReactElement<CustomAutocompleteProps<T>>;

interface TypeA {
  a: string;
  b: number:
  c: boolean;
  d: () => void;
}

type TypeB = Omit<TypeA, "b" | "d">;

interface TypeB {
  a: string;
  c: boolean;
}

interface TypeA {
  a: string;
  b: number:
}
interface TypeB {
  c: boolean;
  d: () => void;
}

type TypeC = TypeA & TypeB;

interface TypeC {
  a: string;
  b: number:
  c: boolean;
  d: () => void;
}

其他常见问题#

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    },
    "declaration": true,
    "declarationMap": true,
    "declarationDir": "./dist",
    "jsx": "react",
    "target": "ES2015",
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true
  },
  "exclude": ["node_modules", "public", "server"]
}