用途:shadcn/ui 是一个用于构建 UI、组件和设计系统的框架,组件以源代码形式通过 CLI 添加到用户项目中,便于直接修改和组合。
主要能力:通过 CLI 执行组件添加、搜索、查看文档、预览变更和预设应用;支持社区注册表(如 @magicui 等)中的组件;提供项目上下文(配置、已安装组件、别名、框架、图标库等),并附带组件文档与示例 URL。
使用方式:命令必须使用项目的包运行器,即 npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest。常用命令包括:npx shadcn@latest info --json 获取项目上下文;npx shadcn@latest docs <component> 获取文档与示例 URL;npx shadcn@latest search 搜索注册表;npx shadcn@latest add 添加组件;npx shadcn@latest apply <code> 应用预设;npx shadcn@latest preset decode/resolve 等处理预设。
设计原则:优先复用已有组件和内置变体,使用语义化颜色,采用组合而非重造;使用 flex+gap-* 而非 space-x-;用 size- 表示等宽高;表单使用 FieldGroup+Field;图标通过 data-icon 传入且不加尺寸类;Dialog、Sheet、Drawer 必须有标题。
适用场景:React 项目中构建管理后台、仪表盘、设置页等界面;需要可定制组件代码而非依赖包时。
限制:需在用户项目目录内执行预设命令;apply 仅适用于已有 components.json 的项目;更新组件时应使用 --dry-run 和 --diff 智能合并,未经用户明确同意不得使用 --overwrite;添加社区注册表组件后需手动修正硬编码导入路径和图标库。