TypeScript 备忘录：如何在 React 中完美运用？

前言

一直以来，ssh 身边都有很多小伙伴对 TS 如何在 React 中运用有很多困惑，他们开始慢慢讨厌 TS，觉得各种莫名其妙的问题降低了开发的效率。

其实如果运用熟练的话，TS 只是在第一次开发的时候稍微多花一些时间去编写类型，后续维护、重构的时候就会发挥它神奇的作用了，还是非常推荐长期维护的项目使用它的。

其实我一直知道英文版有个不错的备忘录，本来想直接推荐给小伙伴，奈何很多人对英文比较头痛，而它中文翻译的版本点进去竟然是这个景象：

既然如此，就自己动手。结合英文原版里的一些示例进行一些扩展，总结成这篇备忘录。

前置基础

阅读本文的前提条件是：

• 熟悉 React 的使用。
• 熟悉 TypeScript 中的类型知识。
• 本文会侧重使用 React Hook 作为示例，当然大部分类型知识都是通用的。

也就是说，这篇文章侧重点在于 「React 和 TypeScript 的结合」，而不是基础知识，基础知识阅读文档即可学习。

也推荐看我 初中级前端的高级进阶指南 这篇文章中的 React 和 TypeScript 章节，这里不多赘述。

工具

• TypeScript Playground with React：可以在线调试 React + TypeScript，只能调试类型，并不能运行代码
• Stackblitz：云开发工具，可以直接运行 React 代码并且预览
• Create React App TypeScript: 本地用脚手架生成 React + TS 的项目

选择你觉得比较中意的调试工具即可。

组件 Props

先看几种定义 Props 经常用到的类型：

基础类型

1type BasicProps = {
2  message: string;
3  count: number;
4  disabled: boolean;
5  /** 数组类型 */
6  names: string[];
7  /** 用「联合类型」限制为下面两种「字符串字面量」类型 */
8  status: "waiting" | "success";
9};

对象类型

1type ObjectOrArrayProps = {
2  /** 如果你不需要用到具体的属性 可以这样模糊规定是个对象 ❌ 不推荐 */
3  obj: object;
4  obj2: {}; // 同上
5  /** 拥有具体属性的对象类型 ✅ 推荐 */
6  obj3: {
7    id: string;
8    title: string;
9  };
10  /** 对象数组 😁 常用 */
11  objArr: {
12    id: string;
13    title: string;
14  }[];
15  /** key 可以为任意 string，值限制为 MyTypeHere 类型 */
16  dict1: {
17    [key: string]: MyTypeHere;
18  };
19  dict2: Record<string, MyTypeHere>; // 基本上和 dict1 相同，用了 TS 内置的 Record 类型。
20}

函数类型

1type FunctionProps = {
2  /** 任意的函数类型 ❌ 不推荐 不能规定参数以及返回值类型 */
3  onSomething: Function;
4  /** 没有参数的函数 不需要返回值 😁 常用 */
5  onClick: () => void;
6  /** 带函数的参数 😁 非常常用 */
7  onChange: (id: number) => void;
8  /** 另一种函数语法 参数是 React 的按钮事件 😁 非常常用 */
9  onClick(event: React.MouseEvent<HTMLButtonElement>): void;
10  /** 可选参数类型 😁 非常常用 */
11  optional?: OptionalType;
12}

React 相关类型

1export declare interface AppProps {
2  children1: JSX.Element; // ❌ 不推荐 没有考虑数组
3  children2: JSX.Element | JSX.Element[]; // ❌ 不推荐 没有考虑字符串 children
4  children4: React.ReactChild[]; // 稍微好点 但是没考虑 null
5  children: React.ReactNode; // ✅ 包含所有 children 情况
6  functionChildren: (name: string) => React.ReactNode; // ✅ 返回 React 节点的函数
7  style?: React.CSSProperties; // ✅ 推荐 在内联 style 时使用
8  // ✅ 推荐原生 button 标签自带的所有 props 类型
9  // 也可以在泛型的位置传入组件 提取组件的 Props 类型
10  props: React.ComponentProps<"button">;
11  // ✅ 推荐 利用上一步的做法 再进一步的提取出原生的 onClick 函数类型 
12  // 此时函数的第一个参数会自动推断为 React 的点击事件类型
13  onClickButton：React.ComponentProps<"button">["onClick"]
14}

函数式组件

最简单的：

1interface AppProps = { message: string };
2
3const App = ({ message }: AppProps) => <div>{message}</div>;

包含 children 的：

利用 React.FC 内置类型的话，不光会包含你定义的 AppProps 还会自动加上一个 children 类型，以及其他组件上会出现的类型：

1// 等同于
2AppProps & { 
3  children: React.ReactNode 
4  propTypes?: WeakValidationMap<P>;
5  contextTypes?: ValidationMap<any>;
6  defaultProps?: Partial<P>;
7  displayName?: string;
8}
9
10// 使用
11interface AppProps = { message: string };
12
13const App: React.FC<AppProps> = ({ message, children }) => {
14  return (
15    <>
16     {children}
17     <div>{message}</div>
18    </>
19  )
20};

Hooks

@types/react 包在 16.8 以上的版本开始对 Hooks 的支持。

useState

如果你的默认值已经可以说明类型，那么不用手动声明类型，交给 TS 自动推断即可：

1// val: boolean
2const [val, toggle] = React.useState(false);
3
4toggle(false)
5toggle(true)

如果初始值是 null 或 undefined，那就要通过泛型手动传入你期望的类型。

1const [user, setUser] = React.useState<IUser | null>(null);
2
3// later...
4setUser(newUser);

这样也可以保证在你直接访问 user 上的属性时，提示你它有可能是 null。

通过 optional-chaining 语法（TS 3.7 以上支持），可以避免这个错误。

1// ✅ ok
2const name = user?.name

useReducer

需要用 Discriminated Unions 来标注 Action 的类型。

1const initialState = { count: 0 };
2
3type ACTIONTYPE =
4  | { type: "increment"; payload: number }
5  | { type: "decrement"; payload: string };
6
7function reducer(state: typeof initialState, action: ACTIONTYPE) {
8  switch (action.type) {
9    case "increment":
10      return { count: state.count + action.payload };
11    case "decrement":
12      return { count: state.count - Number(action.payload) };
13    default:
14      throw new Error();
15  }
16}
17
18function Counter() {
19  const [state, dispatch] = React.useReducer(reducer, initialState);
20  return (
21    <>
22      Count: {state.count}
23      <button onClick={() => dispatch({ type: "decrement", payload: "5" })}>
24        -
25      </button>
26      <button onClick={() => dispatch({ type: "increment", payload: 5 })}>
27        +
28      </button>
29    </>
30  );
31}

「Discriminated Unions」一般是一个联合类型，其中每一个类型都需要通过类似 type 这种特定的字段来区分，当你传入特定的 type 时，剩下的类型 payload 就会自动匹配推断。

这样：

• 当你写入的 type 匹配到 decrement 的时候，TS 会自动推断出相应的 payload 应该是 string 类型。
• 当你写入的 type 匹配到 increment 的时候，则 payload 应该是 number 类型。

这样在你 dispatch 的时候，输入对应的 type，就自动提示你剩余的参数类型啦。

useEffect

这里主要需要注意的是，useEffect 传入的函数，它的返回值要么是一个方法（清理函数），要么就是undefined，其他情况都会报错。

比较常见的一个情况是，我们的 useEffect 需要执行一个 async 函数，比如：

1// ❌ 
2// Type 'Promise<void>' provides no match 
3// for the signature '(): void | undefined'
4useEffect(async () => {
5  const user = await getUser()
6  setUser(user)
7}, [])

虽然没有在 async 函数里显式的返回值，但是 async 函数默认会返回一个 Promise，这会导致 TS 的报错。

推荐这样改写：

1useEffect(() => {
2  const getUser = async () => {
3    const user = await getUser()
4    setUser(user)
5  }
6  getUser()
7}, [])

或者用自执行函数？不推荐，可读性不好。

1useEffect(() => {
2  (async () => {
3    const user = await getUser()
4    setUser(user)
5  })()
6}, [])

useRef

这个 Hook 在很多时候是没有初始值的，这样可以声明返回对象中 current 属性的类型：

const ref2 = useRef<HTMLElement>(null);

以一个按钮场景为例：

1function TextInputWithFocusButton() {
2  const inputEl = React.useRef<HTMLInputElement>(null);
3  const onButtonClick = () => {
4    if (inputEl && inputEl.current) {
5      inputEl.current.focus();
6    }
7  };
8  return (
9    <>
10      <input ref={inputEl} type="text" />
11      <button onClick={onButtonClick}>Focus the input</button>
12    </>
13  );
14}

当 onButtonClick 事件触发时，可以肯定 inputEl 也是有值的，因为组件是同级别渲染的，但是还是依然要做冗余的非空判断。

有一种办法可以绕过去。

1const ref1 = useRef<HTMLElement>(null!);
2

null! 这种语法是非空断言，跟在一个值后面表示你断定它是有值的，所以在你使用 inputEl.current.focus() 的时候，TS 不会给出报错。

但是这种语法比较危险，需要尽量减少使用。

在绝大部分情况下，inputEl.current?.focus() 是个更安全的选择，除非这个值真的不可能为空。（比如在使用之前就赋值了）

useImperativeHandle

推荐使用一个自定义的 innerRef 来代替原生的 ref，否则要用到 forwardRef 会搞的类型很复杂。

1type ListProps = {
2  innerRef?: React.Ref<{ scrollToTop(): void }>
3}
4
5function List(props: ListProps) {
6  useImperativeHandle(props.innerRef, () => ({
7    scrollToTop() { }
8  }))
9  return null
10}

结合刚刚 useRef 的知识，使用是这样的：

1function Use() {
2  const listRef = useRef<{ scrollToTop(): void }>(null!)
3
4  useEffect(() => {
5    listRef.current.scrollToTop()
6  }, [])
7
8  return (
9    <List innerRef={listRef} />
10  )
11}

很完美，是不是？

可以在线调试 useImperativeHandle 的例子。

也可以查看这个useImperativeHandle 讨论 Issue，里面有很多有意思的想法，也有使用 React.forwardRef 的复杂例子。

自定义 Hook

如果你想仿照 useState 的形式，返回一个数组给用户使用，一定要记得在适当的时候使用 as const，标记这个返回值是个常量，告诉 TS 数组里的值不会删除，改变顺序等等……

否则，你的每一项都会被推断成是「所有类型可能性的联合类型」，这会影响用户使用。

1export function useLoading() {
2  const [isLoading, setState] = React.useState(false);
3  const load = (aPromise: Promise<any>) => {
4    setState(true);
5    return aPromise.finally(() => setState(false));
6  };
7  // ✅ 加了 as const 会推断出 [boolean, typeof load]
8  // ❌ 否则会是 (boolean | typeof load)[]
9  return [isLoading, load] as const;[]
10}

对了，如果你在用 React Hook 写一个库，别忘了把类型也导出给用户使用。

React API

forwardRef

函数式组件默认不可以加 ref，它不像类组件那样有自己的实例。这个 API 一般是函数式组件用来接收父组件传来的 ref。

所以需要标注好实例类型，也就是父组件通过 ref 可以拿到什么样类型的值。

1type Props = { };
2export type Ref = HTMLButtonElement;
3export const FancyButton = React.forwardRef<Ref, Props>((props, ref) => (
4  <button ref={ref} className="MyClassName">
5    {props.children}
6  </button>
7));

由于这个例子里直接把 ref 转发给 button 了，所以直接把类型标注为 HTMLButtonElement 即可。

父组件这样调用，就可以拿到正确类型：

1export const App = () => {
2  const ref = useRef<HTMLButtonElement>()
3  return (
4    <FancyButton ref={ref} />
5  )
6}

鸣谢

本文大量使用 react-typescript-cheatsheets 中的例子，加上自己的润色和例子补充，英文好的同学也可以读这个原文扩展学习。

如果这篇文章点赞的人数还不错的话，我会继续更新本系列，欢迎关注「前端从进阶到入院」。

❤️ 谢谢支持

1.喜欢的话别忘了分享、点赞、在看三连哦~。

2.长按下方图片，关注「前端从进阶到入院」，获取我分类整理的原创精选面试热点文章，Vue、React、TS、手写题等应有尽有，我进入字节、滴滴、百度的小伙伴们说文章对他们帮助很大，希望也能帮助到你。