登录
从零开始用 TypeScript + React 打造类型安全的 Todo 应用
2026年3月6日 19:34
从零开始用 TypeScript + React 打造类型安全的 Todo 应用
引言：为什么选择 TypeScript + React？
React 作为当下最流行的前端库，以其组件化和声明式开发著称。而 TypeScript 作为 JavaScript 的超集，带来了静态类型检查和强大的 IDE 支持。两者结合，堪称黄金搭档。
在纯 JavaScript 的 React 项目中，我们常常遇到：
- 组件 props 类型不确定，传错属性难以及时发现；
- 状态更新时，不小心修改了不该改的数据；
- 调用自定义 Hook 返回的方法时，参数类型模糊不清。
TypeScript 可以完美解决这些问题。它让你在编写代码时就能发现错误，并且提供精准的代码补全和文档提示。今天我们就通过一个经典的 Todo 应用，来体验 TypeScript 在 React 项目中的魅力。
一、项目初始化
首先创建一个 React + TypeScript 项目（使用 Create React App）：
npx create-react-app todo-ts --template typescript
cd todo-ts
项目结构我们会按照功能模块组织：
src/
├── components/
│ ├── TodoInput.tsx
│ ├── TodoItem.tsx
│ └── TodoList.tsx
├── hooks/
│ └── useTodos.ts
├── types/
│ └── todo.ts
├── utils/
│ └── storages.ts
└── App.tsx
二、定义核心类型：Todo 接口
数据是整个应用的核心，TypeScript 通过接口（interface） 来约束数据的形状。
src/types/todo.ts：
export interface Todo {
id: number; // 唯一标识
title: string; // 标题
completed: boolean; // 是否完成
}
这个接口将被多个组件和 Hook 使用，确保整个应用中 Todo 的数据结构始终一致。
三、封装 localStorage 工具函数（泛型实战）
为了方便存取数据，我们封装两个工具函数，并利用 TypeScript 的泛型让它们支持任意类型。
src/utils/storages.ts：
export function getStorage<T>(key: string, defaultValue: T): T {
const value = localStorage.getItem(key);
return value ? JSON.parse(value) : defaultValue;
}
export function setStorage<T>(key: string, value: T): void {
localStorage.setItem(key, JSON.stringify(value));
}
泛型 <T> 的作用：
-
getStorage的返回值类型与defaultValue类型一致，调用时可以明确知道返回的是什么类型。 -
setStorage的value参数类型为T，确保存入的数据类型与取出时的预期相符。
例如，当我们存储 Todo 数组时，可以这样调用：
const todos = getStorage<Todo[]>('todos', []);
setStorage<Todo[]>('todos', todos);
如果传入了错误类型，TypeScript 会立即报错。
四、自定义 Hook：useTodos（核心业务逻辑）
useTodos 负责管理待办事项的状态，并与 localStorage 同步。我们看看 TypeScript 如何让这个 Hook 变得健壮。
src/hooks/useTodos.ts：
import { useState, useEffect } from 'react';
import type { Todo } from '../types/todo';
import { getStorage, setStorage } from '../utils/storages';
const STORAGE_KEY = 'todos';
export default function useTodos() {
// 1. 初始化状态，使用泛型指定状态类型，并懒加载从 localStorage 读取数据
const [todos, setTodos] = useState<Todo[]>(() =>
getStorage<Todo[]>(STORAGE_KEY, [])
);
// 2. 自动同步到 localStorage
useEffect(() => {
setStorage<Todo[]>(STORAGE_KEY, todos);
}, [todos]);
// 3. 添加待办
const addTodo = (title: string) => {
const newTodo: Todo = {
id: +new Date(), // 使用时间戳作为简单 ID
title,
completed: false,
};
setTodos([...todos, newTodo]);
};
// 4. 切换完成状态
const toggleTodo = (id: number) => {
const newTodos = todos.map(todo =>
todo.id === id ? { ...todo, completed: !todo.completed } : todo
);
setTodos(newTodos);
};
// 5. 删除待办
const removeTodo = (id: number) => {
const newTodos = todos.filter(todo => todo.id !== id);
setTodos(newTodos);
};
return {
todos,
addTodo,
toggleTodo,
removeTodo,
};
}
关键点解析
-
useState<Todo[]>：明确状态类型，后续setTodos只能传入Todo[]类型数据。 -
懒初始化函数：
() => getStorage<Todo[]>(...)确保 localStorage 读取只在首次渲染时执行。 -
useEffect依赖[todos]：每当todos变化，自动调用setStorage同步到本地。 -
操作方法参数类型：
addTodo接收string，toggleTodo和removeTodo接收number，杜绝传错参数的可能。 - 返回对象：TypeScript 会自动推断返回值的类型，在组件中使用时能得到完整的类型提示。
五、编写 React 组件
1. TodoInput：受控输入框
src/components/TodoInput.tsx：
import * as React from 'react';
interface Props {
onAdd: (title: string) => void; // 回调函数类型
}
const TodoInput: React.FC<Props> = ({ onAdd }) => {
const [value, setValue] = React.useState<string>('');
const handleAdd = () => {
if (!value.trim()) return; // 忽略空输入
onAdd(value.trim());
setValue(''); // 清空输入框
};
return (
<div>
<input
value={value}
onChange={e => setValue(e.target.value)}
/>
<button onClick={handleAdd}>添加</button>
</div>
);
};
export default TodoInput;
TypeScript 亮点：
-
React.FC<Props>定义了函数组件的 props 类型。 -
onAdd的类型是(title: string) => void，确保调用时传入正确的参数。 -
useState<string>显式声明状态类型（虽然可以推导，但写上更清晰）。
2. TodoItem：单个待办项
src/components/TodoItem.tsx：
import type { Todo } from '../types/todo';
import * as React from 'react';
interface Props {
todo: Todo;
onToggle: (id: number) => void;
onRemove: (id: number) => void;
}
const TodoItem: React.FC<Props> = ({ todo, onToggle, onRemove }) => {
return (
<li>
<input
type="checkbox"
checked={todo.completed}
onChange={() => onToggle(todo.id)}
/>
<span style={{ textDecoration: todo.completed ? 'line-through' : 'none' }}>
{todo.title}
</span>
<button onClick={() => onRemove(todo.id)}>删除</button>
</li>
);
};
export default TodoItem;
TypeScript 亮点：
-
todo: Todo明确传入的对象符合Todo接口。 -
onToggle和onRemove的参数类型明确为number，使用todo.id时类型匹配。
3. TodoList：渲染列表
src/components/TodoList.tsx：
import type { Todo } from '../types/todo';
import TodoItem from './TodoItem';
import * as React from 'react';
interface Props {
todos: Todo[];
onToggle: (id: number) => void;
onRemove: (id: number) => void;
}
const TodoList: React.FC<Props> = ({ todos, onToggle, onRemove }) => {
return (
<ul>
{todos.map(todo => (
<TodoItem
key={todo.id}
todo={todo}
onToggle={onToggle}
onRemove={onRemove}
/>
))}
</ul>
);
};
export default TodoList;
TypeScript 亮点：
-
todos: Todo[]明确数组元素类型。 - 在
map循环中，todo自动推导为Todo类型。
六、组合应用：App 组件
src/App.tsx：
import useTodos from './hooks/useTodos';
import TodoList from './components/TodoList';
import TodoInput from './components/TodoInput';
export default function App() {
const { todos, addTodo, toggleTodo, removeTodo } = useTodos();
return (
<div>
<h1>TodoList</h1>
<TodoInput onAdd={addTodo} />
<TodoList
todos={todos}
onToggle={toggleTodo}
onRemove={removeTodo}
/>
</div>
);
}
在 App 中，我们从 useTodos 获取状态和方法，然后直接传递给子组件。由于所有类型都已定义，这里传参时完全类型安全，如果 addTodo 需要传入 number 类型，TypeScript 会立刻报错。
七、TypeScript 带来的好处总结
通过这个简单的 Todo 应用，我们可以看到 TypeScript 在 React 项目中的实际价值：
-
接口即文档：
Todo、Props等接口清晰地描述了数据结构，新成员加入项目能快速理解。 -
类型安全的状态管理：
useState<Todo[]>确保状态始终符合预期，不会意外混入错误数据。 -
精确的事件处理：
onToggle={(id: number) => ...}让调用方明确知道需要传递什么参数。 -
自动补全与重构：在 VS Code 中，输入
todo.会立刻弹出id、title、completed提示；修改接口字段后，所有用到的地方都会报错，重构零风险。 - 减少运行时错误：很多低级错误（如传错参数类型、访问不存在的属性）在编译阶段就被捕获。
八、扩展思考
这个 Todo 应用虽然简单，但已经涵盖了 TypeScript + React 的核心实践。在此基础上，你可以继续探索：
- 更高级的泛型：比如封装通用的请求函数，使用泛型约束返回数据类型。
-
类型工具：
Partial、Pick、Omit等工具类型，用于灵活地处理类型变换。 - Redux Toolkit + TypeScript：大型状态管理中的类型安全。
- 类型定义文件（.d.ts）：为第三方无类型库编写声明。
结语
TypeScript 并不是一个陌生的新语言，它只是为 JavaScript 添加了一层“安全网”。在 React 项目中使用 TypeScript，初期可能会觉得有些繁琐，但一旦你习惯了类型带来的自信和效率，就很难再回到纯 JavaScript 的开发方式。
希望这篇文章能帮助你迈出 TypeScript + React 的第一步。如果你有任何问题或想法，欢迎在评论区留言交流！
效果图
参考资料：TypeScript 官方文档 | React 官方类型定义
