Superglue Fragments 完全指南让 Rails Partial 拥有前端身份轻松实现乐观更新【免费下载链接】superglueA productive library for Classic Rails, React and Redux项目地址: https://gitcode.com/gh_mirrors/su/superglueSuperglue 是一个面向 Classic Rails、React 与 Redux 的生产力库而其中的 Fragments 能力可以让每一个 Rails Partial 在前端拥有可引用的身份id只要你用这个 id 更新一次数据所有使用该片段的页面都会立即同步刷新。配合useUpdateFragmentHook你甚至不需要发起请求就能完成购物车、点赞按钮这类高频交互的乐观更新且更新过程完全可回滚。本文面向刚接触 Superglue 的开发者用少量示例带你理解Fragment 与 Rails Partial 的关系如何在服务端用一行 DSL 声明 Fragment数据在 Redux Store 中如何标准化 → 非标准化流转如何用 3 步完成一次带失败回滚的乐观更新什么是 Fragment给 Partial 一个前端身份Superglue 官方文档 docs/fragments.md 中有一句精准的定义Fragment 是一个带有前端引用身份的已渲染 Partial。你可能已经习惯用_header.html.erb这样的 Partial 来组织视图——提取出这个文件就等价于声明了这是一个 header它有自己的身份和边界。但传统做法里渲染成 HTML 后这份身份信息就丢失了。Fragment 保留了它一个 id全局唯一例如userCart代表当前用户的购物车多处引用单一数据源页头、页尾、弹窗同时展示购物车时它们共享同一段数据改一处处处更新按 id 更新 Fragment 后所有页面/组件中的该 Fragment 立即响应服务端声明一行 DSL无需新建 APISuperglue 的核心理念是不需要 API——同一个路由浏览器访问.html得到页面访问.json得到同构的 JSON 数据。Fragments 的声明就发生在.json.props模板中基于 PropsTemplate 这个 JBuilder 风格的 DSLjson.title Hello json.cart(partial: [user/cart, fragment: userCart]) do end含义非常直白渲染app/views/user/_cart这个 Partial并把它注册为 id 是userCart的 Fragment。没有新建控制器、没有新路由、没有序列化器讨论一个可被前端引用的购物车实体就诞生在 Redux Store 里。数据流转标准化存入 Store按需非标准化读取页面响应先以标准化形态返回数据本体放在data里fragments数组只记录哪个 id 指向哪条路径{ data: { title: Hello, cart: { totalCost: 69.97, itemCount: 3 } }, fragments: [{ type: userCart, path: [cart] }] }客户端收到后Superglue 会做非标准化处理userCart的完整数据被存入state.fragments.userCart而页面数据中的cart位置只保留一个引用对象{ _id: userCart }。读取时由useContent/useFragment两个 Hook 完成透明解引用实现见 lib/hooks/useFragment.tsxconst content useContent() h1{content.title}/h1 p{content.cart.items.length} {/* 自动解引用 Fragment像普通对象一样读 */}/p背后的机制值得一知半解Hook 返回的是 Proxy它懒加载地解开 Fragment 引用同时悄悄记录你读到了哪些 Fragment。之后任何一个被读到的 Fragment 发生变更对应 React 组件就会精准重渲染——不需要手动写依赖数组。3 步完成乐观更新useUpdateFragment有了身份乐观更新就变得自然。Superglue 提供useUpdateFragmentHook实现见 lib/hooks/useUpdateFragment.tsx返回一个update函数接收Fragment 定位 Immer 草稿函数三步完成定位传入字符串 iduserCart、toFragmentRef(userCart)或直接传content.cart这个带_id的引用对象改草稿在回调里像改普通对象一样直接赋值底层由 Immer 生成不可变的新状态自动分发Superglue 将新状态写入 Store所有引用该 Fragment 的组件瞬间更新以购物车加购为例const update useUpdateFragment() update(toFragmentRef(userCart), (cartDraft) { cartDraft.items.push(newItem) // 直接修改安全且不可变 cartDraft.totalCost newItem.price cartDraft.itemCount 1 })两个贴心的设计嵌套更新草稿中的子节点如果本身是 Fragment 引用如{ __id: userCoupons }可以把它直接传给下一次update调用实现跨层级的组合更新可回滚update的返回值是链式对象调用其reset()即可撤销本次修改——这正是乐观更新先改界面、失败再回滚的保险丝配合服务端同步点赞按钮的完整姿势乐观更新的经典套路是本地先改 → 请求服务端 → 失败则回滚在 Superglue 里天然成立const toggleLike async () { update(toFragmentRef(post_${postId}), (draft) { // ① 立即反馈 draft.liked !draft.liked draft.likeCount draft.liked ? 1 : -1 }) try { await remote(/posts/${postId}/toggle_like, { method: POST }) } catch { // ② 失败时按同样方式再改一次即完成回滚 update(toFragmentRef(post_${postId}), (draft) { draft.liked !draft.liked draft.likeCount draft.liked ? 1 : -1 }) } }整个过程中没有任何手动 setState、没有重新请求整页数据UI 的即时性完全由 Fragment 的身份机制保证。进阶Super Turbo Streams 让 Fragment 实时变化Fragment 本质是 Partial所以 Superglue 还移植了 Turbo Streams 的追加/前置/替换操作命名为Super Turbo Streams详见 docs/super-turbo-streams.mdbroadcast_append_to messages把新消息 Partial 追加进messagesFragmentbroadcast_prepend_to notifications置顶新通知broadcast_update_to messages用新内容替换整个 Fragment服务端一行广播所有已连接的客户端中对应的 Fragment 自动更新。聊天室、实时评论这类场景等于用 JSON 而不是 HTML 重写了 Turbo Streams且天然与 Redux 状态模型打通。常见注意事项不能直接改 ProxyuseContent/useFragment返回的 Proxy 是只读的一切修改必须走useUpdateFragment这是刻意设计id 找不到会抛错update时若 Fragment 不存在会直接抛异常能帮你尽早发现命名不一致按需订阅控制渲染范围用useFragment(toFragmentRef(cart))让子组件只订阅自己关心的 Fragment可避免父组件不必要的重渲染原理见 lib/hooks/useFragment.tsx 中的依赖追踪延伸阅读与源码位置资料路径Fragments 官方文档docs/fragments.md客户端更新含乐观更新示例docs/client-updates.mdSuper Turbo Streamsdocs/super-turbo-streams.mduseFragment/toFragmentRef实现lib/hooks/useFragment.tsxuseUpdateFragment实现Immer 草稿lib/hooks/useUpdateFragment.tsxFragment 状态变更的 Reducerlib/reducers/fragmentReducer.ts类型定义Fragment / FragmentReflib/types/fragment.ts行为测试spec/lib/fragmentReducer.spec.js、spec/lib/useUpdateFragment.spec.jsx一句话总结Fragments 把 Rails Partial 的语义身份带到了前端让 Redux 状态管理像写 Rails 视图一样顺手——声明一次处处引用改一处全局响应。【免费下载链接】superglueA productive library for Classic Rails, React and Redux项目地址: https://gitcode.com/gh_mirrors/su/superglue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考