前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载导读useStore是 react-adminra-core提供的核心 Hook用于从全局 Store 中读取和写入用户偏好等状态。与useState几乎一致的 API、跨组件与跨标签页的自动同步以及基于 localStorage 的持久化能力使它成为保存 UI 偏好如界面语言、主题、列表密度、筛选条件的首选方案。本文以官方文档docs_headless/src/content/docs/useStore.md为骨架结合仓库源码完整讲解其语法、实现原理、配套 Hook 与最佳实践。useStore 是什么一个持久化的全局 useStateuseStore允许你从 react-admin 的 Store 中读取和写入数据。Store 是一个全局、同步、持久化的键值存储存储在其中的值全局可用并且在页面刷新后依然保留——这正是用户偏好preference类状态最需要的特性用户期望某些 UI 选择比如界面语言、主题、列表密度只需要设置一次。Store 就是存储这些偏好的最佳位置。它的 API 完全模仿 React 的useState一行代码即可接入import { useStore } from ra-core; const [value, setValue] useStore(key, defaultValue);从源码看useStore的实现也确认了这一点——useStore.ts 内部正是用useState承载当前值再通过 StoreContext 中的getItem/setItem/subscribe与全局 Store 对接。官方文档将其定位为 useState-like hook using the global Store for persistence。语法与核心规则key字符串键用点号命名空间key必须是字符串作为 localStorage 中存储的键名。官方推荐用点号.分隔做命名空间例如posts.list.density、posts.list.columns。作用域清晰点号前缀天然组织不同资源、不同页面的状态避免键名冲突可直接使用子键如preferences.ui.fontSize与preferences.ui.mode是两个独立键互不干扰。从 localStorageStore.ts 的实现可以看到实际写入 localStorage 的键是经过加工的前缀RaStore常量RA_STORE 可选的应用标识appKey 点号 你的 key最终形如RaStore.posts.list.density。值类型一切可 JSON 序列化的数据Store 可以存放任意类型的值——string、number、boolean、array、object——前提是它们能被JSON.stringify()序列化。函数、undefined、循环引用的对象等无法序列化的值不应存入。这一约束直接来自底层存储localStorageStore的setItem使用JSON.stringify(value)写入读取时用tryParse先尝试JSON.parse解析失败则回退返回原始字符串localStorageStore.ts。setValue值或更新函数setValue的行为与useState返回的 setter 完全一致支持两种调用方式// 直接传值 setValue(32); // 传值更新函数函数接收当前值返回新值 setValue(v v 1);useStore源码中对更新函数做了显式处理当参数是函数时会以当前value为入参调用它useStore.ts。测试用例useStore.spec.tsx也验证了这一行为——点击按钮执行setValue(current \${current} world)后界面值从hello变为hello world。一个有趣的细节setValue(undefined) 会回退到默认值在useStore内部当传入undefined且提供了runtimeDefaultValue时会使用运行时默认值否则回退到 hook 声明时的defaultValue。这意味着你可以在调用点动态覆盖默认值setValue(undefined, fallback);跨组件与跨标签页同步useStore最强大的特性是响应式同步当某个组件对某个 key 调用setValue时所有读取同一 key 的组件都会重新渲染这一同步甚至跨越浏览器标签页——在其他标签页中运行的 react-admin 实例也会同步更新。实现原理分两层同应用内的订阅发布localStorageStore维护一个subscriptions注册表publish会通知所有订阅了该 key 的组件localStorageStore.tsuseStore在挂载时通过subscribe(key, callback)订阅卸载时取消订阅useStore.ts。测试useStore.spec.tsx验证了「更新同一 key 的所有组件」以及「不同 key 的组件不受影响」两个行为。跨标签页同步localStorageStore监听浏览器的storage事件——这是浏览器在 localStorage 被其他文档修改时触发的事件。事件处理器会过滤出带 Store 前缀的变更并只通知订阅了对应 key 的组件localStorageStore.ts。一个值得注意的边界行为当 key 被删除时浏览器storage事件的newValue为null此时实现会回调undefined而不是null从而让订阅方正确回退到默认值。实战示例列表密度切换官方文档给出了一个完整的实战场景列表密度density偏好。PostList读取密度值决定内边距应用其他位置的按钮写入密度值——点击按钮即可触发PostList重新渲染import { ListBase } from ra-core; const PostList () { const [density] useStore(posts.list.density, small); return ( ListBase div style{{ padding: density small ? 0.5em : 1em }} ... /div /ListBase ); } // anywhere else in the app import { useStore } from ra-core; const ChangeDensity () { const [density, setDensity] useStore(posts.list.density, small); // Clicking on this button will trigger a rerender of the PostList const changeDensity () { setDensity(density small ? medium : small); }; return ( button onClick{changeDensity} Change density (current {density}) /button ); };这个例子展示了 useStore 的两个典型用法读PostList只需const [density] useStore(...)即可获得持久化的偏好值无需关心它存储在哪里写ChangeDensity用同一 key 调用setValue两处组件自动联动。同样的模式也适用于显示/隐藏帮助面板——官方 Store 文档 中的HelpButton示例就用useStore(help.open, false)配合setHelpOpen(v !v)实现开关。底层实现Store 的适配器架构要真正理解useStore需要了解它背后依赖的 Store 架构。react-admin 的 Store 采用适配器模式允许开发者把状态存在内存、localStorage甚至同步到 API。Store 依赖 React state 和更新事件update events把变更广播给所有订阅该状态的组件。核心接口Storetype包含方法说明setup()初始化如注册storage事件监听teardown()清理如移除监听getItem(key, defaultValue)读取键值setItem(key, value)写入键值undefined时删除removeItem(key)删除单键removeItems(keyPrefix)按前缀批量删除reset()清空 Storesubscribe(key, callback)订阅键变更返回退订函数listItems(keyPrefix?)列出键值对useStore通过useStoreContext()获取 StoreContext 中的 Store 实例useStoreContext.ts然后调用getItem初始化状态、subscribe订阅变更、setItem写入变更——全部是同步操作。为什么必须同步Store 文档给出了明确的设计动机如果改用 react-query 这类异步方案保存列表状态会出现两次数据请求的竞态——列表控制器先以默认排序请求数据异步拿到已保存的排序后再请求一次。而同步 Store 让列表控制器在发起请求前就能拿到已保存的排序全程只请求一次。这是 react-admin 自行实现 Store 而非使用 Redux、Zustand、Jotai 等外部状态库的核心原因。配套 Hook 全家桶useStore是 Store 系列的入口但 ra-core 还提供了其他几个配套 Hook均导出自 index.tsHook作用useStore(key, defaultValue)读写单个键useStoreContext()获取 StoreContext 中的 Store 实例高级用法useRemoveFromStore(key)从 Store 中移除指定键useRemoveItemsFromStore(keyPrefix)按前缀移除多个键useResetStore()重置 Store 到初始状态面向业务的专用 Hookreact-admin 内部组件并不直接调用useStore而是使用领域专用 Hook从而避免在业务代码中硬编码 store keyuseLocaleState()—— 界面语言localeuseUnselect()/useUnselectAll()/useRecordSelection()—— 资源的选中记录useExpanded()—— 数据表格中展开的行以useLocaleState为例它内部就是基于useStore实现的见packages/ra-core/src/controller/create/CreateBase.stories.tsx、ListBase.stories.tsx等示例中的用法业务代码无需关心它底层存储的键名。如果你的组件需要保存语言、主题这类通用偏好优先考虑这些专用 Hook而不是自己发明 store key。最佳实践向前兼容与 Store 失效不要向 Store 存结构会变的对象如果向 Store 写入复杂对象而应用后续升级改变了对象结构旧代码读到的旧结构对象会导致运行时错误。官方文档给出了典型反例// 旧版本结构 { fontSize: large, colorScheme: dark } // 新版本代码期望的新结构 { ui: { fontSize: large, mode: dark, } } // 这样写可能抛错旧对象没有 .ui const preferences useStore(preferences); const { fontSize, mode } preferences.ui;安全做法是永远假设 Store 中的数据形状可能不符合预期读取时做形状校验并回退默认值let preferences useStore(preferences); if (!preferences.ui || !preferences.ui.fontSize || !preferences.ui.mode) { preferences { ui: { fontSize: large, mode: dark } }; } // 这样永远不会失败 const { fontSize, mode } preferences.ui;更好的做法是只存标量值用点号拆成多个键let fontSize useStore(preferences.ui.fontSize); let mode useStore(preferences.ui.mode);如需更强保障也可以引入 Zod、Yup 等 schema 校验库对读取结果做运行时校验。Store 失效Invalidation版本号自动重置如果应用无法校验对象形状react-admin 提供了逃生舱store invalidation。给 Store 指定一个版本号当 localStorage 中已存数据的版本号与代码不一致时Store 会自动清空所有偏好。import { CoreAdmin, Resource, localStorageStore } from ra-core; const STORE_VERSION 2; const App () ( CoreAdmin dataProvider{dataProvider} store{localStorageStore(STORE_VERSION)} Resource nameposts / /CoreAdmin );每次推送与已存值不兼容的代码时就递增这个版本号。实现上localStorageStore的setup()会读取${prefix}.version若与当前版本不符则删除所有带 Store 前缀的键并写入新版本号localStorageStore.ts。同域名多实例应用键隔离如果同一个域名下运行多个 react-admin 应用可以通过appKey区分各自的存储避免相互覆盖。localStorageStore(version, appKey)的第二个参数即为应用键import { CoreAdmin, Resource, localStorageStore } from ra-core; const APP_KEY blog; const App () ( CoreAdmin dataProvider{dataProvider} store{localStorageStore(undefined, APP_KEY)} Resource nameposts / /CoreAdmin );默认appKey为空字符串这样配置就可以在多个实例之间共享localStorageStore.ts。临时 Store用 memoryStore 取消持久化如果某些偏好不需要在会话间保留可以覆盖默认的 Store 为memoryStore()这样每次应用加载后 Store 都会重置为空import { CoreAdmin, Resource, memoryStore } from ra-core; const App () ( CoreAdmin dataProvider{dataProvider} store{memoryStore()} Resource nameposts / /CoreAdmin );注意一个细节localStorageStore在 localStorage 不可用如浏览器隐身模式时也会自动回退到内存存储LocalStorageShim见 localStorageStore.ts 的可用性探测保证功能不降级。单元测试隔离 Store 避免测试污染Store 是持久化的这意味着如果某个单元测试修改了 Store 中的值该值会残留在内存中影响下一个测试导致随机的测试失败——所有依赖 Store 的功能行选择、侧边栏状态、语言选择、useStore 本身都可能受影响。解决办法是为每个测试传入新的memoryStore()import { CoreAdminContext, memoryStore } from ra-core; test(MyComponent, async () { const { getByText } render( CoreAdminContext store{memoryStore()} MyComponent / /CoreAdminContext ); const items await screen.findAllByText(/Item #[0-9]: /) expect(items).toHaveLength(10) })如果不需要CoreAdminContext的其他能力也可以只包裹StoreContextProviderimport { StoreContextProvider, memoryStore } from ra-core; test(MyComponent, async () { const { getByText } render( StoreContextProvider value{memoryStore()} MyComponent / /StoreContextProvider ); const items await screen.findAllByText(/Item #[0-9]: /) expect(items).toHaveLength(10) })仓库自带的测试 useStore.spec.tsx 正是采用这一模式通过StoreContextProvidermemoryStore验证了默认返回undefined、读取已有值、挂载时订阅与卸载时退订、同 key 联动、异 key 隔离、支持更新函数、key 变化时清空值等全部行为。总结useStore是 react-admin 持久化用户偏好的标准入口其设计要点可归纳为API 即useStateconst [value, setValue] useStore(key, defaultValue)学习成本为零同步且全局同步读取避免多余请求全局响应式更新跨组件、跨标签页生效持久化默认开启基于 localStorage隐身模式自动降级为内存存储配套工具完整useRemoveFromStore、useResetStore、useStoreContext以及useLocaleState等专用 Hook 覆盖各种读写场景版本失效机制localStorageStore(version, appKey)让你在数据结构升级时一键重置旧值memoryStore()让你在需要时彻底关闭持久化。掌握useStore你就能以最小成本为应用实现「记忆用户选择」的体验。更深入的内容可继续阅读 Store 文档、源码 useStore.ts、localStorageStore.ts 以及测试 useStore.spec.tsx。赞分享前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载相关推荐react-admin useStore Hook 完全指南全局持久化偏好存储的读写、同步与最佳实践react admin useStore Hook 完全指南全局持久化偏好存储的读写、同步与最佳实践 useStore 是 react admin 框架提供的前端UI组件react-admin useResetStore Hook 实战指南清空全局 Store 的正确姿势react admin useResetStore Hook 实战指南清空全局 Store 的正确姿势 useResetStore 是 react admin前端UI组件Zustand useStore Hook 完整指南在 React 中接入任意 vanilla storeZustand useStore Hook 完整指南在 React 中接入任意 vanilla store useStore 是 Zustand 提供的 Re前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
