react-starter-kit 中的 shadcn 组件 API 迁移指南:Base UI 与 Radix 基座差异全解析(base-vs-radix)

原创2026-09-19 15:34:411,958 阅读
文章标签:后端前端

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:没有 type prop,用 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 中,可作为组件审查与代码生成时的对照依据。

登录后查看全文
react-starter-kit