前端UI组件【免费下载链接】primitivesRadix Primitives is an open-source UI component library for building high-quality, accessible design systems and web apps. Maintained by workos.项目地址https://gitcode.com/gh_mirrors/pr/primitives点击查看免费下载radix-ui/react-use-layout-effect是 Radix Primitives 组件库内部使用的基础工具 Hook核心解决一个高频问题在服务端渲染SSR与 React Server ComponentsRSC环境下直接调用 React 的useLayoutEffect会触发控制台警告。本文以该包的 CHANGELOG 版本演进为骨架结合仓库源码深入解析其实现原理、RSC 兼容性保障、CI 发布机制与真实使用场景帮助读者理解 Radix 这类 UI 库如何安全地在 SSR 环境中复用布局副作用逻辑。包定位仅供内部使用的工具包该包的 README.md 只有一句话This is an internal utility, not intended for public usage.这是一个内部工具不面向公开使用。与radix-ui/react-dialog、radix-ui/react-tooltip这类面向最终用户的组件不同react-use-layout-effect被设计为 Radix 各组件共享的底层基础设施通过 internal.ts 统一导出后供内部模块引用export { useLayoutEffect } from radix-ui/react-use-layout-effect;从 package.json 可以看到它的完整元信息名称radix-ui/react-use-layout-effect当前版本1.1.4许可证MITsideEffects: false声明无副作用便于打包器webpack/rollup进行 tree-shaking 优化peerDependenciesreact ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc并声明types/react为可选依赖脚本lintoxlint、typechecktsc --noEmit、buildradix-build、clean/reset核心实现一行代码的 SSR 安全判断该包的全部实现只有约 11 行位于 use-layout-effect.tsximport * as React from react; /** * On the server, React emits a warning when calling useLayoutEffect. * This is because neither useLayoutEffect nor useEffect run on the server. * We use this safe version which suppresses the warning by replacing it with a noop on the server. * * See: https://reactjs.org/docs/hooks-reference.html#uselayouteffect */ const useLayoutEffect globalThis?.document ? React.useLayoutEffect : () {}; export { useLayoutEffect };实现思路极为精炼其逻辑可拆解为三步环境探测通过globalThis?.document判断当前是否运行在浏览器环境。存在document对象即意味着客户端渲染上下文否则为服务端Node.js或 RSC 渲染环境。客户端分支浏览器环境直接透传 React 原生的useLayoutEffect保留其在 DOM 变更后同步执行副作用的全部特性。服务端分支用一个空函数() {}替换。因为在服务端无论useLayoutEffect还是useEffect都不会真正执行直接替换为空实现既消除了 React 的警告又避免了不必要的逻辑挂载。入口文件 index.ts 仅做一层转发export { useLayoutEffect } from ./use-layout-effect;注意代码注释中解释了服务端触发警告的根因——React 在服务端不会运行任何 effect包括useLayoutEffect与useEffect因此直接调用会收到 useLayoutEffect does nothing on the server 之类的提示。该工具通过环境判断在源头规避了这一警告。为什么需要它SSR/RSC 下的useLayoutEffect警告React 的 Hooks 参考文档 明确指出useLayoutEffect只在浏览器端有意义它会在 DOM 变更之后、浏览器绘制之前同步刷新布局副作用常用于测量元素尺寸、同步更新 DOM 位置等需要避免闪烁的场景。问题在于服务端渲染阶段根本没有 DOMuseLayoutEffect无法执行直接调用时 React 会在控制台输出警告干扰日志排查在 React Server Components 模型中模块顶层若引用了客户端专属 API还可能引发导入错误详见下文 RSC 兼容性章节。Radix 的解法不是封装复杂的环境判断工具函数而是将浏览器环境检查与原生 hook 引用固化在一个常量上既保证运行时零开销又让所有内部组件获得一致的、无警告的 SSR 体验。版本演进主线从元数据补全到 RSC 兼容性回滚该包 CHANGELOG.md 记录了三个版本的关键变更构成了本文分析的主线1.1.2补充repository.directory元数据Added repository.directory to all package.json files该版本为所有 package.json 增加了repository.directory字段。以本包为例package.json 中记录了仓库类型、URL 与目录repository: { type: git, url: githttps://github.com/radix-ui/primitives.git, directory: packages/react/use-layout-effect }这一字段是 npm 生态的通用约定monorepo 中的包通过它指明自身在仓库中的子目录位置方便工具链如npm、依赖机器人、缺陷追踪插件正确跳转到源码所在路径是包元数据规范化的基础性工作。1.1.3通过 CI 重新发布以附加 provenance 认证Republish through CI to attach provenance attestations. The previous versions of these packages were published manually outside of CI and therefore shipped without provenance; this patch re-releases the same code through the CI pipeline so every package includes an attestation.该版本是一次纯发布流程变更不涉及任何代码改动。其技术要点provenance来源证明是 npm 供应链安全机制通过发布时生成的签名证明attestation向安装方声明该包由声明的来源构建并发布可有效缓解依赖混淆与供应链投毒风险此前版本是脱离 CI 手动发布因而缺失 provenance本次通过 CI 流水线重新发布相同代码使所有包含的包都附带认证。从仓库实际发布流程看这也体现了该 monorepo 将发布固化为 CI 环节的整体策略——与 release-process.md 中描述的发布流程相互印证。1.1.4回滚破坏性变更修复 RSC 兼容性Reverted breaking changes that caused compatibility issues with React Server Components.这是当前最新版本也是最具技术深度的一条上一版中引入了某类破坏性变更breaking changes导致包在 React Server Components 环境下出现兼容性问题1.1.4 将其回滚恢复为与 RSC 兼容的行为结合 use-layout-effect.tsx 的当前实现可见globalThis?.document的空值安全写法?.本身即是面向 RSC 的设计——在服务端globalThis.document为undefined可选链保证了访问不抛错从而让模块在 Server Component 中可安全导入。RSC 兼容性的仓库级保障测试与脚手架1.1.4 的兼容性回滚并非孤立行为仓库对此有系统性保障。根目录的 scripts/rsc-compatibility.rsc.test.ts 是专门的 RSC 回归防护测试其核心设计运行环境该测试套件在 React 的react-server构建下运行对应vitest.config.mts中的rsc项目此构建中客户端专属 API 为undefined用以模拟 Server Component 的模块上下文校验点测试断言React.createContext为undefined确保确实跑在 React 的 server build 上避免测试通过了但测错环境边界机制声明了use client的包被视为客户端边界会被桩替换stub未声明的包则要求能被 Server Component 直接导入且不抛错覆盖范围遍历core与react两个包组中所有可发布的包逐一验证其入口模块可被安全导入。该测试的注释还明确指出模块顶层module scope的客户端专属引用是导入期即可捕获的问题而仅在渲染期调用的客户端 API 无法在导入时被发现——这正是radix-ui/react-use-layout-effect采用常量级环境判断方案的深层原因把客户端专属的React.useLayoutEffect引用收敛到条件分支中避免它在模块顶层对 RSC 导入产生副作用。仓库还提供 apps/ssr-testing 这一 Next.js SSR 测试应用含 rsc 页面用于在真实服务端渲染场景中验证各组件与 Hook 的兼容性。真实使用场景遍布 Radix 组件内部的底层依赖useLayoutEffect在 Radix 组件库中被广泛引用是众多交互组件的公共地基。仓库内的使用证据包括id.tsx生成确定性 ID 的核心逻辑。对于 React 18 之前的版本通过useLayoutEffect在客户端为无deterministicId的调用生成递增的radix-${id}IDuseLayoutEffect(() { if (!deterministicId) setId((reactId) reactId ?? String(count)); }, [deterministicId]);announce.tsx无障碍实时区域aria-live通知组件依赖该 Hook 同步执行文本变更后的播报逻辑avatar.tsx镜像图片加载状态到 ref并同步触发onLoadingStatusChange回调同时负责通过new window.Image()预加载图片并在useLayoutEffect中挂载 load/error 事件监听use-effect-event.tsx在 React 尚未稳定提供useEffectEvent时用useLayoutEffect将最新回调写入 ref 以近似模拟其行为此外dialog.tsx、popper.tsx、popover.tsx、navigation-menu.tsx、portal.tsx、collapsible.tsx、scroll-area.tsx、slider.tsx、toast.tsx、tooltip.tsx、roving-focus-group.tsx 等均引入了该 Hook用于在布局阶段同步完成焦点管理、位置计算、尺寸测量等操作。这种一个底层 Hook 服务数十个组件的架构正是 Radix 将 SSR 安全的副作用处理固化为单一内部包的原因任何组件都不需要重复实现环境判断且所有组件共享同一份经过 RSC 测试验证的实现。总结从 1.1.2 的元数据规范到 1.1.3 的 CI 发布与 provenance 认证再到 1.1.4 的 RSC 兼容性回滚radix-ui/react-use-layout-effect的版本演进完整展示了 Radix 对 SSR/RSC 兼容性的持续投入。其核心价值在于实现极简以globalThis?.document的常量级判断替代运行时复杂逻辑服务端分支降级为空函数从源头消除useLayoutEffect的服务端警告兼容面广peerDependencies 覆盖 React 16.8 至 19 的全部主流版本生态保障与scripts/rsc-compatibility.rsc.test.ts、apps/ssr-testing等仓库设施配合形成从单元测试到真实 SSR 应用的多层验证体系。对希望在自有 SSR/RSC 应用中安全使用useLayoutEffect的开发者而言这个包的实现与版本故事是一个可直接借鉴的范本用一次环境探测换取所有组件与页面在服务端渲染时的零警告、零异常。赞分享前端UI组件【免费下载链接】primitivesRadix Primitives is an open-source UI component library for building high-quality, accessible design systems and web apps. Maintained by workos.项目地址https://gitcode.com/gh_mirrors/pr/primitives点击查看免费下载相关推荐Osmedeus Cloud Cheatsheet多云端分布式扫描的完整速查与源码级解析Osmedeus Cloud Cheatsheet多云端分布式扫描的完整速查与源码级解析 本篇速查指南聚焦 Osmedeus GitHub_Trending前端UI组件Reka UI 完全指南以可访问性与无样式理念构建 Vue 设计系统的现代组件库Reka UI 完全指南以可访问性与无样式理念构建 Vue 设计系统的现代组件库 本篇技术指南以 Reka UIRadix Vue v2 演化版官方 In前端UI组件radix-ui/react-compose-refs 深入解析Radix Primitives 中 ref 组合工具的实现原理与版本演进radix ui/react compose refs 深入解析Radix Primitives 中 ref 组合工具的实现原理与版本演进 导读 radi前端UI组件上一篇如何安装和使用misakaXiOS终极定制工具完整指南下一篇Litho 事件机制实战从 ClickEvent 声明、自定义事件到可见性事件基于 codelabs/events 完整演练创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考