coss Accordion 组件实战指南从安装、受控展开到 Radix 迁移【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app本指南以开源仓库 coss skill 参考文档 为核心系统讲解 coss 组件体系中 Accordion手风琴/可展开多区块内容区的安装方式、规范导入、最小实现、多面板展开与受控模式并结合本仓库中真实的 site 端实现 与 web 端实现 深入剖析其底层原理与常见陷阱。读完本文你将掌握如何在 React Tailwind CSS v4 Base UI 项目中正确搭建、定制和迁移 coss Accordion并规避从 Radix/shadcn 迁移时最容易踩的坑。何时使用 coss AccordionAccordion 用于组织可展开的多区块内容区域是渐进式披露progressive disclosure的典型载体。根据原文档accordion.md它适合两类典型场景可展开的多区块内容例如长文档的分节导航、配置面板中按类别收纳的设置项FAQ 与设置页需要把大量问答或选项压缩进有限空间用户按需展开查看。与之相对若只需要一个独立的展开/收起区域无多条目联动应优先考虑 collapsible 原语若需要多标签页互斥切换面板则应选用 tabs 原语。组件选型可对照 component-registry.md 中的索引快速决策。安装CLI 一键添加与手动依赖方式一shadcn CLI 添加推荐在项目根目录需已配置 shadcn 与 Tailwind CSS v4执行npx shadcnlatest add coss/accordion根据 coss CLI 参考项目使用 pnpm 或 bun 时应始终使用对应的包运行器避免全局二进制版本漂移pnpm dlx shadcnlatest add coss/accordion bunx --bun shadcnlatest add coss/accordion建议在正式写入前使用预览模式确认改动范围组件可能已存在于本地或你只想先检查将要生成的文件npx shadcnlatest add coss/accordion --dry-run npx shadcnlatest add coss/accordion --diff npx shadcnlatest add coss/accordion --view方式二手动安装依赖CLI 之外的手动安装路径核心是按组件文档安装其声明的最小依赖。Accordion 的运行时依赖是 Base UI 的 React 包npm install base-ui/react安装完成后将本仓库 apps/site/components/ui/accordion.tsx或 web 端 apps/web/src/components/ui/accordion.tsx中导出的四个组件复制到你自己项目的components/ui/accordion.tsx并把/lib/cn等导入别名替换为项目实际的别名配置。手动安装注意事项见 cli.mdCLI 方式会自动接线所需的主题 token手动方式若涉及destructive-foreground、info、success、warning等颜色家族需要自行从 coss 样式文档补齐对应 token。规范导入无论哪种安装方式组件文件最终都从项目的 ui 目录导出以下四个成员import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, } from /components/ui/accordion对照仓库源码 apps/site/components/ui/accordion.tsx 可以看到导出集合与文档完全一致Accordion根、AccordionItem条目、AccordionTrigger触发器、AccordionPanel内容面板并且额外以别名AccordionContent导出AccordionPanel兼容 Radix 时代的命名习惯。最小模式一个可展开的条目Accordion defaultValue{[item-1]} AccordionItem valueitem-1 AccordionTriggerWhat is Base UI?/AccordionTrigger AccordionPanel Base UI is a library of high-quality unstyled React components. /AccordionPanel /AccordionItem /Accordion要点拆解Accordion接收字符串数组形式的defaultValue这与 Base UI 的受控模型一致——即便只有一个面板也要写成数组[item-1]每个AccordionItem必须有稳定且唯一的value它是条目身份标识也是受控行为的依据AccordionTrigger与AccordionPanel必须是同一个AccordionItem的直接子级不能跨条目混放。源码实现印证从仓库组件实现apps/site/components/ui/accordion.tsx可以看到Accordion直接透传AccordionPrimitive.Root的全部 props并挂上data-slotaccordion供 Tailwind v4 样式选择器定位AccordionTrigger内部用AccordionPrimitive.Header包裹真实按钮并附带一个旋转指示器ChevronDownIcon见 第 28-42 行AccordionPanel则通过--accordion-panel-height变量与transition-[height]实现展开/收起的高度动画见 第 47-61 行。这意味着你使用四个组件时开箱即获得无障碍语义Header 按钮结构、键盘焦点环与平滑动画无需自行实现。进阶模式多开、受控与数据映射多面板同时展开默认不传multiple时 Accordion 为单开模式展开新面板会收起旧面板。若需要多个面板同时保持展开显式传入multiple并给出多个默认值Accordion multiple defaultValue{[item-1, item-2]} AccordionItem valueitem-1 AccordionTriggerSection 1/AccordionTrigger AccordionPanelContent 1/AccordionPanel /AccordionItem AccordionItem valueitem-2 AccordionTriggerSection 2/AccordionTrigger AccordionPanelContent 2/AccordionPanel /AccordionItem /Accordion受控模式外部状态驱动当需要由外部逻辑如全部展开按钮、URL 参数同步、搜索高亮定位驱动面板状态时使用valueonValueChange完全受控const [value, setValue] useStatestring[]([item-1]) Accordion value{value} onValueChange{setValue} {/* items... */} /Accordion再次强调受控value永远是string[]而不是单个字符串或布尔值。这一约定与 Base UI 的 Accordion API 完全一致也是从 Radix 迁移时最常见的认知断层。数据映射mapped items模式配合value数组最常见的生产形态是遍历数据源批量渲染条目const faqs [ { id: q1, question: How does coss work?, answer: ... }, { id: q2, question: Is it accessible?, answer: ... }, ]; Accordion multiple defaultValue{faqs.map((f) f.id)} {faqs.map((f) ( AccordionItem key{f.id} value{f.id} AccordionTrigger{f.question}/AccordionTrigger AccordionPanel{f.answer}/AccordionPanel /AccordionItem ))} /Accordion该模式对应粒子示例p-accordion-1mapped items、p-accordion-2单开静态区块、p-accordion-3多开行为、p-accordion-4受控 value 外部动作完整列表见 accordion.md。从 Radix / shadcn 迁移模型差异对照coss 的 Accordion 与 Radix 版本在 API 表面上高度相似但状态模型不同。根据 migration.md 中的对照模板// shadcn/Radixtypesingle collapsible 字符串 defaultValue Accordion typesingle collapsible defaultValueitem-1 AccordionItem valueitem-1.../AccordionItem /Accordion // coss/Base UImultiple 布尔值 数组 defaultValue Accordion defaultValue{[item-1]} AccordionItem valueitem-1.../AccordionItem /Accordion迁移时只需记住三个等价替换Radix 心智模型coss / Base UI 模型typesingle/typemultiple布尔属性multiple缺省即 singledefaultValueitem-1字符串defaultValue{[item-1]}字符串数组受控value为标量受控value恒为string[]此外coss 迁移规则migration.md强调不要假设所有 shadcn 模式都能 1:1 平移对触发器类组件要逐原语核对文档中的 trigger/content 层级asChild仅在明确支持render的部件上替换为render。常见陷阱清单原文档accordion.md归纳了四个高频错误全部可在仓库实现中找到对应约束把AccordionTrigger/AccordionPanel放在AccordionItem之外——破坏条目的子级结构导致状态无法归属到对应条目实现见 apps/site/components/ui/accordion.tsx在AccordionItem上省略value——条目失去身份标识展开状态无法追踪受控模式直接失效套用 Radix 的typesingle | multiple心智——coss 用布尔multiple 数组值混用会产生类型错误或行为异常把受控value当成标量——必须使用string[]否则受控行为不成立。自检清单在提交 coss Accordion 代码前对照 SKILL.md 的输出清单逐项确认导入路径与导出成员与组件文档一致Accordion/AccordionItem/AccordionPanel/AccordionTrigger每个AccordionItem都有稳定唯一的valueTrigger与Panel是同一 item 的子级受控用法使用string[]类型的valueonValueChange无障碍结构完整AccordionTrigger内含Header可键盘操作焦点环样式保留迁移代码已用迁移规则核对migration.md未保留type等 Radix 专属 props。按此清单核对后coss Accordion 即可安全落地到 FAQ、设置页等渐进式披露场景并获得与仓库 site / web 实现一致的体验质量。【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考