shadcn/ui 组件迁移指南:Base 与 Radix 的 API 差异对照与正确写法

原创2026-10-12 12:26:551,347 阅读
文章标签:开发工具

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 默认值 始终为数组 单选为字符串、多选为数组

九、最佳实践与检查清单

  1. 先确认变体:编写或修复组件前,先运行 npx shadcn@latest info 查看 base 字段(radix 或 base),再决定采用哪套 API 写法。
  2. Trigger 不做多余包裹:无论哪种变体,都不要在 Trigger 外面套 div,直接 asChild 或 render 组合目标组件。
  3. base 渲染非按钮要声明 nativeButton={false}:渲染 <a>、<span>、InputGroupAddon 等非按钮元素时必加,否则交互与语义可能异常。
  4. 值形态对齐:base 的 ToggleGroup/Accordion 的 value/defaultValue 恒为数组;Slider 单滑块为标量。radix 的 ToggleGroup/Accordion 单选用字符串。
  5. Group 包裹不遗漏:SelectItem 等条目必须放在对应 SelectGroup 内,这与 base/radix 变体无关,是 shadcn 全局组件结构规则,详见 rules/composition.md。
  6. 不猜不抄:迁移代码时以 npx shadcn@latest docs <component> 获取官方文档与示例为准,避免凭记忆混用两套 API(例如把 type="single" 抄进 base 项目)。

相关文档入口

登录后查看全文
remeda