shadcn/ui Base 与 Radix 双引擎适配指南以 Spree 项目为例的 API 差异全解析【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree导读在 shadcn/ui 生态中底层原语primitive库正经历从 Radix UI 到 Base UI 的演进同一个组件如Select、Slider、Accordion在两种引擎下的 props、组合方式与受控模式并不相同。本文以 Spree 开源电商平台仓库中.agents/skills/shadcn/rules/base-vs-radix.md这一规范文档为核心骨架系统梳理base与radix两套 API 的差异涵盖组合方式asChildvsrender、非按钮触发器、Select数据驱动、ToggleGroup、Slider与Accordion的取值语义并给出 Incorrect/Correct 对照与可复制的 TSX 示例帮助你在任何 shadcn/ui 项目中快速判断当前引擎并写出正确的组件代码。先判断当前引擎npx shadcnlatest info的base字段在动手写任何组件前第一步永远是确认项目当前使用的原语库。shadcn 官方 Skill 文档.agents/skills/shadcn/SKILL.md明确要求通过npx shadcnlatest info输出的base字段判断是radix还是base并据此选择正确的 API 写法。npx shadcnlatest info输出的 JSON 中base字段取值为radix或base它决定了组合方式使用asChildradix还是renderbase是否允许在Select根组件上传items数据ToggleGroup、Slider、Accordion的defaultValue是字符串、数组还是纯数字内容定位是positionpopper还是alignItemWithTrigger。在 Spree 仓库中管理后台packages/dashboard/package.json 与 packages/dashboard-ui/package.json依赖base-ui/react^1.4.1即当前仓库的 dashboard 组件栈是 Base UI 引擎同时仓库内的规则文件也要求同时兼容 radix 写法例如radix-nova风格因此掌握两套 API 的对应关系是必要的。切换 preset 时 CLI 会自动保留components.json中的base配置预设码本身不编码 base因此显式核对info输出是唯一可靠手段。组合方式radix 的asChild与 base 的render两种引擎都允许把触发按钮替换为自定义元素但机制不同Radix使用asChild让子元素继承触发器的一切 props 与事件Base UI使用render把自定义元素作为渲染结果传入。无论哪种引擎都不要在触发器外面包裹多余的元素否则会破坏事件传递与可访问性aria-expanded、焦点管理等。Incorrect两种引擎通用DialogTrigger div ButtonOpen/Button /div /DialogTriggerCorrectradixDialogTrigger asChild ButtonOpen/Button /DialogTriggerCorrectbaseDialogTrigger render{Button /}Open/DialogTrigger这一规则适用于所有 trigger 与 close 类组件规则原文逐一列出包括DialogTrigger、SheetTrigger、AlertDialogTrigger、DropdownMenuTrigger、PopoverTrigger、TooltipTrigger、CollapsibleTrigger、DialogClose、SheetClose、NavigationMenuLink、BreadcrumbLink、SidebarMenuButton、Badge、Item。实践提示当使用 base 引擎时render的写法更接近传入组件实例而 radix 的asChild要求子元素必须能接受 ref否则 React 会报 Function components cannot be given refs 的警告这是排查触发器失效时的常见切入点。用render把按钮渲染为非按钮元素时必须显式声明nativeButton{false}base onlyBase UI 的Button默认渲染为原生button。当通过render将其替换为a、span等非按钮元素时必须显式传入nativeButton{false}否则组件仍会按按钮语义处理导致语义与键盘行为错乱。Incorrectbase缺少nativeButton{false}Button render{a href/docs /}Read the docs/ButtonCorrectbaseButton render{a href/docs /} nativeButton{false} Read the docs /ButtonCorrectradix无需该 propButton asChild a href/docsRead the docs/a /Button同理凡是触发器通过render渲染为非Button元素的情况例如用InputGroupAddon作为 Popover 触发器也需要补上nativeButton{false}// base. PopoverTrigger render{InputGroupAddon /} nativeButton{false} Pick date /PopoverTrigger这与 shadcn 规范中 rules/composition.md 强调的用组件而非自定义标记一脉相承按钮与触发器的语义role、键盘事件、焦点环必须由原语层保证而不是靠外层div手工模拟。Selectbase 的items数据驱动 vs radix 的内联 JSXSelect是两套 API 差异最大的组件。items propbase onlyBase 要求在Select根组件上提供items数组选项声明与渲染是数据驱动的Radix 则完全使用内联 JSX 声明选项。Incorrectbase缺itemsSelect SelectTriggerSelectValue placeholderSelect a fruit //SelectTrigger /SelectCorrectbaseconst items [ { label: Select a fruit, value: null }, { label: Apple, value: apple }, { label: Banana, value: banana }, ] Select items{items} SelectTrigger SelectValue / /SelectTrigger SelectContent SelectGroup {items.map((item) ( SelectItem key{item.value} value{item.value}{item.label}/SelectItem ))} /SelectGroup /SelectContent /SelectCorrectradixSelect SelectTrigger SelectValue placeholderSelect a fruit / /SelectTrigger SelectContent SelectGroup SelectItem valueappleApple/SelectItem SelectItem valuebananaBanana/SelectItem /SelectGroup /SelectContent /Select注意两点placeholder 的实现不同base 在items数组中放一个{ value: null }的项作为占位符radix 使用SelectValue placeholder...。选项必须包在 Group 里SelectItem必须位于SelectGroup内对应 rules/composition.md 的 Items always inside their Group 规则直接裸放在SelectContent下是错误的。内容定位alignItemWithTriggerbasevspositionradix// base. SelectContent alignItemWithTrigger{false} sidebottom // radix. SelectContent positionpopper多选与对象值base onlyBase 额外支持三类 radix 不具备的能力多选multiple 数组类型的defaultValueSelectValue支持渲染函数Select items{items} multiple defaultValue{[]} SelectTrigger SelectValue {(value: string[]) value.length 0 ? Select fruits : ${value.length} selected} /SelectValue /SelectTrigger ... /Select对象值itemToStringValue负责把对象映射为字符串供匹配与展示SelectValue的渲染函数收到原始对象Select defaultValue{plans[0]} itemToStringValue{(plan) plan.name} SelectTrigger SelectValue{(value) value.name}/SelectValue /SelectTrigger ... /Select从源码角度看这两处差异对应 Base UIbase-ui/reactcontrolled data model 的设计选项的取值、展示与比较逻辑统一收敛在根组件的数据模型上渲染函数只是视图层而 Radix 把每一项的 JSX 即数据。这解释了为什么 base 能支持value: null占位与对象值而 radix 只能做字符串单选。在 Spree 后台大量使用base-ui/react见 packages/dashboard/package.json的场景下数据驱动的Select更适合表单字段与 API 枚举值的绑定。ToggleGroupmultiple布尔 vstypesingle | multipleBase 用布尔 propmultiple表达多选单选时不需要任何 type prop且defaultValue永远是数组Radix 必须显式传type单选时defaultValue是字符串。Incorrectbase混用了 radix 的type写法ToggleGroup typesingle defaultValuedaily ToggleGroupItem valuedailyDaily/ToggleGroupItem /ToggleGroupCorrectbase// Single无需任何 propdefaultValue 始终是数组。 ToggleGroup defaultValue{[daily]} spacing{2} ToggleGroupItem valuedailyDaily/ToggleGroupItem ToggleGroupItem valueweeklyWeekly/ToggleGroupItem /ToggleGroup // 多选。 ToggleGroup multiple ToggleGroupItem valueboldBold/ToggleGroupItem ToggleGroupItem valueitalicItalic/ToggleGroupItem /ToggleGroupCorrectradix// SingledefaultValue 是字符串。 ToggleGroup typesingle defaultValuedaily spacing{2} ToggleGroupItem valuedailyDaily/ToggleGroupItem ToggleGroupItem valueweeklyWeekly/ToggleGroupItem /ToggleGroup // 多选。 ToggleGroup typemultiple ToggleGroupItem valueboldBold/ToggleGroupItem ToggleGroupItem valueitalicItalic/ToggleGroupItem /ToggleGroup受控单值对比——base 需要手动做数组解包/打包// base —— 包裹/解包数组。 const [value, setValue] React.useState(normal) ToggleGroup value{[value]} onValueChange{(v) setValue(v[0])} // radix —— 直接传字符串。 const [value, setValue] React.useState(normal) ToggleGroup typesingle value{value} onValueChange{setValue}从源码结构可以推断Base 内部把 ToggleGroup 的值统一建模为数组单选手动约束为长度为 1因此受控时必须由调用方完成[value]与v[0]的转换Radix 则通过type在内部区分标量与数组。迁移时最常见的 bug 就是受控 value 类型不匹配导致的选中态不更新。Slider纯数字 vs 数组Base 的单滑块直接接受纯数字Radix 的defaultValue则要求数组两者在 range双滑块场景下都使用数组。Incorrectbase把 radix 的数组写法搬了过来Slider defaultValue{[50]} max{100} step{1} /CorrectbaseSlider defaultValue{50} max{100} step{1} /CorrectradixSlider defaultValue{[50]} max{100} step{1} /受控回调的类型差异——base 的onValueChange在 TS 下可能需要显式断言// base. const [value, setValue] React.useState([0.3, 0.7]) Slider value{value} onValueChange{(v) setValue(v as number[])} / // radix. const [value, setValue] React.useState([0.3, 0.7]) Slider value{value} onValueChange{setValue} /推断依据Base 为单滑块把值建模为标量导致回调参数类型在双滑块场景下需要断言收敛Radix 始终是数组模型onValueChange{setValue}直接类型匹配。跨引擎迁移 Slider 时务必同时检查defaultValue与onValueChange两处。Accordiontype/collapsiblevsmultipleRadix 要求typesingle或typemultiple并可用collapsible允许折叠当前展开项defaultValue为字符串Base 不提供type用布尔multiple表达多选defaultValue永远是数组。Incorrectbaseradix 写法Accordion typesingle collapsible defaultValueitem-1 AccordionItem valueitem-1.../AccordionItem /AccordionCorrectbaseAccordion defaultValue{[item-1]} AccordionItem valueitem-1.../AccordionItem /Accordion // 多选。 Accordion multiple defaultValue{[item-1, item-2]} AccordionItem valueitem-1.../AccordionItem AccordionItem valueitem-2.../AccordionItem /AccordionCorrectradixAccordion typesingle collapsible defaultValueitem-1 AccordionItem valueitem-1.../AccordionItem /AccordionBase 的 单选可折叠 语义即defaultValue{[item-1]}单元素数组只展开一个条目点击其他条目会替换当前展开项需要全部折叠的空状态则对应空数组。速查表常见组件的 base/radix 差异一览组件维度baseradix通用触发器组合方式render{Button /}asChild通用触发器外层包裹禁止额外div包裹禁止额外div包裹Button 触发非按钮声明nativeButton{false}无需asChild自动继承Select选项来源根组件itemsprop数据驱动内联 JSXSelect占位符items 中{ value: null }项SelectValue placeholder...Select内容定位alignItemWithTriggerpositionpopperSelect多选/对象值支持multiple、itemToStringValue仅字符串单选ToggleGroup模式声明multiple布尔单选无需 proptypesingle \| multipleToggleGroupdefaultValue永远是数组单选字符串、多选数组Slider单滑块 defaultValue纯数字数组Sliderrange数组数组Accordion模式声明multiple布尔typecollapsibleAccordiondefaultValue永远是数组单选字符串、多选数组如何在 Spree 项目中落地这些规则Spree 仓库把这份base-vs-radix.md作为 shadcn Skill 的强制规则之一见 .agents/skills/shadcn/SKILL.md 中 Component Structure → base-vs-radix.md 的引用在新增或修改 UI 组件时按如下流程执行确认引擎运行npx shadcnlatest info读取base字段而不是靠记忆猜。对照本表涉及触发器、Select、ToggleGroup、Slider、Accordion 时逐项核对上表的取值语义与 props。参考既有实现仓库内 dashboard 组件大量使用render组合与 Base UI 原语如 packages/dashboard/src/components/spree/orders/order-cancel-dialog.tsx 中的render{({ field }) ...}模式这些文件本身就是 base 引擎下的活体示例迁移或排查时可直接对照。避免混写最常见的回归是radix 心智、base 工程——例如给 base 的Select忘传items、给Accordion传typesingle、把Slider的defaultValue写成数组。这类问题编译期往往不报错但运行期交互会失效。掌握这两套 API 的映射关系后无论是新建 shadcn/ui 项目、在 radix 与 base 之间切换 presetnpx shadcnlatest apply --preset code还是为 Spree 这类以 Base UI 为原语的后台应用贡献组件都能写出语义正确、可访问、可迁移的 UI 代码。【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考