# shadcn/ui ## 概述指南使用 shadcn/ui 作为代码生成平台（不是 npm 依赖项）构建可访问、可自定义的 UI。组件通过 CLI 复制到您的项目中并完全拥有。支持 Radix UI 或 Base UI 原语、带有 oklch 颜色标记的 Tailwind CSS 4、React 19 直接引用模式以及使用 Field 组件和 Zod 的类型安全表单验证。 **何时使用：** 添加 shadcn/ui 组件、使用 CSS 变量和 oklch 颜色进行主题化、使用 React Hook Form 或 TanStack Form 构建表单、创建自定义注册表、编写可访问的组件变体、设置暗模式。 **何时不使用：** 非 React 框架（使用 shadcn-vue 或 shadcn-svelte 代替）、使用不同组件库（MUI、Chakra）的项目、不使用 Tailwind CSS 的项目。 ## 快速参考图案| API / 方法 |要点 ---|---|--- 初始化项目| `npx shadcn@latest init` |自动检测框架，配置CSS变量添加组件 | `npx shadcn@最新添加 [名称]` |将源代码复制到您的项目中定制项目 | `npx shadcn@最新创建` |选择库（Radix/Base UI）、样式、主题、字体检查更新 | `npx shadcn@latest diff [组件]` |显示组件的上游更改搜索注册表 | `npx shadcn@最新搜索@registry` |从命名空间注册表浏览并安装构建注册表| `npx shadcn@最新版本` |从“registry.json”生成注册表 JSON 主题代币 | `:root` vars + `@theme inline` 映射 | oklch 颜色值，通过 `.dark` 类的深色模式深色模式 | `@custom-variant dark (&:is(.dark *))` |在 `.dark` 选择器下交换 CSS 变量组件变体 |来自“类方差权威”的“cva()” |类型安全的变体定义多态槽 |来自 Radix | 的带有 `` 的 `asChild` 属性将 props 合并到子元素上直接参考| `ref` 作为常规 prop | React 19 中已弃用 `forwardRef` 表格（当前）| `` \+ React Hook 表单 + Zod |替换旧版“

”组件表格（旧版）| `` \+ `` \+ Zod |仍然有效，但不再积极开发类合并| `cn()` 实用程序包装 `clsx` \+ `twMerge` |安全地合并 Tailwind 类而不会发生冲突吐司/通知| Sonner (`npx shadcn@latest add sonner`) |默认通知方式；自动消除、堆叠用块初始化 | `npx shadcn@latest init sidebar-01` |带有预构建页面块的 Bootstrap 项目 RTL 支持 |根元素上的 `dir="rtl"` |对所有组件的内置 RTL 布局支持新组件 | `Spinner`、`Kbd`、`ButtonGroup` |最近添加的实用程序和布局组件 ## 常见错误错误|正确的模式 ---|--- 安装 shadcn/ui 作为 npm 依赖项 |使用 CLI (`npx shadcn@latest add`) 将源代码复制到您的项目中将 `forwardRef` 与 React 19 组件结合使用 |直接将 `ref` 作为 prop 传递——`forwardRef` 在 React 19 中已被弃用使用 HSL 值作为颜色标记 |使用 oklch 格式：`--primary: oklch(0.205 0 0)` 在实用程序中使用“hsl()”或“oklch()”包装变量 |直接引用 CSS 变量：`var(--primary)` 将令牌直接放入 `@theme {}` |使用 `:root` 作为值 + `@theme inline` 将它们映射到 Tailwind 将旧版“”用于新表单 |将 `` 组件与 React Hook Form 或 TanStack Form 一起使用跳过表单组件中的 Zod 验证 |始终将表单与 Zod 模式配对以进行类型安全验证使用“div”元素进行交互式控件 |使用 Radix 或 Base UI 原语实现语义 HTML 和可访问性修改`node_modules`中的组件 |组件位于您的源代码树中——直接拥有和定制使用旧的 CLI 命令 `shadcn-ui@canary` |对所有 CLI 操作使用“npx shadcn@latest” ## 代表团 * **组件发现和原始查找** ：使用“Explore”代理 * **主题迁移或多文件重构** : 使用 `Task` 代理 * **设计系统架构规划** : 使用 `Plan` 代理 * **注册表设置和分发** ：使用 `Task` 代理 > 如果“tanstack-form”技能可用，请将高级表单状态管理（数组字段、链接字段、异步验证）委托给它。如果“顺风”技能可用，请将实用程序类模式和设计令牌架构委托给它。 ## 参考文献 * [主题和深色模式]() * [组件模式和变体]() * [使用 Field、React Hook Form 和 Zod 形成模式]() * [CLI 和注册表]()

沙德恩用户界面

包含技能