React-RxJS 核心API速查：state()、useStateObservable 与 connectObservable 一个都不少

React-RxJS 核心API速查：state()、useStateObservable 与 connectObservable 一个都不少

【免费下载链接】react-rxjsReact bindings for RxJS项目地址: https://gitcode.com/gh_mirrors/rea/react-rxjs

React-RxJS 是 RxJS 与 React 之间的响应式绑定库（React bindings for RxJS），帮你用最少代码把流式数据接入组件，且零内存泄漏、原生支持 React Suspense。本文是一份面向新手的 React-RxJS 核心 API 速查指南：state()、useStateObservable、connectObservable一个都不少，并附上bind、Subscribe、shareLatest的用法与选型决策表。

一、先搞懂：React-RxJS 解决什么问题？

在 React 里直接使用 RxJS，通常需要手动处理三件事：订阅、取消订阅、共享最新值。稍不注意就会出现内存泄漏或重复订阅。

React-RxJS 把这三件事全部自动化：

• ⚡自动订阅/取消订阅：组件挂载时订阅、卸载时自动清理，无需手写useEffect
• 🔁自动共享最新值：多个组件订阅同一个流时，底层只保留一份订阅（引用计数归零即关闭）
• 😴一等公民支持 Suspense：异步流未发出第一个值时，组件可以自动挂起等待
• 📦小而可 tree-shake：按需引入 API，体积友好

项目是一个 monorepo，包含三个包：@react-rxjs/core（核心绑定）、@react-rxjs/dom（DOM 批量更新优化）、@react-rxjs/utils（信号与监听器工具）。

二、30 秒安装：一键上手 React-RxJS

npm install @react-rxjs/core

如果你想阅读源码，可以克隆仓库：

git clone https://gitcode.com/gh_mirrors/rea/react-rxjs

三、核心 API 速查总表

API	一句话作用	典型场景
state()	把 Observable 包装成可复用、可组合的"状态对象"	定义全局共享流、参数化流
useStateObservable()	React Hook：订阅状态并取回最新值	组件内读取流式数据
connectObservable()	一次性绑定固定 Observable，返回[Hook, 共享流]	组件快速接入现成的流
connectFactoryObservable()	绑定"返回 Observable 的工厂函数"，按参数隔离订阅	按用户 ID 等参数动态取数
bind()	统一入口，自动路由到上面两种 connect	日常开发首选入口
Subscribe	组件：管理订阅生命周期 + Suspense 边界	包裹组件树，杜绝手动退订
shareLatest()	可组合操作符：共享并回放最新值	手动共享流的最新值

速记口诀：state造状态，useStateObservable读状态，connectObservable快速绑定现成流。

四、state()：创建可复用、可组合的状态对象

state()是 React-RxJS 的"状态工厂"。它接受一个 Observable（或返回 Observable 的工厂函数），返回一个StateObservable——一个既能被订阅、又能被多个组件共享的状态对象。

import { state } from "@react-rxjs/core"; import { filter } from "rxjs"; const todos$ = state(fetchTodos$); // 固定流 const activeTodos$ = todos$.pipeState(filter(t => t.active)); // 派生状态 const user$ = state((id: string) => fetchUser$(id)); // 参数化工厂

三个要点：

1. 派生状态：用pipeState()链式创建派生流，派生流同样共享底层订阅
2. 参数化流：传入工厂函数后，user$("42")会为不同参数分别维护订阅
3. JSX 友好：在 React 构建中，StateObservable可以直接作为 JSX 元素渲染（实现见packages/core/src/stateJsx.tsx）

📁 源码位置：packages/core/src/stateJsx.tsx

五、useStateObservable()：组件里订阅状态的唯一入口

拿到StateObservable后，在组件里用它读取最新值：

function Counter() { const count = useStateObservable(count$); // 最新值，自动订阅 return <span>{count}</span>; }

它底层基于useSyncExternalStore实现，天然适配 React 并发模式；流尚未发出第一个值时，Hook 会通过Suspense挂起组件（抛出 Promise 等待）。因此异步流要包在<Suspense>边界里，或给state()提供默认值。

📁 源码位置：packages/core/src/useStateObservable.ts

六、connectObservable()：把现成 Observable 快速绑进组件

如果你已经有一个现成的 Observable（比如一个定时器或事件流），connectObservable一行就能接入 React：

const [useClick$, click$] = connectObservable(fromEvent(document, "click")); // 带默认值：避免 Suspense 等待 const [useTodo$, todo$] = connectObservable(fetchTodo$("1"), { loading: true });

它返回一个元组：

• 第一个元素：React Hook，调用后得到流的最新值
• 第二个元素：sharedLatest版共享流，可用于pipeState派生其他流；最后一个订阅者消失时自动关闭

不传默认值时，若流没有同步发出值，Hook 会借助 Suspense 等待——这是 React-RxJS 的标志性行为。

📁 源码位置：packages/core/src/bind/connectObservable.ts

七、connectFactoryObservable() 与 bind()：参数化流怎么选？

当流需要按参数动态创建（如按用户 ID 拉数据），用connectFactoryObservable：

const [useUser$, user$] = connectFactoryObservable( (id: string) => api.get(`/users/${id}`), ); function Profile() { const user = useUser$("42"); // 不同 id 各自维护订阅 }

而bind()是日常开发的统一入口：传入 Observable 就等价于connectObservable，传入工厂函数就等价于connectFactoryObservable，两者完全自动路由，返回值结构也一致。

📁 源码位置：packages/core/src/bind/index.ts、packages/core/src/bind/connectFactoryObservable.ts

八、速查决策表：这个场景该用哪个 API？

你的场景	推荐 API
全局固定流（定时器、WebSocket）	state(observable)+useStateObservable
现成 Observable 想快速进组件	connectObservable
按 ID/参数动态取数	state((id) => obs)工厂或bind(factory)
从已有状态派生新状态	state$.pipeState(操作符)
避免手动管理订阅生命周期	<Subscribe>组件包裹组件树
手动共享流的最新值	shareLatest()操作符
需要 DOM 批量更新优化	@react-rxjs/dom的batchUpdates

九、三个新手最容易踩的坑 ⚠️

1. 忘记 Suspense 边界：异步流（订阅后异步才发值）必须包在<Suspense fallback={...}>中，或者提供defaultValue跳过等待。
2. 缺少订阅边界：组件树建议用<Subscribe>包裹（可选source$属性确保订阅先于渲染建立）。Subscribe会自动收集子组件订阅并在卸载时统一清理，见packages/core/src/Subscribe.tsx。
3. 错误处理：流抛出错误会沿 React 错误边界传播，请用 Error Boundary 捕获，而不是在业务代码里静默吞掉。

十、源码导读：去仓库哪里看实现？

文件	内容
packages/core/src/index.tsx	所有公开 API 的导出入口
packages/core/src/stateJsx.tsx	state()的 JSX 增强实现
packages/core/src/useStateObservable.ts	核心 Hook，基于useSyncExternalStore
packages/core/src/bind/connectObservable.ts	固定流绑定
packages/core/src/bind/connectFactoryObservable.ts	工厂流绑定
packages/core/src/Subscribe.tsx	订阅边界组件
packages/core/src/shareLatest.ts	共享最新值操作符
packages/dom/src/batchUpdates.ts	DOM 批量更新优化
packages/utils/src/createSignal.ts	信号工具

总结

React-RxJS 的核心其实只有三个记忆点：用state()或bind()创建/绑定状态流，用useStateObservable()在组件里读取最新值，用Subscribe管理生命周期。掌握这份速查表，你就能把 RxJS 的响应式能力干净利落地带入 React 项目——真正的响应式、无泄漏、对 Suspense 友好。

【免费下载链接】react-rxjsReact bindings for RxJS项目地址: https://gitcode.com/gh_mirrors/rea/react-rxjs