shadcn/ui 组件迁移指南:Base 与 Radix 的 API 差异对照与正确写法
shadcn/ui 组件迁移指南:Base 与 Radix 的 API 差异对照与正确写法
导读
在 shadcn/ui 生态中,组件既可以基于 Radix UI(radix),也可以基于 Base UI(base)两种底层原始组件库(primitive library)构建,两者在组合方式、受控状态与数据模型上存在系统性差异。本文以仓库 .agents/skills/shadcn/rules/base-vs-radix.md 为骨架,逐项拆解 asChild 与 render、Select 的 items 属性、ToggleGroup/Slider/Accordion 的类型与取值差异,并给出可直接复制运行的 Incorrect/Correct 代码对照。读完本文,你将能准确判断项目当前使用的 base 变体,并写出在两种变体下都能正确工作的组件代码。
判断依据:在项目根目录运行
npx shadcn@latest info,查看输出的base字段即可确认当前变体为radix还是base。该字段定义可参考 SKILL.md 中的 "Key Fields" 一节,它直接影响组件可用属性与 API 形态。
一、Composition:asChild(Radix)与 render(Base)
差异本质
- Radix 变体:通过
asChild属性让子元素"替换"默认渲染元素,语义是"把这个元素当作默认元素的子级来组合"。 - Base 变体:通过
render属性传入一个 JSX 元素(如<Button />)来替换默认元素,语义是"渲染这个元素"。
两者目的相同:让 Trigger 等包装组件把原生元素替换为你自己的组件,从而保留无障碍属性、事件与焦点管理。
常见错误:不要在 Trigger 外再包一层 div
Incorrect(两种变体都不对):
<DialogTrigger>
<div>
<Button>Open</Button>
</div>
</DialogTrigger>
多包一层 div 会破坏 Trigger 的事件透传,点击按钮可能无法触发弹层,同时破坏语义结构。
Correct(radix):
<DialogTrigger asChild>
<Button>Open</Button>
</DialogTrigger>
Correct(base):
<DialogTrigger render={<Button />}>Open</DialogTrigger>
注意 base 的写法把按钮文案作为 DialogTrigger 的子文本传入,而 render 只负责"渲染什么元素"。
适用组件范围
这条规则适用于所有 trigger 与 close 类组件,包括:DialogTrigger、SheetTrigger、AlertDialogTrigger、DropdownMenuTrigger、PopoverTrigger、TooltipTrigger、CollapsibleTrigger、DialogClose、SheetClose、NavigationMenuLink、BreadcrumbLink、SidebarMenuButton、Badge、Item。
从仓库的组件结构规则看,shadcn 的 Critical Rules 也明确要求"对自定义 trigger 使用 asChild(radix)或 render(base)",见 rules/composition.md。
二、Button / Trigger 渲染为非按钮元素(仅 Base 需要 nativeButton)
问题场景
当 base 变体的 render 把元素替换成非 <button> 的元素(如 <a>、<span>)时,组件内部仍会按原生按钮的逻辑处理点击、键盘事件与表单提交。此时必须显式声明 nativeButton={false},告诉组件"我渲染的不是原生按钮",避免生成错误的 DOM 行为。
Incorrect(base)——缺少 nativeButton={false}:
<Button render={<a href="/docs" />}>Read the docs</Button>
Correct(base):
<Button render={<a href="/docs" />} nativeButton={false}>
Read the docs
</Button>
Correct(radix)——radix 无需该属性:
<Button asChild>
<a href="/docs">Read the docs</a>
</Button>
Trigger 的 render 不是 Button 时同理
// base
<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>
Pick date
</PopoverTrigger>
这一差异只在 base 变体中出现,radix 由于天然使用 asChild 组合子元素,不需要也不存在 nativeButton 属性。
三、Select:items 属性(仅 Base)与内联 JSX(Radix)
数据来源差异
- Base:根组件
<Select>必须通过items属性接收选项数据数组,这是数据模型的唯一入口。 - Radix:不使用
items,选项直接在<SelectContent>中以内联 JSX 声明。
Incorrect(base)——缺少 items:
<Select>
<SelectTrigger>
<SelectValue placeholder="Select a fruit" />
</SelectTrigger>
</Select>
Correct(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>
注意 base 示例中 items 数组的第一项 { label: "Select a fruit", value: null } 正是占位符的载体,同时 SelectItem 仍然需要在 SelectGroup 内渲染(组件结构规则见 rules/composition.md)。
Correct(radix):
<Select>
<SelectTrigger>
<SelectValue placeholder="Select a fruit" />
</SelectTrigger>
<SelectContent>
<SelectGroup>
<SelectItem value="apple">Apple</SelectItem>
<SelectItem value="banana">Banana</SelectItem>
</SelectGroup>
</SelectContent>
</Select>
占位符(Placeholder)差异
| 变体 | 占位符实现方式 |
|---|---|
| base | 在 items 数组中放入一个 { value: null } 的占位项 |
| radix | 使用 <SelectValue placeholder="..."> 属性 |
弹层定位(Content Positioning)差异
| 变体 | 定位属性 |
|---|---|
| base | alignItemWithTrigger(布尔值) |
| radix | position(如 "popper") |
// base
<SelectContent alignItemWithTrigger={false} side="bottom">
// radix
<SelectContent position="popper">
四、Select 进阶:多选与对象值(仅 Base)
Base 变体在 Select 上提供了远超 radix 的能力:
- 多选:根组件支持
multiple布尔属性; - 渲染函数子级:
SelectValue可以接收 render-function 子级,根据当前值动态渲染; - 对象值:通过
itemToStringValue把对象序列化为可展示的字符串。
Radix 的 Select 仅支持单选且值只能是字符串。
Correct(base——多选):
<Select items={items} multiple defaultValue={[]}>
<SelectTrigger>
<SelectValue>
{(value: string[]) =>
value.length === 0 ? "Select fruits" : `${value.length} selected`
}
</SelectValue>
</SelectTrigger>
...
</Select>
这里 defaultValue 传入空数组表示初始无选中项,SelectValue 的 render-function 接收 string[] 并返回展示文案。
Correct(base——对象值):
<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>
<SelectTrigger>
<SelectValue>{(value) => value.name}</SelectValue>
</SelectTrigger>
...
</Select>
对象值场景下,defaultValue 直接是对象本身,itemToStringValue 负责把对象转成字符串用于显示与匹配,SelectValue 的 render-function 则自定义选中后展示的内容。
五、ToggleGroup:multiple 布尔属性(Base)与 type 属性(Radix)
模式声明方式
- Base:使用
multiple布尔属性声明是否多选;默认(不传)即单选。 - Radix:使用
type="single"或type="multiple"声明。
Incorrect(base)——沿用了 radix 的 type 写法:
<ToggleGroup type="single" defaultValue="daily">
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
</ToggleGroup>
Correct(base):
// 单选(无需任何属性),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>
Correct(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}>
核心差异:base 的 value/defaultValue 永远是数组(即使单选),而 radix 的单选值是字符串、多选值才是数组。这也是 shadcn 的 SKILL.md 中将 ToggleGroup 推荐用于"2–5 个选项之间切换"时的首选组件。
六、Slider:标量(Base 单滑块)与数组(Radix 恒为数组)
取值形态差异
- Base:单滑块时直接接受一个普通数字(number)。
- Radix:无论单滑块还是范围滑块,值一律是数组。
Incorrect(base)——沿用了 radix 的数组写法:
<Slider defaultValue={[50]} max={100} step={1} />
Correct(base):
<Slider defaultValue={50} max={100} step={1} />
Correct(radix):
<Slider defaultValue={[50]} max={100} step={1} />
范围滑块与受控写法
两种变体在**范围滑块(range)**场景下都使用数组:
// base —— 受控 onValueChange 可能需要一次类型断言
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 单滑块场景下 value 是标量、onValueChange 回调参数类型可能与 number[] 存在差异,必要时使用 v as number[] 断言以保持 TypeScript 类型一致。
七、Accordion:type/collapsible(Radix)与 multiple 布尔属性(Base)
模式声明差异
- Radix:必须声明
type="single"或type="multiple";单选模式下额外支持collapsible(允许全部折叠);defaultValue是字符串。 - Base:无
type属性,改用multiple布尔属性;defaultValue永远是数组。
Incorrect(base)——沿用了 radix 写法:
<Accordion type="single" collapsible defaultValue="item-1">
<AccordionItem value="item-1">...</AccordionItem>
</Accordion>
Correct(base):
// 单选(默认即单选,无需属性)
<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>
Correct(radix):
<Accordion type="single" collapsible defaultValue="item-1">
<AccordionItem value="item-1">...</AccordionItem>
</Accordion>
在 base 中若要实现"单选且可折叠"(即 radix 的 type="single" collapsible),同样基于默认单选模式即可;multiple 对应多选。注意 base 没有 collapsible 属性,折叠行为由默认交互处理。
八、速查对照表
| 能力点 | Base | Radix |
|---|---|---|
| 组合自定义元素 | render={<Button />} |
asChild |
| Trigger 渲染非按钮 | 需加 nativeButton={false} |
无需额外属性 |
| Select 数据源 | 根组件 items 属性 |
内联 JSX |
| Select 占位符 | items 中 { value: null } 项 |
<SelectValue placeholder="..."> |
| Select 弹层定位 | alignItemWithTrigger |
position |
| Select 多选 | multiple 属性 + render-function |
不支持(仅单选字符串) |
| Select 对象值 | itemToStringValue + render-function |
不支持 |
| ToggleGroup 模式 | multiple 布尔(默认单选) |
type="single" / type="multiple" |
| ToggleGroup 默认值 | 始终为数组 ["daily"] |
单选为字符串、多选为数组 |
| Slider 单滑块值 | 标量 50 |
数组 [50] |
| Slider 范围值 | 数组(必要时断言) | 数组 |
| Accordion 模式 | multiple 布尔(默认单选) |
type="single" / type="multiple" |
| Accordion 折叠 | 无 collapsible 属性 |
type="single" 时支持 collapsible |
| Accordion 默认值 | 始终为数组 | 单选为字符串、多选为数组 |
九、最佳实践与检查清单
- 先确认变体:编写或修复组件前,先运行
npx shadcn@latest info查看base字段(radix或base),再决定采用哪套 API 写法。 - Trigger 不做多余包裹:无论哪种变体,都不要在 Trigger 外面套
div,直接asChild或render组合目标组件。 - base 渲染非按钮要声明
nativeButton={false}:渲染<a>、<span>、InputGroupAddon等非按钮元素时必加,否则交互与语义可能异常。 - 值形态对齐:base 的
ToggleGroup/Accordion的value/defaultValue恒为数组;Slider 单滑块为标量。radix 的ToggleGroup/Accordion单选用字符串。 - Group 包裹不遗漏:
SelectItem等条目必须放在对应SelectGroup内,这与 base/radix 变体无关,是 shadcn 全局组件结构规则,详见 rules/composition.md。 - 不猜不抄:迁移代码时以
npx shadcn@latest docs <component>获取官方文档与示例为准,避免凭记忆混用两套 API(例如把type="single"抄进 base 项目)。
相关文档入口
- 本文核心对照依据:.agents/skills/shadcn/rules/base-vs-radix.md
- 组件组合与结构规则:.agents/skills/shadcn/rules/composition.md
- shadcn 技能总览与
base字段说明:.agents/skills/shadcn/SKILL.md - CLI 命令与
info字段参考:.agents/skills/shadcn/cli.md - 主题定制与变体切换:.agents/skills/shadcn/customization.md