企业官网建设流程全解析

OpenWork 中的 shadcn/ui 组件开发指南：Base UI 与 Radix 的 API 差异对照与迁移实战

【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork

OpenWork（opencode 驱动的开源 Claude Cowork 替代品）的 Web 前端基于 shadcn/ui 搭建，其 UI 原语层同时支持 Base UI 与 Radix 两种实现。本篇技术指南以.opencode/skills/shadcn技能规则中base-vs-radix为核心骨架，系统梳理两者在组合模式（render/asChild）、Select、ToggleGroup、Slider、Accordion等组件上的 API 差异，并结合 apps/app/src/components/ui 下的真实源码给出正反示例，帮助你在 OpenWork 及任何 shadcn/ui 项目中写出正确、可移植的组件代码。

先决条件：先确认当前项目的base字段

Base UI 与 Radix 的 API 差异是由项目的原语库配置决定的，因此在写任何组件之前，第一步永远是确认当前项目用的是哪一种原语。

在 OpenWork 仓库中，Web 主应用的原语配置位于 apps/app/components.json：

{ "$schema": "https://ui.shadcn.com/schema.json", "style": "base-luma", "rsc": false, "tsx": true, "tailwind": { "config": "", "css": "src/app/index.css", "baseColor": "neutral", "cssVariables": true, "prefix": "" }, "iconLibrary": "lucide", "rtl": true, "aliases": { "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui", "lib": "@/lib", "hooks": "@/hooks" }, "registries": { "@ai-elements": "https://ai-sdk.dev/elements/api/registry/{name}.json" } }

style: "base-luma"中的base前缀即表明该项目采用 Base UI 原语。根据 .opencode/skills/shadcn/cli.md 中对npx shadcn@latest info输出字段的说明，base字段（取值为radix或base）直接决定组件 API 与可用 props。官方推荐的标准做法是运行：

npx shadcn@latest info

从输出的base字段判断当前项目的原语类型（该命令还同时返回framework、tailwindVersion、aliases、iconLibrary、packageManager等关键配置）。在 OpenWork 中，几乎所有 UI 组件都直接导入@base-ui/react原语，例如 select.tsx 中import { Select as SelectPrimitive } from "@base-ui/react/select"，说明该仓库实际运行在 Base UI 之上。

注意：技能规则明确要求使用项目对应的包管理器运行 CLI——OpenWork 是 pnpm monorepo，应使用pnpm dlx shadcn@latest ...，而非npx shadcn@latest ...（见 .opencode/skills/shadcn/SKILL.md 中的 IMPORTANT 说明）。

组合模式：asChild（Radix）vsrender（Base）

两者最根本的组合差异在于替换默认渲染元素的方式：

• Radix使用asChild，要求子元素必须是可接收 ref 的单元素，由子元素继承触发语义；
• Base使用render，以 props 形式传入目标元素，被替换的元素自身保留在 JSX 中并接收合并后的 props。

无论哪种原语，共同铁律都是：不要在触发器外再包裹多余的元素。

错误写法（两种原语通用）：

<DialogTrigger> <div> <Button>Open</Button> </div> </DialogTrigger>

多包一层<div>会破坏触发器的 ref 转发链，导致点击区域错位、无障碍语义丢失。

正确写法（Radix）：

<DialogTrigger asChild> <Button>Open</Button> </DialogTrigger>

正确写法（Base）：

<DialogTrigger render={<Button />}>Open</DialogTrigger>

注意 Base 中render={<Button />}是直接替换，文字Open作为DialogTrigger的 children 传入。

这一规则适用于所有 trigger 与 close 类组件，包括：DialogTrigger、SheetTrigger、AlertDialogTrigger、DropdownMenuTrigger、PopoverTrigger、TooltipTrigger、CollapsibleTrigger、DialogClose、SheetClose、NavigationMenuLink、BreadcrumbLink、SidebarMenuButton、Badge、Item。

在 OpenWork 源码中可以找到大量render组合的实例，例如 select.tsx 中触发器内置的下拉箭头：

<SelectPrimitive.Icon render={ <ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground ..." /> } />

以及 select.tsx 中SelectPrimitive.ItemIndicator通过render注入定位用<span>的写法。这说明在 Base 原语下，连原语内部部件也是通过render完成元素替换的。

Button / Trigger 渲染为非按钮元素：Base 需显式声明nativeButton={false}

Button默认渲染为原生<button>，并通过原生按钮语义（空格/回车激活、表单提交等）工作。当 Base 的render将元素替换为非按钮元素（如<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）：Radix 的asChild天然接管元素语义，无需额外标记。

<Button asChild> <a href="/docs">Read the docs</a> </Button>

同样的约束适用于render目标不是Button的所有触发器，例如用输入框前缀装饰件做触发器：

// base. <PopoverTrigger render={<InputGroupAddon />} nativeButton={false}> Pick date </PopoverTrigger>

在 OpenWork 中，nativeButton同样被用于真实业务代码，例如 ollama-config.tsx 中的设置项即使用了该属性。从源码结构可以推断：只要render的目标不是按钮元素，Base 都需要这个显式标记来关闭原生按钮行为。

Select：itemsprop 与占位符（placeholder）的处理差异

Select是 Base 与 Radix 差异最大的组件，主要分歧点有三个：数据来源、占位符、内容定位。

items prop（仅 Base）

Base 要求根节点Select必须提供items数组作为数据源；Radix 只使用内联 JSX，不需要额外数据源。

错误写法（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>

占位符（Placeholder）

Base 的占位符是items数组中的一个{ label, value: null }项，配合SelectValue的 render-function 展示；Radix 则直接使用<SelectValue placeholder="...">属性。上面的例子中，Base 版本的items[0]（value: null）即承担占位符角色。

内容定位（Content positioning）

Base 使用alignItemWithTrigger控制下拉面板是否与触发器对齐；Radix 使用position指定定位模式（popper等）。

// base. <SelectContent alignItemWithTrigger={false} side="bottom"> // radix. <SelectContent position="popper">

OpenWork 的 select.tsx 恰好完整印证了 Base 的这套 API：SelectContent接收side、sideOffset、align、alignOffset、alignItemWithTrigger等定位 props，并将其透传给SelectPrimitive.Positioner，最终由SelectPrimitive.Popup渲染弹层。这正是规则中alignItemWithTrigger（Base）对应position（Radix）的底层实现依据。

Select 高级能力：多选与对象值（仅 Base）

Base 还提供两项 Radix 不具备的能力：

• multiple多选：配合defaultValue={[]}，SelectValue的 children 可以是 render function，接收string[]并自定义展示文本；
• 对象值：通过itemToStringValue将对象序列化为可比较的字符串值，SelectValue的 render function 直接拿到原始对象。

多选（Base）：

<Select items={items} multiple defaultValue={[]}> <SelectTrigger> <SelectValue> {(value: string[]) => value.length === 0 ? "Select fruits" : `${value.length} selected`} </SelectValue> </SelectTrigger> ... </Select>

对象值（Base）：

<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}> <SelectTrigger> <SelectValue>{(value) => value.name}</SelectValue> </SelectTrigger> ... </Select>

Radix 的 Select 是仅字符串值的单选组件，不存在上述 props。如果你的应用（如 OpenWork 的模型选择器）需要把整个配置对象作为选项值传递，Base 原语是唯一可行方案。

ToggleGroup：multiple布尔属性 vstype枚举

Base 用布尔属性multiple表达多选模式，单选时不写任何属性；Radix 则用type="single" | "multiple"显式声明。另一个关键差异是defaultValue的类型：Base 的defaultValue永远是数组（即使单选），Radix 单选时是字符串、多选时是数组。

错误写法（Base）：混用了 Radix 的type="single"。

<ToggleGroup type="single" defaultValue="daily"> <ToggleGroupItem value="daily">Daily</ToggleGroupItem> </ToggleGroup>

正确写法（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>

正确写法（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 受控时需要在数组与标量之间手动转换；Radix 直接使用字符串。

// 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 的spacingprop 是通用的（上面的 Radix 示例同样出现了spacing={2}），但模式与取值类型必须严格按原语区分。OpenWork 在 .opencode/skills/shadcn/SKILL.md 的关键模式中也将ToggleGroup列为 2–5 个选项切换的首选组件，因此这套差异在真实表单开发中会频繁遇到。

Slider：标量 vs 数组

单滑块时，Base 直接接受标量数值（number），Radix 则永远要求数组（每个 thumb 一个元素）；两者在 range（双滑块）模式下都用数组。

错误写法（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} />

受控onValueChange时，Base 的类型收窄可能比数组类型更严格，必要时需要一次类型断言：

// 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} />

Accordion：type/collapsiblevsmultiple与数组 defaultValue

Radix 的Accordion必须声明type="single"或type="multiple"，并支持collapsible（允许全部收起），单选时defaultValue为字符串。Base 没有typeprop：单/多选由布尔属性multiple控制，且defaultValue恒为数组；Base 默认即可全部收起（对应 Radix 的collapsible语义）。

错误写法（Base）：照搬 Radix 的type="single" collapsible defaultValue="item-1"。

<Accordion type="single" collapsible defaultValue="item-1"> <AccordionItem value="item-1">...</AccordionItem> </Accordion>

正确写法（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>

正确写法（Radix）：

<Accordion type="single" collapsible defaultValue="item-1"> <AccordionItem value="item-1">...</AccordionItem> </Accordion>

从 OpenWork 的 accordion.tsx 导入@base-ui/react的情况可以推断，该仓库的 Accordion 实际使用 Base API——写代码时应使用defaultValue={["item-1"]}数组形式，而不是 Radix 的字符串形式。

速查表与迁移建议

迁移要点总结：

1. 先查base字段：用npx/pnpm dlx shadcn@latest info或直接查看 apps/app/components.json，确定项目运行在 Base 还是 Radix 原语上，再决定使用哪套 API；
2. 组合优先用对原语：Base 项目统一用render并留意nativeButton={false}，Radix 项目统一用asChild，两者都禁止在触发器外包裹多余元素；
3. 数组语义是核心差异：ToggleGroup、Slider、Accordion 三者的defaultValue类型和单选/多选表达方式在原语间完全不同，迁移时最容易出错；
4. 复用 OpenWork 现有实现：仓库中 apps/app/src/components/ui 下的组件（如 select.tsx、accordion.tsx、dialog.tsx 等）全部以@base-ui/react为基础，是 Base API 用法的现成参照。

当在两个原语之间迁移组件时，逐项对照上表检查即可；若需预览某个组件在另一原语下的 API，可运行npx shadcn@latest docs <component>获取对应文档与示例 URL（详见 .opencode/skills/shadcn/cli.md）。

【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork