OpenWork 中的 shadcn/ui 组件开发指南Base UI 与 Radix 的 API 差异对照与迁移实战【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openworkOpenWorkopencode 驱动的开源 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 shadcnlatest info输出字段的说明base字段取值为radix或base直接决定组件 API 与可用 props。官方推荐的标准做法是运行npx shadcnlatest 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 shadcnlatest ...而非npx shadcnlatest ...见 .opencode/skills/shadcn/SKILL.md 中的 IMPORTANT 说明。组合模式asChildRadixvsrenderBase两者最根本的组合差异在于替换默认渲染元素的方式Radix使用asChild要求子元素必须是可接收 ref 的单元素由子元素继承触发语义Base使用render以 props 形式传入目标元素被替换的元素自身保留在 JSX 中并接收合并后的 props。无论哪种原语共同铁律都是不要在触发器外再包裹多余的元素。错误写法两种原语通用DialogTrigger div ButtonOpen/Button /div /DialogTrigger多包一层div会破坏触发器的 ref 转发链导致点击区域错位、无障碍语义丢失。正确写法RadixDialogTrigger asChild ButtonOpen/Button /DialogTrigger正确写法BaseDialogTrigger 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 classNamepointer-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正确写法BaseButton render{a href/docs /} nativeButton{false} Read the docs /Button正确写法RadixRadix 的asChild天然接管元素语义无需额外标记。Button asChild a href/docsRead the docs/a /Button同样的约束适用于render目标不是Button的所有触发器例如用输入框前缀装饰件做触发器// base. PopoverTrigger render{InputGroupAddon /} nativeButton{false} Pick date /PopoverTrigger在 OpenWork 中nativeButton同样被用于真实业务代码例如 ollama-config.tsx 中的设置项即使用了该属性。从源码结构可以推断只要render的目标不是按钮元素Base 都需要这个显式标记来关闭原生按钮行为。Selectitemsprop 与占位符placeholder的处理差异Select是 Base 与 Radix 差异最大的组件主要分歧点有三个数据来源、占位符、内容定位。items prop仅 BaseBase 要求根节点Select必须提供items数组作为数据源Radix 只使用内联 JSX不需要额外数据源。错误写法Base缺少items。Select SelectTriggerSelectValue placeholderSelect a fruit //SelectTrigger /Select正确写法Baseconst 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正确写法RadixSelect SelectTrigger SelectValue placeholderSelect a fruit / /SelectTrigger SelectContent SelectGroup SelectItem valueappleApple/SelectItem SelectItem valuebananaBanana/SelectItem /SelectGroup /SelectContent /Select占位符PlaceholderBase 的占位符是items数组中的一个{ label, value: null }项配合SelectValue的 render-function 展示Radix 则直接使用SelectValue placeholder...属性。上面的例子中Base 版本的items[0]value: null即承担占位符角色。内容定位Content positioningBase 使用alignItemWithTrigger控制下拉面板是否与触发器对齐Radix 使用position指定定位模式popper等。// base. SelectContent alignItemWithTrigger{false} sidebottom // radix. SelectContent positionpopperOpenWork 的 select.tsx 恰好完整印证了 Base 的这套 APISelectContent接收side、sideOffset、align、alignOffset、alignItemWithTrigger等定位 props并将其透传给SelectPrimitive.Positioner最终由SelectPrimitive.Popup渲染弹层。这正是规则中alignItemWithTriggerBase对应positionRadix的底层实现依据。Select 高级能力多选与对象值仅 BaseBase 还提供两项 Radix 不具备的能力multiple多选配合defaultValue{[]}SelectValue的 children 可以是 render function接收string[]并自定义展示文本对象值通过itemToStringValue将对象序列化为可比较的字符串值SelectValue的 render function 直接拿到原始对象。多选BaseSelect items{items} multiple defaultValue{[]} SelectTrigger SelectValue {(value: string[]) value.length 0 ? Select fruits : ${value.length} selected} /SelectValue /SelectTrigger ... /Select对象值BaseSelect defaultValue{plans[0]} itemToStringValue{(plan) plan.name} SelectTrigger SelectValue{(value) value.name}/SelectValue /SelectTrigger ... /SelectRadix 的 Select 是仅字符串值的单选组件不存在上述 props。如果你的应用如 OpenWork 的模型选择器需要把整个配置对象作为选项值传递Base 原语是唯一可行方案。ToggleGroupmultiple布尔属性 vstype枚举Base 用布尔属性multiple表达多选模式单选时不写任何属性Radix 则用typesingle | multiple显式声明。另一个关键差异是defaultValue的类型Base 的defaultValue永远是数组即使单选Radix 单选时是字符串、多选时是数组。错误写法Base混用了 Radix 的typesingle。ToggleGroup typesingle defaultValuedaily ToggleGroupItem valuedailyDaily/ToggleGroupItem /ToggleGroup正确写法Base// 单选无需任何模式属性defaultValue 恒为数组。 ToggleGroup defaultValue{[daily]} spacing{2} ToggleGroupItem valuedailyDaily/ToggleGroupItem ToggleGroupItem valueweeklyWeekly/ToggleGroupItem /ToggleGroup // 多选。 ToggleGroup multiple ToggleGroupItem valueboldBold/ToggleGroupItem ToggleGroupItem valueitalicItalic/ToggleGroupItem /ToggleGroup正确写法Radix// 单选defaultValue 为字符串。 ToggleGroup typesingle defaultValuedaily spacing{2} ToggleGroupItem valuedailyDaily/ToggleGroupItem ToggleGroupItem valueweeklyWeekly/ToggleGroupItem /ToggleGroup // 多选。 ToggleGroup typemultiple ToggleGroupItem valueboldBold/ToggleGroupItem ToggleGroupItem valueitalicItalic/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 typesingle value{value} onValueChange{setValue}注意 Base 的spacingprop 是通用的上面的 Radix 示例同样出现了spacing{2}但模式与取值类型必须严格按原语区分。OpenWork 在 .opencode/skills/shadcn/SKILL.md 的关键模式中也将ToggleGroup列为 2–5 个选项切换的首选组件因此这套差异在真实表单开发中会频繁遇到。Slider标量 vs 数组单滑块时Base 直接接受标量数值numberRadix 则永远要求数组每个 thumb 一个元素两者在 range双滑块模式下都用数组。错误写法Base混用 Radix 的数组形式。Slider defaultValue{[50]} max{100} step{1} /正确写法BaseSlider defaultValue{50} max{100} step{1} /正确写法RadixSlider 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} /Accordiontype/collapsiblevsmultiple与数组 defaultValueRadix 的Accordion必须声明typesingle或typemultiple并支持collapsible允许全部收起单选时defaultValue为字符串。Base 没有typeprop单/多选由布尔属性multiple控制且defaultValue恒为数组Base 默认即可全部收起对应 Radix 的collapsible语义。错误写法Base照搬 Radix 的typesingle collapsible defaultValueitem-1。Accordion typesingle collapsible defaultValueitem-1 AccordionItem valueitem-1.../AccordionItem /Accordion正确写法BaseAccordion defaultValue{[item-1]} AccordionItem valueitem-1.../AccordionItem /Accordion // 多选。 Accordion multiple defaultValue{[item-1, item-2]} AccordionItem valueitem-1.../AccordionItem AccordionItem valueitem-2.../AccordionItem /Accordion正确写法RadixAccordion typesingle collapsible defaultValueitem-1 AccordionItem valueitem-1.../AccordionItem /Accordion从 OpenWork 的 accordion.tsx 导入base-ui/react的情况可以推断该仓库的 Accordion 实际使用 Base API——写代码时应使用defaultValue{[item-1]}数组形式而不是 Radix 的字符串形式。速查表与迁移建议能力点BaseRadix替换默认元素render{El /}asChild 子元素触发器替换为非按钮需加nativeButton{false}无需额外标记Select 数据源根节点必须itemsprop仅内联 JSXSelect 占位符items 中{ value: null }项SelectValue placeholder...Select 内容定位alignItemWithTriggerpositionSelect 多选 / 对象值支持multiple、itemToStringValue不支持仅单选、字符串值ToggleGroup 模式multiple布尔属性typesingle | multipleToggleGroup defaultValue恒为数组单选字符串 / 多选数组Slider 单 thumb 值标量number数组[n]Accordion 模式multiple布尔属性默认可全部收起typecollapsibleAccordion defaultValue恒为数组单选字符串 / 多选数组迁移要点总结先查base字段用npx/pnpm dlx shadcnlatest info或直接查看 apps/app/components.json确定项目运行在 Base 还是 Radix 原语上再决定使用哪套 API组合优先用对原语Base 项目统一用render并留意nativeButton{false}Radix 项目统一用asChild两者都禁止在触发器外包裹多余元素数组语义是核心差异ToggleGroup、Slider、Accordion 三者的defaultValue类型和单选/多选表达方式在原语间完全不同迁移时最容易出错复用 OpenWork 现有实现仓库中 apps/app/src/components/ui 下的组件如 select.tsx、accordion.tsx、dialog.tsx 等全部以base-ui/react为基础是 Base API 用法的现成参照。当在两个原语之间迁移组件时逐项对照上表检查即可若需预览某个组件在另一原语下的 API可运行npx shadcnlatest 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考