useStore 与 useStoreWithEqualityFn

相关源文件

• docs/apis/create-with-equality-fn.md
• docs/apis/create.md
• docs/hooks/use-store-with-equality-fn.md
• docs/hooks/use-store.md
• src/react.ts
• src/react/shallow.ts
• src/traditional.ts

目的

这些钩子将通用的 Zustand 存储（使用 createStore() 创建）连接到 React 组件，实现了框架无关的状态管理与 React 渲染系统之间的集成。虽然 useStore 提供了基本连接，但 useStoreWithEqualityFn 添加了自定义相等性检查以优化重新渲染。

对于直接使用 create() 创建的绑定到 React 的存储，请参阅 create。对于使用自定义相等性函数创建绑定到 React 的存储，请参阅 createWithEqualityFn。

Hook API 参考

useStore

useStoreWithEqualityFn

来源

• src/react.ts17-37
• src/traditional.ts23-47

实现细节

useStore 实现

useStore 钩子使用 React 的 useSyncExternalStore API 来订阅通用存储更新

useStoreWithEqualityFn 实现

useStoreWithEqualityFn 钩子使用 use-sync-external-store 包中的 useSyncExternalStoreWithSelector 来对重新渲染进行额外控制

来源

• src/react.ts26-37
• src/traditional.ts33-47

钩子之间的主要区别

功能	useStore	useStoreWithEqualityFn
包	zustand	zustand/traditional
依赖项	内置 React 钩子	需要 use-sync-external-store 包
重新渲染控制	默认相等性检查 (Object.is)	自定义相等性检查函数
实现	useSyncExternalStore	useSyncExternalStoreWithSelector
性能优化	基础	高级

Store 集成架构

通用到 React 的集成流程

重新渲染决策流程

来源

• src/react.ts17-37
• src/traditional.ts23-47

使用模式

基本 Store 连接

最简单的模式是将通用存储连接到 React 组件

带自定义相等性函数

使用 useStoreWithEqualityFn 和自定义相等性函数来优化渲染

来源

• docs/hooks/use-store.md47-169
• docs/hooks/use-store-with-equality-fn.md53-194

高级模式

动态 Store 创建

为不同的实体动态创建 Store

实现示例

来源

• docs/hooks/use-store.md171-393
• docs/hooks/use-store-with-equality-fn.md197-427

带有 Context 的作用域 Store

为每个组件树创建隔离的 Store 实例

实现示例

来源

• docs/hooks/use-store.md396-609
• docs/hooks/use-store-with-equality-fn.md430-645

性能优化技巧

1. 精确的 Selector

仅选择组件所需的部分

2. 自定义相等性函数

使用自定义相等性函数来防止不必要的重新渲染

3. Selector 记忆化

使用 useShallow 创建记忆化的 Selector

来源

• src/react/shallow.ts4-12
• docs/hooks/use-store-with-equality-fn.md20-50

常见问题排查

组件未重新渲染

问题：Store 状态改变时，组件未更新

可能的解决方案:

• 检查您是否正确使用了 selector
• 确保您没有直接修改状态
• 验证 Store 是否已使用 setState 正确更新

过多的重新渲染

问题：组件重新渲染过于频繁

解决方案：使用 useStoreWithEqualityFn 和 shallow 相等性函数

最佳实践

1. 使用 selectors 最小化重新渲染 - 只选择组件所需的特定状态
2. 对复杂状态使用相等性函数 - 为对象和数组应用自定义相等性检查
3. 按需动态创建 Store - 为参数化 Store 使用工厂模式
4. 考虑 Store 的作用域 - 使用 Context 为特定组件实例创建 Store
5. 分离读写访问 - 对读取状态和访问 actions 使用不同的 selectors

来源

• docs/hooks/use-store.md922-925
• docs/hooks/use-store-with-equality-fn.md961-962