用途:这是一套面向 shadcn 组件与自定义 Radix UI 原语的 Base UI 迁移技能,强调手动、低风险、分阶段推进,适合需要将现有 Radix 依赖替换为 Base UI 的项目。
主要能力与四阶段流程:
- 移除 Radix 包并切换导入:从依赖中删除 Radix 原语包,添加项目使用的 Base UI 包,逐个组件替换导入;本阶段保持组件名稳定(必要时用别名)以缩小 diff。可参考 references/checklist.md 的通过顺序与验证门。
- 以 Base UI 的 render 组合替换 asChild:找出依赖 asChild 的触发器/内容组合,改用 Base UI 基于 render 的组合方式,保留语义 HTML 并避免嵌套交互元素,对每个迁移后的触发器重新测试键盘与焦点行为。可参考 references/migration-map.md 中的常见 asChild 迁移模式。
- 解决类型与 API 差异:每迁移一个组件族后运行类型检查与构建;将 Radix 风格的 prop/类型名替换为 Base UI 等价物,把 TypeScript 错误当作迁移待办清单,优先处理扇出最高的组件;检查重命名的 slot/backdrop/overlay/content 原语以及事件 prop 命名差异。可参考 references/migration-map.md 映射常见重命名类别。
- 将定位迁移到基于 Positioner 的布局:对浮动 UI(下拉、弹出、提示、类对话框浮层)按需引入 Base UI Positioner 模式,将旧内容节点上的放置相关 prop 移到新的定位层,重新验证放置、碰撞处理、对齐与动画原点。可参考 references/migration-map.md 的定位转换指引。
操作规则:一次只迁移一个原语族(dropdown、popover、dialog、tooltip、select);API 迁移期间保持视觉样式不变,样式重构留到后续 PR;不确定时优先查阅文档与 shadcn 的 Base UI 示例,不要猜测 prop 对等性;在各组件族之间保持构建通过,避免回归叠加。
完成标准:源码中不再有 Radix 原语导入;无迁移相关 TypeScript 错误;所有浮动组件使用有效的 Base UI 定位组合;迁移组件的键盘/焦点交互通过;现有 UI 快照或冒烟测试通过。
限制:资料未提供具体安装命令、代码示例、版本要求、收费信息与支持平台,这些内容暂未提供。