react-starter-kit 中的 shadcn 组件 API 迁移指南:Base UI 与 Radix 基座差异全解析(base-vs-radix)
react-starter-kit 中的 shadcn 组件 API 迁移指南:Base UI 与 Radix 基座差异全解析(base-vs-radix)
本指南以仓库内 shadcn 技能规则文档 .agents/skills/shadcn/rules/base-vs-radix.md 为骨架,系统梳理 shadcn/ui 在两种底层原语库——Base UI(base) 与 Radix UI(radix)——之间的 API 差异。读完你可以在同一份 components.json 配置下准确判断当前项目属于哪种基座,并正确编写 Select、ToggleGroup、Slider、Accordion 以及各类 Trigger 组件,避免把 Radix 的写法直接套到 Base UI 项目(或反之)导致的编译错误与交互失效。
1. 先判定基座:base 还是 radix
Base UI 与 Radix UI 是 shadcn/ui 可选的两种底层原语库。二者提供的组件语义相似,但 props 设计差异很大:同样是"把子元素渲染成别的元素",Radix 用 asChild,Base UI 用 render;同样是"单选还是多选",Radix 用 type="single" | "multiple",Base UI 用 multiple 布尔属性。
因此写任何组件之前,第一步永远是确认当前项目的基座:
npx shadcn@latest info
info 命令输出的项目配置中,base 字段即表示原语库,取值 radix 或 base,它决定组件可用 API 与 props(字段含义详见 cli.md — info 命令 与 SKILL.md — Key Fields)。SKILL.md 中的强制规则也明确写道:使用 asChild(radix)还是 render(base)来自定义触发器,取决于 npx shadcn@latest info 输出的 base 字段。
在本仓库中,UI 组件包 packages/ui/package.json 的依赖清单里全部是 @radix-ui/react-*(如 @radix-ui/react-select、@radix-ui/react-toggle-group、@radix-ui/react-dialog 等),packages/ui/components/select.tsx 直接 import * as SelectPrimitive from "@radix-ui/react-select" 并逐层包装。可以确认:这是一个 radix 基座的项目,日常书写应使用 asChild、type="single" 这一套 API。
提示:切换预设(preset)时,shadcn CLI 会自动保留
components.json中当前的base(base或radix),preset code 本身不编码基座信息。如需在临时目录做--dry-run对比,请显式传--base <current-base>。
2. 组合方式:asChild(Radix)vs render(Base)
Radix 使用 asChild 让子元素替换默认渲染元素;Base UI 使用 render。无论哪种基座,都不要把触发器包在多余的 DOM 元素里——多包一层 div 会破坏触发器与弹出层之间的引用关系,导致点击不生效或 a11y 属性错位。
错误写法(两种基座通用):
<DialogTrigger>
<div>
<Button>Open</Button>
</div>
</DialogTrigger>
正确写法(Radix):
<DialogTrigger asChild>
<Button>Open</Button>
</DialogTrigger>
正确写法(Base):
<DialogTrigger render={<Button />}>Open</DialogTrigger>
这一规则适用于所有 Trigger 与 Close 类组件,包括但不限于:DialogTrigger、SheetTrigger、AlertDialogTrigger、DropdownMenuTrigger、PopoverTrigger、TooltipTrigger、CollapsibleTrigger、DialogClose、SheetClose、NavigationMenuLink、BreadcrumbLink、SidebarMenuButton、Badge、Item。
仓库佐证:本仓库 UI 包的 packages/ui/components/dialog.tsx 等文件均基于 @radix-ui/react-* 原语,因此项目内所有自定义触发器都应采用 asChild 形式,而不是 render。
3. Button / 触发器渲染为非 button 元素(仅 Base 需要 nativeButton={false})
当 Base UI 的 render 把默认的 <button> 换成非 button 元素(如 <a>、<span>)时,必须追加 nativeButton={false},告诉组件不要按原生按钮的交互与语义处理该元素。
错误写法(Base,缺少 nativeButton={false}):
<Button render={<a href="/docs" />}>Read the docs</Button>
正确写法(Base):
<Button render={<a href="/docs" />} nativeButton={false}>
Read the docs
</Button>
正确写法(Radix,用 asChild 即可,无需该属性):
<Button asChild>
<a href="/docs">Read the docs</a>
</Button>
对触发器同样适用——只要 render 渲染的不是 Button,就要补上 nativeButton={false}:
// base.
<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>
Pick date
</PopoverTrigger>
理解要点:Base UI 的 Button 内部会为原生按钮处理键盘事件、focus 样式与 type 属性。当渲染目标是链接或其它元素时,nativeButton={false} 相当于告诉组件"不要强加按钮行为"。而 Radix 的 asChild 通过 @radix-ui/react-slot(本仓库 packages/ui/package.json 中也引入了 @radix-ui/react-slot)把属性透传给子元素,天然兼容非 button 元素,因此不存在该问题。
4. Select:items prop、占位符与定位方式
Select 是两者差异最集中的组件,分三个维度对比。
4.1 items prop(仅 Base 需要)
Base UI 要求在 Select 根组件上提供 items 数组;Radix 只使用内联 JSX,不要求 items。
错误写法(Base,缺少 items):
<Select>
<SelectTrigger>
<SelectValue placeholder="Select a fruit" />
</SelectTrigger>
</Select>
正确写法(Base):
const 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>
</Select>
正确写法(Radix):
<Select>
<SelectTrigger>
<SelectValue placeholder="Select a fruit" />
</SelectTrigger>
<SelectContent>
<SelectGroup>
<SelectItem value="apple">Apple</SelectItem>
<SelectItem value="banana">Banana</SelectItem>
</SelectGroup>
</SelectContent>
</Select>
4.2 占位符(Placeholder)
- Base:占位符不是一个 prop,而是在
items数组中放一个{ value: null }的条目。 - Radix:直接在
<SelectValue placeholder="...">上声明。
4.3 内容定位(Content positioning)
- Base:使用
alignItemWithTrigger控制是否与触发器对齐。 - Radix:使用
position="popper"采用 popper 定位。
// base.
<SelectContent alignItemWithTrigger={false} side="bottom">
// radix.
<SelectContent position="popper">
仓库佐证:本仓库 packages/ui/components/select.tsx 的 SelectContent 默认 position = "popper",并为 popper 模式追加了 translate 微调类与 --radix-select-trigger-width/height 变量控制弹层尺寸——这正是 radix 基座下定位体系的实际落地,Base UI 项目中不存在这些 radix CSS 变量。
5. Select 进阶(仅 Base):多选与对象值
Base UI 的 Select 额外支持三类能力,Radix 只能单选、值只能是字符串:
multiple:允许多选;SelectValue支持 render-function 子元素,可自定义选中态的展示;- 通过
itemToStringValue支持 对象值(object values)。
Base — 多选:
<Select items={items} multiple defaultValue={[]}>
<SelectTrigger>
<SelectValue>
{(value: string[]) =>
value.length === 0 ? "Select fruits" : `${value.length} selected`
}
</SelectValue>
</SelectTrigger>
...
</Select>
Base — 对象值(如将套餐对象作为 value):
<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>
<SelectTrigger>
<SelectValue>{(value) => value.name}</SelectValue>
</SelectTrigger>
...
</Select>
这在需要携带结构化数据(例如本仓库中按套餐对象选择计费方案)的场景里尤其有用:value 直接是对象,itemToStringValue 负责把对象转成可读字符串,SelectValue 的 render-function 决定触发器上展示哪一字段。
6. ToggleGroup:multiple 布尔值 vs type
- Base:用
multiple布尔属性区分单/多选,defaultValue永远是数组。 - Radix:用
type="single"或type="multiple",defaultValue单选取字符串、多选取数组。
错误写法(Base,混用了 Radix 的 type 与字符串默认值):
<ToggleGroup type="single" defaultValue="daily">
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
</ToggleGroup>
正确写法(Base):
// 单选:无需任何 prop,defaultValue 始终是数组。
<ToggleGroup defaultValue={["daily"]} spacing={2}>
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
<ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
</ToggleGroup>
// 多选。
<ToggleGroup multiple>
<ToggleGroupItem value="bold">Bold</ToggleGroupItem>
<ToggleGroupItem value="italic">Italic</ToggleGroupItem>
</ToggleGroup>
正确写法(Radix):
// 单选,defaultValue 是字符串。
<ToggleGroup type="single" defaultValue="daily" spacing={2}>
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
<ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
</ToggleGroup>
// 多选。
<ToggleGroup type="multiple">
<ToggleGroupItem value="bold">Bold</ToggleGroupItem>
<ToggleGroupItem value="italic">Italic</ToggleGroupItem>
</ToggleGroup>
受控单选值的差异(这是最容易踩坑的地方):
// base — 需要手动包裹/解包数组。
const [value, setValue] = React.useState("normal")
<ToggleGroup value={[value]} onValueChange={(v) => setValue(v[0])}>
// radix — 直接就是字符串。
const [value, setValue] = React.useState("normal")
<ToggleGroup type="single" value={value} onValueChange={setValue}>
仓库佐证:本仓库 packages/ui/components/toggle-group.tsx 基于 @radix-ui/react-toggle-group,因此项目内写单选时必须带 type="single",受控时 value 直接用字符串、onValueChange 直接 setState。
7. Slider:标量 vs 数组
- Base:单滑块直接接受普通数字(
defaultValue={50})。 - Radix:始终要求数组(
defaultValue={[50]})。
错误写法(Base,按 Radix 传数组):
<Slider defaultValue={[50]} max={100} step={1} />
正确写法(Base):
<Slider defaultValue={50} max={100} step={1} />
正确写法(Radix):
<Slider defaultValue={[50]} max={100} step={1} />
两者在范围滑块(range)场景下都用数组。受控模式下,Base 的 onValueChange 可能返回联合类型,需要断言:
// 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} />
8. Accordion:type/collapsible vs multiple
- Radix:必须传
type="single"或type="multiple";单选时可用collapsible允许再次点击收起;defaultValue是字符串。 - Base:没有
typeprop,用multiple布尔值控制;defaultValue永远是数组。
错误写法(Base,直接照搬 Radix):
<Accordion type="single" collapsible defaultValue="item-1">
<AccordionItem value="item-1">...</AccordionItem>
</Accordion>
正确写法(Base):
// 单选(默认),defaultValue 是数组。
<Accordion defaultValue={["item-1"]}>
<AccordionItem value="item-1">...</AccordionItem>
</Accordion>
// 多选。
<Accordion multiple defaultValue={["item-1", "item-2"]}>
<AccordionItem value="item-1">...</AccordionItem>
<AccordionItem value="item-2">...</AccordionItem>
</Accordion>
正确写法(Radix):
<Accordion type="single" collapsible defaultValue="item-1">
<AccordionItem value="item-1">...</AccordionItem>
</Accordion>
记忆要点:Radix 靠 type 声明语义,Base 靠 multiple 追加能力;defaultValue 的形状也随之改变(字符串 vs 数组)。
9. 速查对照表与仓库实践
| 能力点 | Base UI(base) |
Radix UI(radix) |
|---|---|---|
| 替换默认元素 | render={<Button />} |
asChild |
| 渲染为非 button 元素 | 需 nativeButton={false} |
无需额外 prop |
| Select 数据源 | 根组件必传 items |
纯内联 JSX |
| Select 占位符 | items 中 { value: null } 条目 |
<SelectValue placeholder="..." /> |
| Select 弹层定位 | alignItemWithTrigger |
position="popper" |
| Select 多选 / 对象值 | 支持(multiple、itemToStringValue) |
不支持(仅单选、字符串值) |
| ToggleGroup 单/多选 | multiple 布尔值 |
`type="single" |
| ToggleGroup defaultValue | 永远是数组 | 单选取字符串、多选取数组 |
| Slider 单滑块默认值 | 数字 | 数组 |
| Accordion 单/多选 | multiple 布尔值 |
type + collapsible |
| Accordion defaultValue | 永远是数组 | 字符串 |
本仓库中的落地实践:react-starter-kit 的 UI 组件包位于 packages/ui,通过 packages/ui/index.ts 统一导出,应用侧以 @repo/ui 别名引用(见 apps/app/components.json 的 "ui": "@repo/ui")。由于依赖与源码均基于 @radix-ui/react-* 原语,写组件时请一律使用上述 Radix 列 的 API;只有当你把项目切换到 base 基座(通过 npx shadcn@latest 的 preset/init 流程),才需要迁移到 Base UI 的 render、items、multiple、数组式 defaultValue 写法。相关规则文件的完整清单见 SKILL.md — Detailed References,其余强制规范(样式、表单、图标、组合方式)分别记录在 styling.md、forms.md、composition.md 与 icons.md 中,可作为组件审查与代码生成时的对照依据。