Redux 核心 API

相关源文件

• docs/api/Store.md
• docs/api/applyMiddleware.md
• docs/api/bindActionCreators.md
• docs/api/combineReducers.md
• docs/api/compose.md
• docs/api/createStore.md
• docs/usage/migrations/migrating-rtk-2.md
• src/applyMiddleware.ts
• src/bindActionCreators.ts
• src/combineReducers.ts
• src/compose.ts
• src/createStore.ts
• src/index.ts
• src/types/middleware.ts
• src/types/reducers.ts
• src/types/store.ts
• test/helpers/actionTypes.ts
• test/typescript/reducers.test-d.ts
• tsconfig.base.json

本页面介绍了 Redux 库的核心 API 函数和概念。虽然 Redux Toolkit 现在是编写 Redux 逻辑的推荐方法（详情请参阅Redux Toolkit），但了解核心 API 能提供对 Redux 基本原理和操作的宝贵见解。

概述

Redux 核心 API 由几个关键函数组成，这些函数通过单向数据流模式实现可预测的状态管理。本文档涵盖了主要的 API 方法和概念：

• Store 的创建与管理
• Action 的分发与处理
• Reducer 的组合
• 中间件的集成
• 实用函数

来源: src/index.ts1-50 docs/api/createStore.md1-93 docs/api/Store.md1-147

Store

Redux store 是保存应用程序完整状态树的中心对象。它提供了一个小巧的 API 接口，包含几个与应用程序状态交互的关键方法。

Store 创建

Store 是使用 createStore 函数创建的，但现在推荐使用 Redux Toolkit 的 configureStore。

来源: docs/api/createStore.md1-64 src/createStore.ts1-100

Store 方法

store 对象提供了四个关键方法：

1. getState() - 返回应用程序当前的状态树
2. dispatch(action) - 分发一个 action 以触发状态改变
3. subscribe(listener) - 注册一个回调函数，在状态改变时被调用
4. replaceReducer(nextReducer) - 替换当前 store 用来计算状态的 reducer（用于代码分割）

来源: docs/api/Store.md16-147 src/types/store.ts81-165

getState()

返回应用程序当前的状态树。它反映了 store 的 reducer 返回的最新值。

来源: docs/api/Store.md18-26 src/createStore.ts176-186

dispatch(action)

向 store 分发一个 action，触发状态更新过程。这是 Redux 中触发状态改变的唯一方式。

action 必须是一个包含 type 属性的普通对象。从 Redux 5.0 开始，type 必须是字符串。

来源: docs/api/Store.md31-78 src/createStore.ts280-319

subscribe(listener)

添加一个变更监听器，每当 action 被分发且状态可能已改变时，该监听器将被调用。

来源: docs/api/Store.md84-132 src/createStore.ts211-253

replaceReducer(nextReducer)

替换当前 store 用于计算状态的 reducer。这主要用于代码分割和热模块替换。

来源: docs/api/Store.md138-147 src/createStore.ts330-346

Action 分发和 Reducer

Redux 遵循单向数据流，状态变化由分发 action 触发，这些 action 经由 reducer 处理以产生新的状态。

来源: docs/api/Store.md7-14 src/createStore.ts255-319

Reducer

Reducer 是一个纯函数，它接收当前状态和一个 action，并返回下一个状态。Reducer 必须：

1. 对无法识别的 action 返回当前状态
2. 永不返回 undefined
3. 无副作用
4. 不修改其参数

来源: src/types/reducers.ts1-34 docs/api/combineReducers.md77-85

实用函数

核心 API 包含几个简化 Redux 使用的实用函数。

combineReducers

combineReducers 函数将一个 reducer 函数对象转换为一个单一的 reducer 函数。这使得可以按状态领域拆分 reducer 逻辑。

来源: docs/api/combineReducers.md1-161 src/combineReducers.ts1-201

主要功能

• 按 reducer 键为状态划分命名空间
• 处理初始状态生成
• 强制执行 reducer 规则（例如，不允许返回 undefined）
• 通过仅更新状态中改变的部分进行优化

来源: docs/api/combineReducers.md36-52 src/combineReducers.ts96-113

applyMiddleware

applyMiddleware 函数是一个 store 增强器，允许你拦截和修改分发的 action。这是用自定义功能扩展 Redux 的推荐方式。

来源: docs/api/applyMiddleware.md1-232 src/applyMiddleware.ts1-77

中间件结构

每个中间件接收 getState 和 dispatch 函数，并返回一个接收 next 中间件的函数。该函数又返回一个接收 action 并决定是传递、转换还是生成新 action 的函数。

来源: src/types/middleware.ts1-30 docs/api/applyMiddleware.md14-30

常见用例

• 异步 action（thunk、promise）
• 记录 action 和状态
• 崩溃报告
• 路由
• API 调用

来源: docs/api/applyMiddleware.md22-24 docs/api/applyMiddleware.md70-202

bindActionCreators

bindActionCreators 函数将一个 action 创建器函数对象转换为一个具有相同键的对象，但每个函数都被包装在一个 dispatch 调用中。

来源: docs/api/bindActionCreators.md1-113 src/bindActionCreators.ts1-83

用途

这主要用于将 action 创建器传递给不了解 Redux 但需要分发 action 的组件时。

来源: docs/api/bindActionCreators.md17-19 docs/api/bindActionCreators.md76-110

compose

compose 函数是一个实用工具，它将多个函数从右到左组合起来。它用于将多个 store 增强器组合成一个。

来源: docs/api/compose.md1-52 src/compose.ts1-61

用途

来源: docs/api/compose.md33-47

Redux 数据流

Redux 实现严格的单向数据流，使状态变化可预测且可追踪。

来源: docs/api/Store.md7-14 src/createStore.ts255-319

完整数据流过程

1. UI 中的事件触发一个 action
2. action 被分发到 Redux store
3. store 将 action 通过任何中间件转发
4. 中间件可以转换 action 或执行副作用
5. 根 reducer 处理 action 并返回新状态
6. store 更新其内部状态树
7. store 通知所有已订阅的监听器
8. 连接到 store 的 UI 组件使用新状态重新渲染

来源: docs/api/Store.md7-14 src/createStore.ts255-319

已弃用功能和迁移说明

Redux 核心 API 仍在运行，但已弃用，转而推荐使用 Redux Toolkit 更易于开发者使用的 API。

• createStore 已弃用，推荐使用 RTK 的 configureStore。
• 使用 RTK 的 createSlice 可以更轻松地直接组合 reducer。
• 手动定义 action 创建器已被 createSlice 和 createAction 取代。
• 中间件设置在 configureStore 中自动化。

来源: docs/api/createStore.md15-26 docs/usage/migrations/migrating-rtk-2.md27-92

TypeScript 集成

Redux 核心包含其所有 API 的完整 TypeScript 定义。

API 元素	主要 TypeScript 接口
Store	Store<S, A>, Dispatch<A>
Reducer	Reducer<S, A>, ReducersMapObject<S, A>
操作	Action, UnknownAction
中间件	Middleware, MiddlewareAPI
增强器	StoreEnhancer, StoreCreator

来源: src/types/store.ts27-232 src/types/reducers.ts1-114 src/types/middleware.ts1-30

现代 Redux 用法说明

尽管本文档涵盖了 Redux 核心 API，但现代 Redux 应用程序应使用 Redux Toolkit (RTK)，它提供了：

• 使用良好默认值简化 store 设置
• 减少 action 和 reducer 的样板代码
• 内置的不可变更新逻辑
• 集成的异步 action 处理
• 默认集成 DevTools

有关使用 RTK 的详细信息，请参阅 Redux Toolkit 页面。

来源: docs/api/createStore.md15-26 docs/api/applyMiddleware.md16-20 docs/api/combineReducers.md18-32