shadcn/ui 迁移参考Radix 到 Base UI 的 Disclosure 与 Toggle 组件族 Props 映射全解【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui本篇指南基于 shadcn/ui 仓库内置的迁移技能文档 disclosure.md系统讲解 accordion、collapsible、tabs、toggle、toggle-group、toolbar 六个组件从 Radix UI 迁移到base-ui/react时的部件改名、Props 签名变化、data 属性与 CSS 变量改写规则。读完本文你可以对照仓库中的 registry 金标实现golden pair逐行完成一个项目里全部可折叠/可切换类组件的迁移并正确重写配套样式而不会遗漏行为差异。这份文档在迁移体系中的位置shadcn/ui 仓库在 skills/migrate-radix-to-base/ 目录下内置了一套迁移知识库供迁移 Agent 与开发者共同使用SKILL.md定义迁移流程preflight 检查、golden pair 策略、渐进/整项目两种模式、硬规则、.migration/component.md报告格式disclosure.md本文主体disclosure toggle 组件族的 Props 映射表accordion、collapsible、tabs、toggle、toggle-group、toolbarclass-mapping.mdclassName / cva / cn 中的 data 选择器与 CSS 变量机械改写表universal-patterns.md导入改写、asChild→render通用模式、部件改名速查表consumer-props.md应用侧调用点consumerProps 改写清单。disclosure.md的映射依据是 Radix 官方 primitives 文档与 Base UI 官方.md文档的交叉核对并对照已安装的base-ui/react1.6.0的.d.ts文件进行了校验原文注明Base UI 官方 accordion 文档页面有滞后此处以类型声明为准。因此本文所有结论的适用前提是Base UI 1.6.0。仓库内apps/v4/registry/bases/{base,radix}/ui/下成对存放的组件实现如 base/ui/accordion.tsx 与 radix/ui/accordion.tsx正是这些映射关系的可验证实现证据。全组件通用约定以下五条约定适用于后文所有组件迁移时先整体过一遍asChildboolean默认false→render。类型从boolean变为ReactElement | (props: HTMLProps, state) ReactElement。签名变了不再是包裹一个子元素而是把元素直接传给renderBase UI 会把 props 合并到该元素上。渲染为按钮的部件还额外接受nativeButton默认true当render产出的不是button元素时设为false。className和style支持函数式取值(state) value。Radix 的data-[state...]值属性变为 Base UI 的存在性属性data-open、data-closed、data-pressed、data-active——状态由属性是否存在表达而非属性值。Base UI 所有 change 回调都新增了第二个eventDetails参数{ reason, event, cancel(), ... }可用于阻止状态变更。Radix 的dirprop 全部移除Base UI 从 DOMdir属性或DirectionProvider读取方向。accordion部件映射Root → Root、Item → Item、Header → Header、Trigger → Trigger、Content → Panel。Accordion.Root → Accordion.RootRadix prop类型 / 默认值Base UI 对应迁移说明asChildboolean/falserender签名变更。把元素传给render而不是包裹子元素。type必填single \| multiple/ —multiple签名变更。typemultiple→multipleboolean默认falsetypesingle→ 省略。valuestringsingle或string[]multiple/ —value签名变更。Base UI 永远是数组Value[]Value anysingle 模式也不例外valuea→value{[a]}。defaultValuestring或string[]/ —defaultValue与value相同的数组注意事项。onValueChange(value: string) void或(value: string[]) void/ —onValueChange签名变更(value: Value[], eventDetails: Accordion.Root.ChangeEventDetails) void。永远收到数组single 模式需value[0]解包。collapsibleboolean/false— 移除Base UI single 模式永远可折叠。若要禁止关闭最后一个打开项即 Radixcollapsible{false}的默认行为需控制value并忽略数组为空的更新或在value.length 0时调用eventDetails.cancel()。disabledboolean/falsedisabled默认false相同。dirltr \| rtl/ltr— 移除用 DOMdir属性 /DirectionProvider。orientationvertical \| horizontal/vertical— 移除prop 存在但已废弃为空操作Base UI 遵循 APG 指引更新移除了 roving 方向键焦点orientation及loopFocus不再影响键盘行为。不要带过去。Accordion.Item → Accordion.ItemRadix prop类型 / 默认值Base UI 对应迁移说明asChildboolean/falserender签名变更。value必填string/ —value约束变化Base UI 的value是any且可选省略时按索引自动生成。为保持一致性建议继续传字符串。disabledboolean/falsedisabled默认false相同。Accordion.Header → Accordion.HeaderRadix prop类型 / 默认值Base UI 对应迁移说明asChildboolean/falserender签名变更。两者默认都渲染h3。Accordion.Trigger → Accordion.TriggerRadix prop类型 / 默认值Base UI 对应迁移说明asChildboolean/falserender另有nativeButton默认true签名变更。Accordion.Content → Accordion.PanelRadix prop类型 / 默认值Base UI 对应迁移说明asChildboolean/falserender签名变更。forceMounttrue \| undefined/ —keepMountedboolean默认false改名。forceMount→keepMounted关闭的面板保留在 DOM 中但隐藏。Root上也有同名 prop可一次性作用于所有面板。Base UI 独有、值得知道的 propsRoot.hiddenUntilFound/Panel.hiddenUntilFound默认false使用hiddenuntil-found让浏览器页内查找能展开面板会覆盖keepMounted。Radix 无对应物。Root.keepMounted按面板keepMounted的根级版本。Item.onOpenChange(open: boolean, eventDetails: Accordion.Item.ChangeEventDetails) void逐项的展开回调。Radix 无对应物。Trigger.nativeButton默认true。所有部件的className/style状态函数形式。data 属性映射accordionRadixBase UI备注Item/Header/Content [data-stateopen \| closed]Item、Headerdata-open存在性Paneldata-open存在性accordion 部件没有data-closed与 collapsible 不同关闭态样式按缺少data-open书写。Trigger [data-stateopen]Trigger [data-panel-open]改名。Trigger 专用于data-panel-open而不是data-open。[data-disabled][data-disabled]相同Root、Item、Header、Trigger、Panel。[data-orientation]所有部件Root、Paneldata-orientation随 orientation 一起废弃避免依赖。—Item/Header/Panel [data-index]Base UI 独有数字项索引。—Panel [data-starting-style]、[data-ending-style]Base UI 独有CSS transition 动画钩子替代 Radix 的挂载/卸载动画模式。CSS 变量映射accordionRadixBase UI--radix-accordion-content-height--accordion-panel-height--radix-accordion-content-width--accordion-panel-width仓库实现证据registry 中的 accordion 金标对对比 radix/ui/accordion.tsx 与 base/ui/accordion.tsx上述规则逐条落地导入与类型import { Accordion as AccordionPrimitive } from radix-uiReact.ComponentPropstypeof AccordionPrimitive.Root→import { Accordion as AccordionPrimitive } from base-ui/react/accordionAccordionPrimitive.Root.Props子路径导入、类型写法变化见 universal-patterns.mdAccordionPrimitive.Content→AccordionPrimitive.Panel类型AccordionPrimitive.Panel.PropsTrigger 类名中 Radix 版的disabled:pointer-events-none disabled:opacity-50变为 Base UI 版的aria-disabled:pointer-events-none aria-disabled:opacity-50——这与 class-mapping.md 的禁用态钩子规则一致accordion trigger 在 Base UI 中用aria-disabled表达禁用而非disabled属性disabled:*类在此处成为死代码需替换为aria-disabled:*面板内部高度动画Radix 版写h-(--radix-accordion-content-height)Base UI 版写h-(--accordion-panel-height) contenteditable="false">【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
