# 深入 React Todos：从零实现一个状态提升与本地持久化的待办应用

引言

在日常开发中，Todo 应用是学习前端框架的“Hello World”级案例，它浓缩了组件化开发的核心模式：状态管理、父子通信、兄弟组件协作、受控组件以及副作用处理。今天我们将基于一个使用 React + Vite + Stylus 构建的 Todo 项目，逐行解析其源码，并总结出可复用的最佳实践。文章会覆盖入口文件、根组件与三个功能组件，最后用表格对比不同组件的职责与数据流向，帮助大家真正掌握 React 的组件化思维。 完整项目链接：gitee.com/hong-strong…

项目总览：组件树与数据流

整个应用由四个组件构成：

App (根组件)
 ├─ TodoInput   (输入添加)
 ├─ TodoList    (列表展示与操作)
 └─ TodoStats   (统计与批量清除)

数据流原则：

1. 状态提升：共享状态 todos 存储在顶层组件 App 中，并通过 props 向下传递给子组件。
2. 子→父通信：子组件无法直接修改 todos，而是通过父组件传递的回调函数（如 onAdd、onDelete）来“上报”修改意图，由父组件执行状态更新。
3. 兄弟组件通信：TodoInput、TodoList、TodoStats 之间没有直接联系，它们都通过与同一个父组件 App 交互实现间接通信。任何操作引发的状态变化都会自动反映到所有相关组件中。

这种模式保证了单一数据源和可预测的状态更新，是 React 哲学的基石。

入口文件 main.jsx：React 18 的渲染方式

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

逐行解读：

• StrictMode：React 的严格模式，仅在开发环境下生效。它会对组件进行额外的检查，例如检测不安全的生命周期、过时的 API 以及意外的副作用。包裹 <App /> 有助于我们在开发阶段提前发现问题。
• createRoot：React 18 引入的新 API，替代了旧版的 ReactDOM.render。它启用并发特性，为后续使用 Suspense、Transitions 等打下基础。
• document.getElementById('root')：挂载点，对应 index.html 中的 div#root。
• .render(...)：将 React 元素树渲染到真实 DOM 中。整个应用从这里启动。

tips：StrictMode 会让组件函数体、初始化函数等执行两次，所以在开发时会发现 useEffect 运行两次，这是刻意设计的，用于暴露副作用问题。

核心：App.jsx —— 状态管理与业务逻辑

根组件是整个应用的“大脑”，负责持有状态、定义修改方法、计算派生数据，以及处理副作用。

import { useState, useEffect } from 'react'
import './styles/app.styl'
import TodoList from './components/TodoList'
import TodoInput from './components/TodoInput'
import TodoStats from './components/TodoStats'

function App() {
  // 1. 状态初始化
  const [todos, setTodos] = useState(() => {
    const saved = localStorage.getItem('todos');
    return saved ? JSON.parse(saved) : [];
  })
  // ...
}

4.1 状态初始化：惰性读取 localStorage

useState 传入了一个函数，而不是直接传值。这是 惰性初始化（Lazy Initial State）：该函数只在组件首次渲染时执行一次。如果直接传值，比如 useState(JSON.parse(localStorage.getItem('todos')) || [])，每次渲染都会执行 localStorage.getItem 和 JSON.parse，即使其结果已被忽略，造成不必要的性能开销。惰性初始化避免了重复读取，是应对从外部存储恢复状态的标准写法。

当本地存储中没有 todos 时返回空数组 []，否则解析出已有的待办列表。这样用户刷新页面后数据不会丢失。

4.2 操作方法：不可变更新

所有修改方法都遵循 不可变数据（Immutable） 原则，不直接修改原数组，而是返回一个新数组：

const addTodo = (text) => {
  setTodos([...todos, {
    id: Date.now(),
    text,
    completed: false,
  }])
}

• 使用展开运算符 ...todos 创建新数组，再附加一个新对象。id 用时间戳生成，保证唯一性；completed 初始为 false。
• 优点：React 通过引用比较来判断状态是否变化，不可变更新确保每次调用都会触发重新渲染。

const deleteTodo = (id) => {
  setTodos(todos.filter(todo => todo.id !== id))
}

• filter 返回一个新数组，剔除指定 id 的项，实现删除。

const toggleTodo = (id) => {
  setTodos(todos.map(todo => todo.id === id ? {
    ...todo,
    completed: !todo.completed,
  } : todo))
}

• map 遍历数组，找到匹配 id 的 todo，用对象展开 ...todo 复制其余属性，并翻转 completed 状态。未匹配的项原样返回。

const clearCompleted = () => {
  setTodos(todos.filter(todo => !todo.completed))
}

• 清除所有已完成项，同样通过 filter 返回新数组。

4.3 派生状态与副作用

const activeCount = todos.filter(todo => !todo.completed).length;
const completedCount = todos.filter(todo => todo.completed).length;

• 这两个变量并非 state，而是派生状态（Derived State）：它们完全由 todos 计算得出，无需额外维护。每当 todos 变化，函数组件重新执行，这两个值会自动更新。这避免了数据冗余和同步问题。

useEffect(() => {
  localStorage.setItem('todos', JSON.stringify(todos));
}, [todos])

• 副作用处理：当 todos 变化时，将其序列化后存入 localStorage。依赖数组 [todos] 保证仅在 todos 引用改变时执行，避免无限循环。注意：useEffect 会在 DOM 更新后异步执行，不会阻塞渲染，因此不会影响交互流畅度。

4.4 组合视图

return (
  <div className="todo-app">
    <h1>My Todo List</h1>
    <TodoInput onAdd={addTodo}/>
    <TodoList 
      todos={todos} 
      onDelete={deleteTodo}
      onToggle={toggleTodo}
    />
    <TodoStats 
      total={todos.length}
      active={activeCount}
      completed={completedCount}
      onClearCompleted={clearCompleted}
    />
  </div>
)

• 通过 props 向子组件传递数据（todos、total 等）和修改方法（onAdd、onDelete 等）。这些修改方法就是“自定义事件”，子组件调用时相当于向父组件发送了操作请求。
• 这种设计保持了组件的纯净性：子组件只负责 UI 和触发行为，不关心状态如何存储与变更，实现了高内聚低耦合。

子组件解析

5.1 TodoInput：受控组件与表单提交

import { useState } from 'react'
const TodoInput = (props) => {
  const { onAdd } = props;
  const [inputValue, setInputValue] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    onAdd(inputValue);
    setInputValue('');
  }

  return (
    <form className="todo-input" onSubmit={handleSubmit}>
      <input 
        type="text"
        value={inputValue}
        onChange={e => setInputValue(e.target.value)}
      />
      <button type="submit">Add</button>
    </form>
  )
}

逐行解析：

• const [inputValue, setInputValue] = useState('')：自有状态，管理输入框的文字。这里采用受控组件（Controlled Component） 模式：value 由 React 状态决定，onChange 更新状态，输入框的视图始终与状态同步。相对于 Vue 的 v-model 双向绑定，React 通过“值 + onChange”的组合实现单向数据流，性能与可预测性更好。
• handleSubmit：阻止表单默认提交行为（避免页面刷新），调用父组件传入的 onAdd 回调，将当前文本传递给 App 进行添加，然后清空输入框。清空动作由本地 setInputValue 完成，体现了局部状态的自治。
• 子→父通信：onAdd(inputValue) 就是子组件向父组件传递数据的唯一途径。

5.2 TodoList：列表渲染与条件样式

const TodoList = (props) => {
  const { todos, onDelete, onToggle } = props;

  return (
    <ul className="todo-list">
      {todos.length === 0 ? (
        <li className="empty">No todos yet!</li>
      ) : (
        todos.map(todo => (
          <li 
            key={todo.id} 
            className={todo.completed ? 'completed' : ''}
          >
            <label>
              <input 
                type="checkbox" 
                checked={todo.completed}
                onChange={() => onToggle(todo.id)}
              />
              <span>{todo.text}</span>
            </label>
            <button onClick={() => onDelete(todo.id)}>X</button>
          </li>
        ))
      )}
    </ul>
  )
}

逐行解析：

• 从 props 解构出 todos（数据）、onDelete、onToggle（操作回调）。
• 条件渲染：当 todos.length === 0 时显示空状态提示，否则渲染列表。空状态处理提升了用户体验。
• 列表渲染：用 map 遍历 todos，给每个 <li> 设置唯一 key（这里使用 todo.id），这是 React 虚拟 DOM Diff 算法优化重排的基础。
• className={todo.completed ? 'completed' : ''} 动态绑定样式，通过样式类名展示完成/未完成状态。
• 复选框：使用受控组件模式，checked={todo.completed} 由父组件状态决定，onChange 触发 onToggle(todo.id) 通知父组件切换完成状态。注意这里没有在子组件内修改 todo.completed，完全遵循单一数据流。
• 删除按钮：onClick={() => onDelete(todo.id)}，同样通过回调将删除意图上报给父组件。

5.3 TodoStats：统计展示与批量操作

const TodoStats = (props) => {
  const { total, active, completed, onClearCompleted } = props;

  return (
    <div className="todo-stats">
      <p>Total: {total} | Active: {active} | Completed: {completed}</p>
      {completed > 0 && (
        <button 
          onClick={onClearCompleted}
          className="clear-btn"
        >Clear Completed</button>
      )}
    </div>
  )
}

逐行解析：

• 接收四个 props：total、active、completed 三个统计数据，以及 onClearCompleted 回调。这些数据完全来自父组件计算的派生状态，体现了数据流自上而下。
• 展示统计信息，用管道符分隔，简洁明了。
• {completed > 0 && (...)}：短路逻辑实现条件渲染，仅当已完成数量大于 0 时才显示“Clear Completed”按钮。避免无意义操作，UI 更清爽。
• 点击按钮触发 onClearCompleted，无参数，父组件据此清除所有已完成项。

数据流总结与表格分析

整个应用严格遵循 单向数据流，形成了清晰的数据生命周期：

用户操作 → 子组件调用 props 回调 → 父组件更新 state → React 重新渲染
→ 子组件接收新 props → 视图更新

同时，通过 useEffect 将状态持久化到 localStorage，实现了 数据刷新不丢失。

下面用一张表格总结各组件的职责与通信方式：

组件	职责	接收的 Props	自有 State	触发的回调（子→父）
App	持有全局状态、定义修改逻辑、持久化	无	todos	无（它是顶层）
TodoInput	输入新待办，提交添加	onAdd	inputValue	onAdd(text)
TodoList	展示待办列表，提供完成/删除交互	todos, onToggle, onDelete	无	onToggle(id), onDelete(id)
TodoStats	显示统计信息，提供批量清除入口	total, active, completed, onClearCompleted	无	onClearCompleted()

关键设计要点：

• 状态提升：todos 是唯一数据源，放在公共祖先 App 中，避免多组件状态不一致。
• 兄弟组件解耦：TodoInput 添加事项后，无需直接通知 TodoList 或 TodoStats；只因 todos 变化，这些组件通过接收新 props 自动更新。
• 不可变更新：所有状态更新都使用新数组，保证 React 能够正确检测变化并触发渲染。
• 受控组件：TodoInput 的文本输入与 TodoList 的复选框都受 React 状态控制，杜绝 DOM 直接操作。
• 惰性初始化与副作用：useState 的函数初始器避免重复读取存储，useEffect 负责同步外部系统。

一些总结

1. 性能优化：如果 todos 数量很大，可以在 TodoList 中使用 React.memo 包裹，避免无关 props 变化导致的重渲染。另外，可以用 useCallback 包裹回调函数，防止因函数引用变化导致子组件不必要的更新。

2. 唯一 ID 生成：当前使用 Date.now() 在高并发快速添加时可能产生重复。在生产环境中可以改用 crypto.randomUUID() 或成熟库（如 nanoid）。

3. 类型安全：加入 TypeScript，为 todos 和 props 定义接口，能大幅减少拼写错误并提升可维护性。

4. 状态管理扩展：若应用规模扩大，可以考虑使用 useReducer 重构 App 的状态逻辑，将操作集中在 reducer 中，更便于测试和跟踪状态变化；或者引入 Context API 避免深层 props 传递（prop drilling），但小型 Todo 应用目前的模式已足够清晰。

5. 自定义 Hook：可以将 useState + useEffect 的持久化逻辑封装成 useLocalStorageState 自定义 Hook，提高复用性。

结语

通过这个 React Todo 应用，我们深入剖析了 组件化设计、状态提升、单向数据流、受控组件以及本地持久化 的核心实践。源码虽然精简，却覆盖了 React 开发中绝大部分的思维范式。掌握这些模式后，无论是构建表单系统、管理后台还是复杂交互页面，都能游刃有余。

---