507 lines
16 KiB
Markdown
507 lines
16 KiB
Markdown
---
|
||
tags: [React, TypeScript, Frontend]
|
||
create time: 2026-04-29 22:09
|
||
---
|
||
|
||
# TS + React
|
||
|
||
## 概述
|
||
|
||
TypeScript 为 React 提供编译时类型检查和智能提示，将运行时错误提前到编码阶段。本文档从 Props、State、Hook、Ref 等核心场景切入，逐步深入到泛型推导、区分联合类型和 Schema 校验等进阶模式。
|
||
|
||
> [!question] 为什么 React + TS 值得投入？
|
||
>
|
||
> React 本身是纯 JS 库，但大型项目中「谁在改什么数据」「这个函数接收什么参数」往往成为协作瓶颈。TS 让你在写代码时就能获得精确的类型反馈，而不是等到测试环节才发现 `undefined is not a function`。
|
||
|
||
## Props 类型定义
|
||
|
||
### 基础方式
|
||
|
||
```tsx
|
||
// ✅ 方式1：interface（推荐，可 extend）
|
||
interface ButtonProps {
|
||
label: string;
|
||
onClick?: () => void;
|
||
}
|
||
const Button = ({ label, onClick }: ButtonProps) => (
|
||
<button onClick={onClick}>{label}</button>
|
||
);
|
||
|
||
// ✅ 方式2：type alias（适合联合类型）
|
||
type ButtonProps = { label: string; onClick?: () => void };
|
||
|
||
// ❌ 避免：解构后不标注类型
|
||
function BadComponent({ a, b }) { ... } // a 和 b 都是 any!
|
||
```
|
||
|
||
> [!tip] interface vs type —— 何时用哪个？
|
||
>
|
||
> - **优先 interface**：它支持 `extends` / `implements`，更适合组件 Props 的层级扩展
|
||
> - **选 type**：当你需要联合类型 (`A | B`)、交叉类型 (`A & B`) 或映射类型 (`Record<K,V>`) 时
|
||
|
||
### 合成事件类型
|
||
|
||
```tsx
|
||
// ❌ 不要用 HTML 原生的 Event
|
||
const handleChange = (e: Event) => {};
|
||
|
||
// ✅ 使用 React 的合成事件类型
|
||
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
|
||
e.target.value; // string | number | string[]（取决于 input type）
|
||
};
|
||
|
||
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
|
||
e.preventDefault(); // 阻止表单默认提交
|
||
};
|
||
|
||
const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
|
||
console.log(e.button); // 0=左键, 1=中键, 2=右键
|
||
};
|
||
|
||
const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
|
||
if (e.key === "Enter") submit();
|
||
};
|
||
```
|
||
|
||
> [!warning] 常见误区：syntheticEvent 的池化问题
|
||
>
|
||
> React 17 之前合成事件会被复用（池化），异步访问时可能已被清空。在 `setTimeout` 或 Promise 回调中，请先读取到局部变量：
|
||
> ```tsx
|
||
> const value = e.target.value; // 先取值
|
||
> setTimeout(() => console.log(value), 100);
|
||
> ```
|
||
|
||
### Children 类型
|
||
|
||
```tsx
|
||
// 通用 children —— 接受任意合法 React 节点
|
||
function Card({ children }: { children: React.ReactNode }) {}
|
||
|
||
// 严格类型 children —— 限制允许的子节点类型
|
||
interface TabsProps {
|
||
children: React.ReactElement<TabProps>; // 只能是 Tab 组件
|
||
}
|
||
|
||
// 泛型 children —— 子节点携带的数据类型可参数化
|
||
interface ListProps<T> {
|
||
children: React.ReactElement<{ item: T }> [];
|
||
}
|
||
```
|
||
|
||
## State 类型推导
|
||
|
||
### useState
|
||
|
||
```tsx
|
||
interface User { name: string; role: "admin" | "user"; age: number }
|
||
|
||
// 完整泛型
|
||
const [user, setUser] = useState<User>({ name: "", role: "user", age: 0 });
|
||
|
||
// 可选初始值 —— 必须显式声明联合类型
|
||
const [user, setUser] = useState<User | null>(null);
|
||
// 使用时需判空
|
||
user?.name; // ✅ 可选链，安全
|
||
(user as User).name; // or: 类型断言
|
||
user!?.name; // non-null assertion（慎用）
|
||
```
|
||
|
||
> [!tip] 利用构造函数推断
|
||
>
|
||
> 当 initialState 是个对象字面量时，可以用类构造函数的模式让 TS 自动推导出 State 类型，减少重复书写：
|
||
> ```tsx
|
||
> class UserStore {
|
||
> name = "";
|
||
> role: "admin" | "user" = "user";
|
||
> age = 0;
|
||
> }
|
||
> const [user, setUser] = useState(new UserStore());
|
||
> // 注意：这里 user 类型就是 new UserStore() 的实例类型
|
||
> ```
|
||
|
||
### useReducer
|
||
|
||
```tsx
|
||
interface State { items: Item[]; filter: string }
|
||
type Action =
|
||
| { type: "SET_FILTER"; payload: string }
|
||
| { type: "ADD_ITEM"; payload: Item };
|
||
|
||
function reducer(state: State, action: Action): State {
|
||
switch (action.type) {
|
||
case "SET_FILTER": return { ...state, filter: action.payload };
|
||
case "ADD_ITEM": return { ...state, items: [...state.items, action.payload] };
|
||
}
|
||
}
|
||
const [state, dispatch] = useReducer(reducer, initialState);
|
||
```
|
||
|
||
## Ref 类型定义
|
||
|
||
### useRef
|
||
|
||
```tsx
|
||
// 元素 ref —— 最常用
|
||
const inputRef = useRef<HTMLInputElement>(null);
|
||
|
||
// mutable value ref（不触发 re-render）
|
||
const timerIdRef = useRef<ReturnType<typeof setInterval>>(undefined);
|
||
timerIdRef.current = setInterval(() => {}, 1000);
|
||
|
||
// class component style ref object（用于挂载子组件引用）
|
||
const childRef = useRef<ComponentInstance>(null);
|
||
// 需要 useImperativeHandle 暴露方法给父级
|
||
```
|
||
|
||
> [!example] 为什么 ref.current 改变不会触发渲染？
|
||
>
|
||
> React 的更新机制只响应 setState 调用。ref 的设计初衷就是绕过 React 的响应式系统——比如在 useEffect 中保存上一次 props 的值、存储定时器 ID、或者调用子组件的原生 DOM API。如果你发现修改 ref 后需要 UI 同步更新，说明你可能应该用 state。
|
||
|
||
### forwardRef + useImperativeHandle
|
||
|
||
```tsx
|
||
const FancyInput = forwardRef<HTMLInputElement, { label: string }>(
|
||
function FancyInput(props, ref) {
|
||
const innerRef = useRef<HTMLInputElement>(null);
|
||
|
||
// 只暴露 focus 和 blur 给父组件，隐藏其他原生方法
|
||
useImperativeHandle(ref, () => ({
|
||
focus: () => innerRef.current?.focus(),
|
||
blur: () => innerRef.current?.blur(),
|
||
}));
|
||
|
||
return <input ref={innerRef} label={props.label} />;
|
||
}
|
||
);
|
||
```
|
||
|
||
## Hook 类型推导
|
||
|
||
### 自定义 Hook 返回值
|
||
|
||
```tsx
|
||
interface UseCountReturn {
|
||
count: number;
|
||
increment: () => void;
|
||
decrement: () => void;
|
||
}
|
||
|
||
function useCount(initial = 0): UseCountReturn {
|
||
const [count, setCount] = useState(initial);
|
||
return {
|
||
count,
|
||
increment: () => setCount(c => c + 1),
|
||
decrement: () => setCount(c => c - 1),
|
||
};
|
||
}
|
||
```
|
||
|
||
> [!tip] 让返回值类型自动推导
|
||
>
|
||
> 如果不想手动编写返回类型接口，可以借助 TypeScript 4.7+ 的 `as const` 技巧或使用 `ReturnType` 工具类型：
|
||
> ```tsx
|
||
> function useMouse() {
|
||
> const [pos, setPos] = useState({ x: 0, y: 0 });
|
||
> useEffect(() => { /* ... */ }, []);
|
||
> return pos; // TS 会自动推导出 { readonly x: number; readonly y: number }
|
||
> }
|
||
> ```
|
||
|
||
### 泛型 Hook —— 最强大的类型推导场景
|
||
|
||
```tsx
|
||
function useAsync<T, Args extends any[]>(
|
||
asyncFn: (...args: Args) => Promise<T>,
|
||
deps: DependencyList
|
||
): { data: T | null; loading: boolean; error: Error | null; invoke: (...args: Args) => void } {
|
||
const [data, setData] = useState<T | null>(null);
|
||
const [loading, setLoading] = useState(false);
|
||
const [error, setError] = useState<Error | null>(null);
|
||
|
||
const invoke = useCallback(async (...args: Args) => {
|
||
setLoading(true);
|
||
setError(null);
|
||
try {
|
||
const result = await asyncFn(...args);
|
||
setData(result);
|
||
} catch (err) {
|
||
setError(err as Error);
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
}, [asyncFn, ...deps]);
|
||
|
||
useEffect(() => { invoke(); }, [invoke]);
|
||
|
||
return { data, loading, error, invoke };
|
||
}
|
||
|
||
// T 自动推导！无需手动指定
|
||
const { data: users } = useAsync(fetchUsers, []); // data: User[] | null
|
||
const { data: user } = useAsync(fetchUserById, [id]); // data: User | null
|
||
const { data: config } = useAsync(fetchConfig, [env]); // data: Config | null
|
||
```
|
||
|
||
> [!question] 为什么 `Args extends any[]`？
|
||
>
|
||
> 这让我们可以同时参数化「异步函数的返回值类型」和「异步函数的入参」。例如 `fetchUserById(id: string)` 的 `T = User`，`Args = [string]`，类型信息从内到外全自动推导，不需要在调用处再次声明。
|
||
|
||
## discriminated Union（区分联合类型）
|
||
|
||
```tsx
|
||
interface SuccessAction { type: "success"; data: User[] }
|
||
interface ErrorAction { type: "error"; error: string }
|
||
interface LoadingAction { type: "loading" }
|
||
|
||
type Action = SuccessAction | ErrorAction | LoadingAction;
|
||
|
||
function reducer(state: State, action: Action): State {
|
||
switch (action.type) {
|
||
case "success":
|
||
return { ...state, data: action.data, status: "loaded" };
|
||
// ✅ TS 自动推断 action.data 是 User[]
|
||
case "error":
|
||
return { ...state, error: action.error };
|
||
// ✅ TS 自动推断 action.error 是 string
|
||
case "loading":
|
||
return { ...state, status: "loading" };
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!important] exhaustive check 防漏分支
|
||
>
|
||
> 添加一个 `default` 分支并用 `never` 类型确保所有联合成员都被覆盖：
|
||
> ```tsx
|
||
> function reducer(state: State, action: Action): State {
|
||
> switch (action.type) {
|
||
> case "success": return { ...state, status: "loaded" };
|
||
> case "error": return { ...state, status: "failed" };
|
||
> case "loading": return { ...state, status: "pending" };
|
||
> default:
|
||
> const _exhaustiveCheck: never = action;
|
||
> throw new Error(`Unhandled action type: ${_exhaustiveCheck}`);
|
||
> }
|
||
> }
|
||
> ```
|
||
> 一旦新增了一个 Action 类型但没有在 switch 中处理，TS 编译器会立刻报错。
|
||
|
||
```mermaid
|
||
graph LR
|
||
A["Union Type"] -->|"switch on type field"| B["Type Narrowing"]
|
||
B --> C["discriminated union — 最优解"]
|
||
B --> D["typeof check"]
|
||
B --> E["in operator"]
|
||
B --> F["instanceof check"]
|
||
|
||
style C fill:#61DAFB,color:#000
|
||
style A fill:#fff,color:#000
|
||
```
|
||
|
||
## Context 类型定义
|
||
|
||
```tsx
|
||
interface ThemeContextType {
|
||
theme: "light" | "dark";
|
||
toggleTheme: () => void;
|
||
}
|
||
|
||
// 创建 context 时传入默认值（可为 null，配合非空断言使用）
|
||
const ThemeContext = createContext<ThemeContextType | null>(null);
|
||
|
||
// 封装类型安全的消费 Hook —— 比直接 useContext 更安全
|
||
function useTheme(): ThemeContextType {
|
||
const ctx = useContext(ThemeContext);
|
||
if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
|
||
return ctx;
|
||
}
|
||
|
||
// Provider 类型 —— 将 value 的类型与 Context 绑定
|
||
function ThemeProvider({ children }: { children: React.ReactNode }) {
|
||
const [theme, setTheme] = useState<"light" | "dark">("light");
|
||
|
||
return (
|
||
<ThemeContext.Provider value={{ theme, toggleTheme: () => setTheme(t => t === "light" ? "dark" : "light") }}>
|
||
{children}
|
||
</ThemeContext.Provider>
|
||
);
|
||
}
|
||
```
|
||
|
||
> [!tip] 多 Context 时的组合策略
|
||
>
|
||
> Context 数量增多后，推荐使用 **多个小型 Context** 而非一个巨型 Context：每个 Context 负责一小块职责（认证、主题、语言），这样消费者只会在自己关注的 context 变化时重渲染。也可以用一个 Context 包裹另一个，形成嵌套结构。
|
||
|
||
## 泛型组件与 Polymorphic Components
|
||
|
||
### 泛型列表组件
|
||
|
||
```tsx
|
||
interface SelectableTableProps<T> {
|
||
data: T[];
|
||
renderRow: (item: T, selected: boolean) => React.ReactNode;
|
||
selectedIds: Set<string>;
|
||
onSelect: (id: string) => void;
|
||
getId: (item: T) => string;
|
||
}
|
||
|
||
function SelectableTable<T>({
|
||
data, renderRow, selectedIds, onSelect, getId,
|
||
}: SelectableTableProps<T>) {
|
||
return (
|
||
<table>
|
||
<tbody>
|
||
{data.map(item => {
|
||
const id = getId(item);
|
||
const selected = selectedIds.has(id);
|
||
return <tr key={id} onClick={() => onSelect(id)}>
|
||
<td>{renderRow(item, selected)}</td>
|
||
</tr>;
|
||
})}
|
||
</tbody>
|
||
</table>
|
||
);
|
||
}
|
||
|
||
// 使用：T 自动推导为 User
|
||
<SelectableTable
|
||
data={users}
|
||
getId={(u: User) => u.id}
|
||
renderRow={(u, sel) => <span style={{ background: sel ? "#eee" : "" }}>{u.name}</span>}
|
||
selectedIds={selected}
|
||
onSelect={setId}
|
||
/>
|
||
```
|
||
|
||
### HTML 标签聚合组件（Polymorphic）
|
||
|
||
```tsx
|
||
// 基于 JSX.IntrinsicElements 实现 polymorphic component
|
||
type PolymorphicComponent<P, D extends keyof JSX.IntrinsicElements> = {
|
||
<As extends keyof JSX.IntrinsicElements = D>(
|
||
props: P & { as?: As } & JSX.IntrinsicElements[As]
|
||
): ReactNode;
|
||
};
|
||
|
||
// Button 可以是 button/div/a 等任何 HTML 元素
|
||
const Button: PolymorphicComponent<
|
||
{ variant?: "primary" | "secondary" },
|
||
"button"
|
||
> = ({ variant = "primary", as: Tag = "button", ...props }) => (
|
||
<Tag className={`btn btn-${variant}`} {...props} />
|
||
);
|
||
```
|
||
|
||
> [!warning] Polymorphic Component 的类型难点
|
||
>
|
||
> 上述写法是简化版。生产环境通常借助第三方库如 `@radix-ui/react-slot` 来处理复杂的泛型推导，因为要让 `as="a"` 时同时合并 `<a>` 的属性（`href`, `target` 等）而不产生冲突，泛型约束较为复杂。
|
||
|
||
## Form 校验与 Zod Schema
|
||
|
||
现代 React + TS 项目中，推荐使用 **Zod** 等 Schema 库将校验逻辑和类型推导合二为一：
|
||
|
||
```tsx
|
||
import { z } from "zod";
|
||
|
||
// 1. 定义 Schema —— 类型从 schema 自动推导
|
||
const LoginSchema = z.object({
|
||
email: z.string().email(),
|
||
password: z.string().min(8),
|
||
});
|
||
type LoginFormValue = z.infer<typeof LoginSchema>;
|
||
|
||
// 2. React Hook Form + ZodResolver 无缝对接
|
||
const { register, handleSubmit, formState: { errors } } = useForm<LoginFormValue>({
|
||
resolver: zodResolver(LoginSchema),
|
||
});
|
||
|
||
// 3. 模板中使用 —— errors 和 register 都有完整类型提示
|
||
<form onSubmit={handleSubmit(onSubmit)}>
|
||
<input {...register("email")} placeholder="Email" />
|
||
{/* errors.email?.message 有类型提示 */}
|
||
{errors.email && <span>{errors.email.message}</span>}
|
||
|
||
<input {...register("password")} type="password" />
|
||
<button type="submit">登录</button>
|
||
</form>
|
||
```
|
||
|
||
> [!tip] 为什么选择 Zod 而非 Yup？
|
||
>
|
||
> - Zod 用 TypeScript 原生语法定义，无需额外 import 类型（Yup 需要 `yupToZooooootTypes` 等桥接方案）
|
||
> - Zod 零依赖、性能更优，且支持 `.parse()` 运行时校验与 `.infer()` 类型推导一体化
|
||
> - Zod 的错误消息更可定制化
|
||
|
||
## 常见坑点与避坑指南
|
||
|
||
> [!failure] 坑1：`any` 的隐式传播
|
||
>
|
||
> `Array<any>`、`Record<string, any>` 会让整个链条失去类型保护。替代方案：
|
||
> - 用 `unknown` 替代顶层 `any`（必须先类型守卫才能使用）
|
||
> - 用泛型 `<T>` 传递具体的数据结构
|
||
>
|
||
> ```tsx
|
||
> // ❌ 危险
|
||
> const data: Record<string, any> = {};
|
||
> data.foo.bar.baz; // 编译通过，运行崩溃
|
||
>
|
||
> // ✅ 安全
|
||
> const data: Record<string, unknown> = {};
|
||
> if (typeof data.foo === "object" && data.foo !== null) {
|
||
> data.foo.bar; // 需要额外的守卫
|
||
> }
|
||
> ```
|
||
|
||
> [!failure] 坑2：事件处理器中的类型收窄失效
|
||
>
|
||
> 箭头函数无法正确收窄：
|
||
> ```tsx
|
||
> // ❌ TS 无法推断 e 具体是哪个事件
|
||
> <button onClick={(e) => handleClick(e)}>Click</button>
|
||
>
|
||
> // ✅ 用命名函数保持类型信息
|
||
> <button onClick={(e) => handleClick(e)}>Click</button>
|
||
> // 但最好直接在属性上写，不包箭头
|
||
> <button onClick={handleClick}>Click</button>
|
||
> ```
|
||
|
||
> [!failure] 坑3：useState 初始值的类型陷阱
|
||
>
|
||
> ```tsx
|
||
> // ❌ 类型变成 never[] —— TS 推断了最窄的空数组类型
|
||
> const [items, setItems] = useState([]);
|
||
> items.push("hello"); // error: Property 'push' does not exist on type 'never[]'
|
||
>
|
||
> // ✅ 显式声明泛型
|
||
> const [items, setItems] = useState<string[]>([]);
|
||
>
|
||
> // ✅ 或者用 non-empty array 初始化
|
||
> const [items, setItems] = useState(["default"]);
|
||
> ```
|
||
|
||
> [!failure] 坑4：React.FC 的副作用
|
||
>
|
||
> `React.FC` 在早期被广泛推荐，但现在社区趋于弃用原因如下：
|
||
> - 它会隐式包含 `children` prop（即使你的组件不需要）
|
||
> - 不支持泛型
|
||
> - 使得 ReturnType 无法正确推导
|
||
> - 使 HOC 的 WrappedComponent 类型丢失
|
||
>
|
||
> ```tsx
|
||
> // ❌ 不推荐
|
||
> const MyComponent: React.FC<MyProps> = ({ children }) => <div>{children}</div>;
|
||
>
|
||
> // ✅ 推荐
|
||
> function MyComponent({ children }: MyProps) {
|
||
> return <div>{children}</div>;
|
||
> }
|
||
> ```
|
||
|
||
## 关联笔记
|
||
|
||
- [[hhs/REACT/README.md]]
|
||
- [[hhs/REACT/1. 基础篇/03-组件与 Props.md]]
|
||
- [[hhs/REACT/1. 基础篇/04-State 与不可变性.md]]
|
||
- [[hhs/REACT/3. 生态工具篇/08-路由管理.md]]
|
||
- [[hhs/REACT/3. 生态工具篇/09-状态管理.md]]
|