前端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是 Radix Primitives 开源仓库位于packages/react/radix-ui/中的统一聚合入口包它把 30 多个低层级、可访问性优先的 React UI 组件原语全部打包为一个 npm 包通过命名空间导出、radix-ui/primitive子路径导入和unstable_前缀三种方式对外提供一致的 API。读完本文你将掌握radix-ui包的导入形态、内部导出结构、internal/unstable子入口的用途以及它如何在 React 19 与 React Server Components 场景下保持兼容并能直接照抄可运行的代码示例。radix-ui官方定位是一个open-source UI component library用于构建高质量、可访问的设计系统与 Web 应用见 radix-ui/README.md。它面向低层级low-level组件设计每个原语都聚焦单一交互模式既可以作为设计系统的基础层整体使用也可以被增量地逐个引入——这一增量采用能力正是聚合包存在的前提。一、radix-ui 聚合包的整体定位1.1 一个包一次安装统一入口radix-ui包本身不含任何独立实现它的源码入口 src/index.ts 只是对各个子包如radix-ui/react-dialog、radix-ui/react-select的再导出re-export。从 package.json 可以看出其依赖关系依赖了30 个radix-ui/react-*子包全部以workspace:*形式声明在 monorepo由pnpm-workspace.yaml管理内联引用还依赖了radix-ui/primitive核心原语与radix-ui/react-primitiveasChild渲染原语等基础层source/main/module均指向./src/index.ts发布时publishConfig才切换到dist下的 ESM/CJS 双格式产物dist/index.mjs/dist/index.js并配套.d.ts/.d.mts类型声明sideEffects: false标记配合按需导入即可被打包器安全摇树tree-shaking。因此使用者只需要安装一个radix-ui就能拿到全部原语而无需逐个安装几十个包。1.2 每个子包独立存在虽然聚合包方便但仓库中每个原语仍然是独立包例如packages/react/accordion/src/accordion.tsxAccordion 折叠面板packages/react/dialog/src/dialog.tsxDialog 对话框packages/react/checkbox/src/checkbox.tsxCheckbox 复选框而聚合包中对应的accordion.ts、dialog.ts、checkbox.ts等文件内容极简例如 src/accordion.ts 只有一行export * from radix-ui/react-accordion;。这说明radix-ui是门面facade入口实现始终在子包中两者发布节奏由CHANGELOG.md统一记录。二、安装与快速上手2.1 安装包名直接是radix-ui在仓库内通过 pnpm workspace 引用pnpm add radix-ui在仓库的 SSR 测试应用 apps/ssr-testing/package.json 中可以看到真实用法radix-ui: workspace:*被一个 Next.js 16 React 19 应用直接依赖用于验证聚合包在服务端渲染SSR与 React Server ComponentsRSC场景下的行为。2.2 最小示例import { Dialog, Tabs, Slider } from radix-ui; export function Example() { return ( Tabs.Root defaultValuetab1 Tabs.List Tabs.Trigger valuetab1Tab 1/Tabs.Trigger Tabs.Trigger valuetab2Tab 2/Tabs.Trigger /Tabs.List Tabs.Content valuetab1Content 1/Tabs.Content Tabs.Content valuetab2Content 2/Tabs.Content /Tabs.Root ); }每个命名空间下都采用Root/Trigger/Content/Indicator等一致的部件part式 API配合asChild属性由radix-ui/react-primitive的 Slot 机制实现可以完全接管渲染的 DOM 元素。三、统一命名空间导出完整组件清单src/index.ts是聚合包的正式导出清单所有原语以命名空间形式export * as Xxx from ...导出全部内容如下命名空间对应子包典型部件AccessibleIconradix-ui/react-accessible-iconRootAccordionradix-ui/react-accordionRoot/Item/Trigger/ContentAlertDialogradix-ui/react-alert-dialogRoot/Portal/Overlay/ContentAspectRatioradix-ui/react-aspect-ratioRootAvatarradix-ui/react-avatarRoot/Image/FallbackCheckboxradix-ui/react-checkboxRoot/IndicatorCollapsibleradix-ui/react-collapsibleRoot/Trigger/ContentContextMenuradix-ui/react-context-menuRoot/Trigger/Content/ItemDialogradix-ui/react-dialogRoot/Portal/Overlay/ContentDirectionradix-ui/react-directionProviderDropdownMenuradix-ui/react-dropdown-menuRoot/Trigger/Content/ItemFormradix-ui/react-formRoot/Field/Control/MessageHoverCardradix-ui/react-hover-cardRoot/Trigger/ContentLabelradix-ui/react-labelRootMenubarradix-ui/react-menubarRoot/Menu/Trigger/ContentNavigationMenuradix-ui/react-navigation-menuRoot/List/Item/Trigger/Contentunstable_OneTimePasswordFieldradix-ui/react-one-time-password-fieldRoot/Input/HiddenInputunstable_PasswordToggleFieldradix-ui/react-password-toggle-fieldRoot/Input/Toggle/Icon/SlotPopoverradix-ui/react-popoverRoot/Trigger/Content/AnchorPortalradix-ui/react-portalRootProgressradix-ui/react-progressRoot/IndicatorRadioGroupradix-ui/react-radio-groupRoot/Item/IndicatorScrollArearadix-ui/react-scroll-areaRoot/Viewport/Scrollbar/ThumbSelectradix-ui/react-selectRoot/Trigger/Content/ItemSeparatorradix-ui/react-separatorRootSliderradix-ui/react-sliderRoot/Track/Range/ThumbSlotradix-ui/react-slotRoot/SlottableSwitchradix-ui/react-switchRoot/ThumbTabsradix-ui/react-tabsRoot/List/Trigger/ContentToastradix-ui/react-toastRoot/Provider/Title/Description/ActionToggleradix-ui/react-toggleRootToggleGroupradix-ui/react-toggle-groupRoot/ItemToolbarradix-ui/react-toolbarRoot/ToggleGroup/Separator/LinkTooltipradix-ui/react-tooltipRoot/Trigger/ContentVisuallyHiddenradix-ui/react-visually-hiddenRoot表中典型部件来自各子包源码例如 checkbox.tsx 导出Root与Indicatordialog.tsx 导出Root、Trigger、Portal、Overlay、Content等。命名空间下还有asChild、受控/非受控、事件回调等通用属性约定。从1.6.3版本开始见 CHANGELOG.md聚合包还提供了每个原语的子路径入口与根入口的命名空间导出一一对应import { Accordion } from radix-ui/accordion; // 等价于import * as Accordion from radix-ui/accordion; import * as Dialog from radix-ui/dialog;这一能力与package.json中的exports配置./*: ./src/*.ts发布后对应dist/*.mjs与dist/*.js直接对应让打包器能按需加载、彻底丢掉落未使用组件的代码。四、unstable_ 前缀试验性原语4.1 什么是 unstable_ 前缀radix-ui用unstable_前缀标识 API 尚未稳定、仍在收集社区反馈的组件。从 src/index.ts 可以看到它们被命名为unstable_OneTimePasswordField与unstable_PasswordToggleField对应 src/unstable/ 目录下的one-time-password-field.ts与password-toggle-field.ts两个子入口。4.2 一次性密码输入框One Time Password Field该原语实现每个字符一个输入框的 OTP 验证码 UI内置了单输入框式的键盘导航、粘贴覆盖、密码管理器自动填充、数值/字母数字校验、完成自动提交、焦点管理以及一个隐藏输入框把单一值提交进表单。官方示例来源 CHANGELOG.md 1.3.0 节import { unstable_OneTimePasswordField as OneTimePasswordField } from radix-ui; export function Verify() { return ( OneTimePasswordField.Root OneTimePasswordField.Input / OneTimePasswordField.Input / OneTimePasswordField.Input / OneTimePasswordField.Input / OneTimePasswordField.Input / OneTimePasswordField.Input / OneTimePasswordField.HiddenInput / /OneTimePasswordField.Root ); }4.3 密码显示/隐藏切换Password Toggle Field该原语把密码输入框与可见性切换按钮组合在一起并处理了指针切换时焦点返回输入框、键盘/虚拟导航切换时保持焦点、表单提交后自动把可见性重置为隐藏防止浏览器存储明文密码、以及为图标式按钮提供隐式可访问标签。官方示例来源 CHANGELOG.md 1.4.0 节import { unstable_PasswordToggleField as PasswordToggleField } from radix-ui; function FieldWithIconToggle() { return ( PasswordToggleField.Root PasswordToggleField.Input / PasswordToggleField.Toggle PasswordToggleField.Icon visible{EyeOpenIcon /} hidden{EyeClosedIcon /} / /PasswordToggleField.Toggle /PasswordToggleField.Root ); } function FieldWithTextToggle() { return ( PasswordToggleField.Root PasswordToggleField.Input / PasswordToggleField.Toggle PasswordToggleField.Slot visibleHide password hiddenShow password / /PasswordToggleField.Toggle /PasswordToggleField.Root ); }注意1.6.0中该组件修正了一个拼写错误的属性名onVisiblityChange→onVisibilityChange说明 unstable API 会随反馈调整升级时需留意 CHANGELOG。4.4 其他 unstable 部件除了 unstable 命名空间部分组件内部也暴露unstable_前缀的部件用于解耦隐藏表单控件。例如1.5.0起Checkbox/Switch/Slider/RadioGroup/Select 都提供了unstable_Provider、unstable_Trigger或unstable_ThumbProvider、unstable_ThumbTrigger与unstable_BubbleInput部件把原本隐式渲染的隐藏原生input/select暴露给使用者便于自行重组例如需要自定义表单控件的场景import { Slider } from radix-ui; function ExampleSlider() { return ( Slider.Root defaultValue{[data.price.min, data.price.max]} Slider.Track Slider.Range / /Slider.Track Slider.unstable_ThumbProvider nameprice[min] Slider.unstable_ThumbTrigger / Slider.unstable_BubbleInput / /Slider.unstable_ThumbProvider Slider.unstable_ThumbProvider nameprice[max] Slider.unstable_ThumbTrigger / Slider.unstable_BubbleInput / /Slider.unstable_ThumbProvider /Slider.Root ); }五、internal 子入口给高阶使用者与库作者的内部工具除公开组件外聚合包还提供radix-ui/internal子路径实现于 src/internal.ts用于导出跨原语共享的底层机制包括基础原语Primitive含.Root与dispatchDiscreteCustomEvent源自 packages/core/primitive内部共享组件Arrow、Collection、Context、DismissableLayer、FocusGuards、FocusScope、Menu、Popper、Presence、RovingFocus工具函数与 HookscomposeRefs/useComposedRefs来自 react-compose-refs、composeEventHandlers、useCallbackRef、useControllableState/useControllableStateReducer、useEffectEvent、useEscapeKeydown、useIsHydrated、useLayoutEffect、useSize其中dispatchDiscreteCustomEvent值得展开由于 React 18 会批量处理所有事件处理器而自定义事件类型无法被 React 推断优先级因此在某个离散事件discrete event如onPointerDown内部派发自定义事件时需要用ReactDOM.flushSync手动刷新批处理保证状态更新立即生效实现见 packages/core/primitive/src/primitive.tsx。这一点解释了许多交互组件为什么在 pointer 事件里派发 CustomEvent。import { Primitive, composeRefs, useControllableState } from radix-ui/internal; // 自定义组件的受控状态 const [value, setValue] useControllableState({ prop: valueProp, defaultProp: defaultValue, onChange: onValueChange, });使用radix-ui/internal需要接受更强的 API 变动风险——它是为想要复用 Radix 底层机制的高阶用户准备的普通业务组件推荐只用公开命名空间。六、与 React Server Components / SSR 的兼容性6.1 双环境输出与use client边界radix-ui的 peerDependencies 支持 React^16.8 || ^17.0 || ^18.0 || ^19.0横跨四个大版本package.json。发布产物同时提供 ESMdist/index.mjs与 CJSdist/index.js并标记sideEffects: false以便摇树。对于 RSC 场景CHANGELOG 提供了明确的演进证据1.5.0Added missinguse clientdirectives to modules causing errors in RSC modules——为缺失use client指令的模块补齐指令修复 RSC 环境报错1.6.6 / 1.6.7Reverted breaking changes that caused compatibility issues with React Server Components——特意回退了导致 RSC 兼容问题的破坏性变更说明RSC 兼容性是被列为最高优先级的1.6.4Fixed a regression where importing primitives from the rootradix-uientry point erased every primitives types toany——修复根入口把全部类型擦除为any的回归。仓库在 apps/ssr-testing/ 内置了一个 Next.js 16 React 19 的 SSR 测试应用并在 scripts/rsc-compatibility.rsc.test.ts 中编写了专门的 RSC 兼容性测试用来持续守护聚合包在服务端环境下的行为。6.2 摇树优化与生产构建1.6.3起组件部件被标记为/* __PURE__ */并使用具名渲染函数替代Component.displayName ...赋值——后者会阻止部分打包器的死代码消除。这意味着只从根入口导入少数组件时未使用的组件可以被完全丢弃这正是在生产环境放心使用聚合包的前提。七、版本演进要点CHANGELOG 速览聚合包的变更记录集中在 CHANGELOG.md以下是值得关注的关键节点版本关键变化1.6.6 / 1.6.7回退破坏性变更保证 React Server Components 兼容性1.6.5通过 CI 重新发布为包附加 provenance来源证明签名1.6.4修复根入口导入把类型擦除为any的回归1.6.3新增 per-primitive 子路径入口radix-ui/accordion等__PURE__摇树优化修复 Toast 按 Escape 关闭非聚焦 toast、Tooltip 子元素双挂载等1.6.0createSlot/SlotProps支持泛型Select 空字符串值可作为清除选项RadioGroup/Select/Slider/Switch/Checkbox 暴露 unstable 表单部件1.5.0ContextMenu 受控openSelect/Slider/RadioGroup/Switch 新增 unstable 部件启用useSyncExternalStoreReact 18消除 ESM-only bundle 崩溃1.4.0引入unstable_PasswordToggleField1.3.0引入unstable_OneTimePasswordField对使用者而言升级时的重点包括检查unstable_组件的属性更名、关注 RSC 兼容性修复、利用子路径入口逐步替换整包导入以获得更优的打包体积。八、许可与生态radix-ui采用MIT 许可见 package.json 与仓库根 LICENSE版权归 WorkOS自 2022 年起持有。仓库采用 monorepo 结构聚合包在packages/react/radix-ui/所有子包按packages/react/primitive/平铺核心非 React 原语如 packages/core/primitive、packages/core/rect与 React 原语分离测试与示例分别在各子包的*.test.tsx、apps/storybook/stories 与 e2e/ 中。若要快速体验各组件可在仓库内启动 Storybook 查看对应 stories或在 apps/ssr-testing/app 中查看每个原语在 Next.js 下的 SSR 页面用法。小结radix-ui聚合包把 Radix Primitives 的 30 组件原语收敛为单一依赖同时通过根入口命名空间导出、radix-ui/primitive子路径、radix-ui/internal与unstable_试验组件在易用性与精细可控之间划出了清晰边界。其双格式产物、sideEffects: false、__PURE__标记与持续的 RSC 兼容修复使它既能服务于传统客户端应用也能安全地进入 Next.js 等现代服务端渲染体系。赞分享前端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点击查看免费下载相关推荐Vendure Dashboard 扩展迁移指南Radix UI 到 Base UI 的导入合并规则vendure/dashboard 统一导入Vendure Dashboard 扩展迁移指南Radix UI 到 Base UI 的导入合并规则vendure/dashboard 统一导入 本篇指后端电商插件系统Radix UI Primitives 深度指南Radix UI Primitives 深度指南 1. 项目介绍 Radix UI Primitives 是一个开放源码的设计系统和组件库致力于提供高质量、可前端UI组件Radix UI Primitives 搭建与使用指南Radix UI Primitives 搭建与使用指南 1. 项目目录结构及介绍 Radix UI Primitives 的源代码目录结构如下 ├── pac前端UI组件上一篇XStream 反序列化命令执行漏洞 CVE-2021-21351vulhub 环境复现与 JNDI 注入深度剖析下一篇Effect JSON-RPC id 序列化边界修复0 与空字符串 id 的保真处理及 null 通知哨兵映射创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考