# 寒平 Kanpeki 是 React 的复制粘贴组件库。组件通过 shadcn CLI 复制到您的项目中（不作为 npm 包安装）。基于 **React Aria Components**（辅助功能）、**CVA beta**（变体）和 **Tailwind CSS 4.1**（样式）构建。文档： ## 快速入门 ### 1\.安装依赖项 npm install cva@beta tailwind-merge tailwindcss-motion tailwindcss-react-aria-组件react-aria-组件-D 删除 shadcn 默认值（如果存在）： npm 删除类方差权威 clsx tw-animate-css ### 2\.创建 CVA 实用程序 `src/lib/cva.ts`: 从“cva”导入{defineConfig}；从“tailwind-merge”导入{twMerge}；导出 const { cva, cx: cn, compose } = DefineConfig({ 钩子：{ onComplete: (className) => twMerge(className), }, }); ### 3\.配置样式添加到 `globals.css`：Tailwind 导入、插件（`tailwindcss-react-aria-components`、`tailwindcss-motion`）、`@custom-variant dark` 和通过 `@theme inline` 的 OKLCH 颜色标记。有关完整的 CSS，请参阅 [references/installation-setup.md]()。 ### 4\.添加组件 npx shadcn@latest 添加@kanpeki/button npx shadcn@latest 添加@kanpeki/dialog npx shadcn@latest 添加@kanpeki/field 组件被复制到`~/components/ui//`。您拥有该代码。 ## 组件架构每个组件都有：“index.ts”（导出）、“.tsx”（实现）、“styles.ts”（CVA 变体）。 ### 简单组件单一出口。示例：从“~/components/ui/button”导入{Button}；点击我 ### 多部分组件复合组件的命名空间导出：从“~/components/ui/dialog”导入{Dialog}； <对话框.根> <按钮>打开 <对话框覆盖> <对话框.模态> <对话框.内容> <对话框标题> 标题描述 <对话框页脚> <按钮>保存 <对话框.关闭/> 具有命名空间导出的多部分组件：Accordion、Breadcrumb、ButtonGroup、Calendar、Card、Carousel、Chart、Combobox、DateField、DatePicker、Dialog、Drawer、Field、InputGroup、ListBox、Menu、NumberField、Pagination、Popover、RadioGroup、Ressized、ScrollArea、SearchField、Select、Sheet、Sidebar、Slider、Table、Tabs、Toast、ToggleGroup、Tooltip。有关完整示例，请参阅 [references/component-patterns.md]()。 ### 关键模式：`composeRenderProps` 包装 React Aria 原语时，始终使用“react-aria-components”中的“composeRenderProps”。这可以确保基于状态的选择器（“pressed:”、“selected:”等）正常工作。从“react-aria-components”导入{ composeRenderProps }；类名={composeRenderProps(类名, (类名) => 样式({ 类名, 变体 }) )} 对于纯 HTML 元素（`div`、`p`），直接调用 CVA：`className={Styles({ className })}`。 ## 表单系统 3层架构：**表单** > **字段** > **输入组件**。 ### 字段构成从“~/components/ui/field”导入{Field}；从“~/components/ui/input”导入{输入}；从“~/components/ui/text-field”导入{ TextField }； }> <字段.标签>电子邮件 <输入占位符=“john@example.com”/> 帮助文本 <字段.错误/> `Field.Root` 的 `render` 属性连接到 React Aria 表单原语（TextField、Select、NumberField 等）以进行自动标签关联和验证。 ### 输入组从“~/components/ui/input-group”导入{InputGroup}； <输入组.根> ### TanStack 表格 {（字段）=>（ <字段.根渲染={ <文本字段 isInvalid={field.state.meta.isTouched && !field.state.meta.isValid} onChange={field.handleChange} onBlur={field.handleBlur} 值={字段.状态.值} /> } > <字段.标签>标题 <输入/> )} 请参阅 [references/form-system.md]() 了解带有 Zod 验证的完整 TanStack 表单示例。 ## 样式和主题 * **CVA** — `styles.ts` 中的变体定义。从 `~/lib/cva` 导入 `cva` （不是直接导入 `cva`）。 * **`cn()`** — 来自 `~/lib/cva` 的类合并实用程序。包裹`twMerge`。 * **OKLCH 颜色** — 通过 `@theme inline` 在 `globals.css` 中定义。使用“light-dark()”实现自动深色模式。 * **深色模式** — `next-themes`（类策略）+ CSS `light-dark()`。组件自动切换。 * **React Aria 选择器** — `pressed:`、`selected:`、`disabled:`、`entering:`、`exiting:`、`focus-visible:`。 * **动画** — `tailwindcss-motion` 插件：`motion-opacity-in`、`motion-scale-in-95`、`motion-duration-200`。通过传递 `className` （twMerge 解决冲突）或直接编辑 `styles.ts` 来覆盖样式。请参阅 [references/styling-and-theming.md]() 以获取完整的令牌参考和 CVA 深入研究。 ## 常见陷阱陷阱|修复 ---|--- 在 React Aria 组件上使用 `className={Styles(...)}`使用“composeRenderProps”——状态选择器必需的缺少“使用客户端”指令 |所有交互组件都需要它（React Aria 仅限客户端）从“cva”导入“cva” |从 `~/lib/cva` 导入 — 包括 `twMerge` 钩子安装了旧的 shadcn deps (`class-variance-authority`, `clsx`) |删除它们，使用 `cva@beta` \+ `tailwind-merge` 使用“active:”表示按下状态 |使用 `pressed:` — React Aria 前缀使用 `@/` 路径别名 | Kanpeki 使用 `~/` ## 组件列表安装任何组件：`npx shadcn@latest add @kanpeki/` **布局和结构：**卡片、分隔符、纵横比、可调整大小、滚动区域、侧边栏、可折叠、轮播 **表单输入：** 输入、文本区域、文本字段、数字字段、搜索字段、复选框、单选组、选择、组合框、自动完成、开关、滑块、日期字段、日期选择器、日历、input-otp、dropzone、字段、表单、输入组 **按钮和操作：**按钮、按钮组、链接、链接按钮、切换、切换组 **叠加：** 对话框、抽屉、工作表、弹出框、工具提示、菜单 **数据显示：**表格、列表框、手风琴、选项卡、头像、徽章、键盘、图表 **反馈：**警报、吐司、进度、旋转器、骨架 **导航：** 面包屑导航、分页 **实用程序：**标签 ## 参考文献 * [安装和设置]() — 完整 CSS、CVA 配置、深色模式、路径别名 * [组件模式]() — 按钮 + 对话框示例、命名空间模式、自定义 * [表单系统]() — Field/InputGroup/ButtonGroup API、TanStack Form + Zod 示例 * [样式和主题]() — CVA 深入研究、OKLCH 代币、React Aria 选择器、动画

官平

包含技能