参照 shadcn 组件重构现有组件的视觉样式
审计现有组件的属性、状态与依赖,安装并解析 shadcn 参考组件的样式规范,仅调整渲染结构、样式类与动效,保留业务逻辑和对外接口,并交付重构文件、迁移说明与提供者补丁。
完整提示词
# shadcn Component Visual Adapter
## 🎯 Objective
重构位于 `${component_file_path}` 的现有 `${component_name}` 组件,使其匹配以下位置提供的参考组件的**视觉设计、结构和行为**:
> ${install_command:bunx --bun shadcn@latest add accordion}
${reference_url:} ← 可选;若无文档页面则留空
不要替换业务逻辑、现有 props 接口或数据获取模式。请保留它们。
仅适配**视觉层**:标记结构、类名、动画和可访问性属性。
---
## 📋 Step 1 — 分析现有组件
在编写任何代码之前:
1. 阅读 `${component_file_path}` 的完整源码。
2. 梳理以下内容:
- 所有**props 及其类型**(TypeScript 接口或 PropTypes)。
- 内部**状态变量**(`useState`、`useReducer`、Zustand slices 等)。
- 消费的**上下文提供者或自定义 Hook**。
- 渲染的**子组件**及其所在位置。
- 向父组件暴露的**事件处理器和回调函数**。
3. 列出每一个**导入项**——标记任何将与 shadcn 原语冲突或可被其替代的项。
在动代码前输出一个简要的审计表:
| 项目 | 当前值 | 操作 |
|------|--------------|--------|
| Props | ... | 保留 / 重命名 / 移除 |
| State | ... | 保留 / 迁移 |
| Context/Hooks | ... | 保留 / 替换 |
| 子组件 | ... | 保留 / 替换 |
| 依赖项 | ... | 保留 / 安装 / 移除 |
---
## 📦 Step 2 — 依赖解析
直接运行安装命令:
${install_command}
命令完成后,生成的文件将出现在
${components_dir:components/ui}/。使用这些文件进入 Step 3。
---
## 🔬 Step 3 — 查看参考组件
如果提供了 ${reference_url} → 获取该页面并像之前一样提取视觉规范。
如果 ${reference_url} 为空 → 直接阅读 Step 2 中 CLI 命令下载的文件,
并从源码中提取相同的信息:
- cva 变体模式
- data-state / data-disabled 属性
- 动画/过渡类
- ARIA 角色和属性
- cn() 使用模式
---
## 🛠 Step 4 — 重构组件
将 Step 3 中提取的视觉结构应用到 Step 1 的现有组件上。
### 规则:
- ✅ 保留所有**现有 prop 名称和类型**,除非存在直接对应的 shadcn 等价物。
- ✅ 保留所有**数据获取、业务逻辑和回调函数**。
- ✅ 使用 **`forwardRef`** 包装 Radix 原语,并展开 `...props` 以保持灵活性。
- ✅ 所有 className 合并使用 `cn()` —— 绝不使用字符串拼接。
- ✅ 如果参考组件使用了命名的复合子组件(如 `Accordion`、`AccordionItem`、`AccordionTrigger`、`AccordionContent`),则导出这些子组件。
- ❌ 不得导入生成的 shadcn 文件并重新导出——应在重构的文件中内联构建原语,以保持逻辑集中。
- ❌ 未经明确指示,不得添加参考组件中不存在的 Tailwind 类。
### 响应式行为(`${responsive_breakpoints:sm md lg}`):
应用移动优先的响应式类。确认 `tailwind.config.ts` 中的当前断点与项目约定一致。如果参考组件使用容器查询,请安装 `@tailwindcss/container-queries`。
---
## 🧩 Step 5 — 上下文提供者和 Hook
如果参考组件需要上下文提供者(例如 `ToastProvider`、`TooltipProvider`):
1. 检查其是否已挂载在 `${provider_file:app/layout.tsx}` 或 `${provider_file:app/providers.tsx}` 中。
2. 如果没有,请将其添加到适当的布局文件中。提供确切的 diff。
3. 如果需要自定义 Hook(例如 `useToast`、`useDialog`),请将其放置在 `${hooks_dir:hooks/}` 中,并从此处导入。
---
## ❓ Step 6 — 明确问题(未知时先提问)
如果以下任何一项无法从现有代码中确定,**请先提问再生成**:
1. **数据/props**:将传入的数据结构是什么?(如有帮助,请提供示例对象。)
2. **状态管理**:组件状态是局部的,还是外部管理的(Zustand、Redux、React Query)?
3. **资源**:是否有未被 lucide-react 覆盖的必需图像、标志或自定义图标?
4. **响应式**:在 `${responsive_breakpoints:sm md lg}` 断点处预期的布局是什么?
5. **位置**:此组件将位于应用路由/布局树的何处?(对上下文提供者的位置很重要。)
---
## 📐 Step 7 — 输出格式
提供以下结果:
1. **`${component_file_path}`** — 完整的重构后组件文件。
2. **`${components_dir:components/ui}/${shadcn_component_slug}.tsx`** — shadcn 原语(仅在需要且 CLI 未生成时提供)。
3. **`lib/utils.ts`** — 仅在需要创建或更新时提供。
4. **Layout/provider diff** — 仅在需要添加提供者时提供。
5. 一个简短的**迁移说明**部分,列出:
- 移除的依赖项
- 重命名的 props(如有)
- 任何所需的手动步骤(例如,将 CSS 变量添加到 `globals.css`)
## 🎨 Tailwind CSS 变量(shadcn 设计令牌)
确认 `globals.css` 包含所需的 CSS 自定义属性。如果参考组件使用了如 `--radius`、`--background`、`--foreground`、`--primary`、`--ring` 等令牌,请补全缺失的变量。除非项目中已定义自定义主题,否则使用 `${color_theme:zinc}` 的 shadcn 默认令牌集。
---
## 🚫 约束条件
- 框架:**${framework:Next.js 14+ App Router}**
- 样式:仅允许使用 **Tailwind CSS ${tailwind_version:3}** — 禁止内联样式、禁止 CSS 模块、禁止 styled-components。
- TypeScript:必须启用 **严格模式**。所有新增代码必须完整类型化。
- 除非存在直接的对等依赖冲突,否则不得升级或降级任何现有依赖版本。分类与标签
编程开发、编程开发、代码、分析