198 lines
8.3 KiB
Markdown
198 lines
8.3 KiB
Markdown
---
|
||
name: component-scaffold
|
||
version: 4.1.0
|
||
description: "生成 Vue 3 SFC 组件脚手架，含单元测试和类型安全 Props。当需要新建组件、拆分子组件或创建复合组件时使用。管理端用 Element Plus，用户端用 Headless UI。"
|
||
requires: [vue-testing]
|
||
---
|
||
|
||
> ⚠️ 核心执行流程已在 `.cursor/rules/skill-component-scaffold.mdc` 中由 Cursor 自动注入。
|
||
> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
|
||
|
||
# Vue 3 Component Scaffold
|
||
|
||
> **⚠️ 前端识别**：生成组件前必须确认目标前端。
|
||
> - **管理端** (`Case-Database-Frontend-admin/`)：使用 Element Plus + Tailwind
|
||
> - **用户端** (`Case-Database-Frontend-user/`)：使用 Headless UI + Tailwind，**禁止 Element Plus**
|
||
|
||
## 触发条件
|
||
|
||
用户要求创建新的 Vue 组件、页面组件、UI 元素或交互模块。
|
||
|
||
## 执行流程
|
||
|
||
### 0. 加载规范（⚠️ 必须最先执行）
|
||
|
||
依次读取 `.cursor/rules/010-typescript.mdc`、`.cursor/rules/011-vue.mdc`、`.cursor/rules/019-modular.mdc`，提取类型注解要求（隐式 any 禁令、ref 泛型规范、Composable 类型规范）、script setup、defineProps/Emits、组件分类、拆分阈值、Composable 提取规则。
|
||
|
||
> **Tier 3**：Vue 3 完整 API 见 `references/vue-api-reference.md`。
|
||
|
||
### 0.5 ⚠️ 生成前强制结构规划（禁止跳过）
|
||
|
||
**写代码前必须先输出文件结构和组件职责说明。**
|
||
|
||
#### A. 检查是否已有可复用的基础组件
|
||
|
||
在生成新组件前，先扫描以下路径，**避免重复造轮子**：
|
||
- `src/components/core/` — 通用基础组件（按钮、输入框、卡片等）
|
||
- `src/components/custom/` — 业务定制组件
|
||
|
||
若已有 `FormInput.vue`、`BaseCard.vue` 等，**直接复用，不重新生成**。
|
||
|
||
#### B. 用户端表单输入：优先复用 FormInput 模式
|
||
|
||
用户端页面中表单输入框若出现 ≥3 个，必须使用 `FormInput` 基础组件：
|
||
|
||
```vue
|
||
<!-- src/components/core/FormInput/FormInput.vue -->
|
||
<script setup>
|
||
defineProps({
|
||
modelValue: { type: String, default: '' },
|
||
type: { type: String, default: 'text' },
|
||
placeholder: { type: String, default: '' },
|
||
icon: { type: Object, default: null }, // Lucide 图标组件
|
||
disabled: { type: Boolean, default: false },
|
||
error: { type: String, default: '' },
|
||
})
|
||
defineEmits(['update:modelValue'])
|
||
</script>
|
||
|
||
<template>
|
||
<div class="relative">
|
||
<component :is="icon" v-if="icon"
|
||
class="absolute left-3 top-1/2 -translate-y-1/2 text-gray-400 dark:text-gray-500 w-5 h-5" />
|
||
<input
|
||
:type="type"
|
||
:value="modelValue"
|
||
:placeholder="placeholder"
|
||
:disabled="disabled"
|
||
@input="$emit('update:modelValue', $event.target.value)"
|
||
:class="[
|
||
'w-full border-b py-3 outline-none transition-colors',
|
||
icon ? 'pl-10 pr-4' : 'px-4',
|
||
'bg-transparent border-gray-300 dark:border-[#333333]',
|
||
'text-gray-900 dark:text-white placeholder:text-gray-400 dark:placeholder:text-gray-600',
|
||
'focus:border-[#C41E3A] dark:focus:border-[#C41E3A]',
|
||
error ? 'border-red-500' : '',
|
||
]"
|
||
data-testid="form-input"
|
||
/>
|
||
<p v-if="error" class="mt-1 text-xs text-red-500">{{ error }}</p>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
> 若项目中尚无 `FormInput`，在生成使用它的页面前先生成该核心组件。
|
||
|
||
#### C. 重复 UI 模式检测
|
||
|
||
检查需求中是否存在重复结构：
|
||
|
||
| 场景 | 检测标准 | 操作 |
|
||
|------|---------|------|
|
||
| 表单输入项 | ≥3 个相同结构的 input 组 | 提取 `FormInput.vue` |
|
||
| 内容卡片 | ≥3 个相同布局的卡片 | 提取 `CaseCard.vue` / `DesignerCard.vue` |
|
||
| 操作按钮组 | ≥2 处相同按钮组合 | 提取 `ActionGroup.vue` |
|
||
| 阶段/Tab 面板 | ≥2 个结构相同的面板 | 提取 `StagePanel.vue` |
|
||
|
||
#### D. 输出组件文件结构（代码前必须输出）
|
||
|
||
```
|
||
# 本次将生成以下文件：
|
||
src/components/<type>/<ComponentName>/
|
||
├── <ComponentName>.vue ← 主组件（目标 ≤ 120 行）
|
||
├── <ComponentName>.test.ts ← 单元测试
|
||
└── index.ts ← barrel export
|
||
|
||
# 依赖（已存在 / 需新建）：
|
||
- FormInput.vue: [已存在 / 需新建]
|
||
- BaseCard.vue: [已存在 / 不需要]
|
||
```
|
||
|
||
---
|
||
|
||
### 1. 确认组件规格
|
||
|
||
| 字段 | 必填 | 默认值 |
|
||
|------|------|--------|
|
||
| 组件名 | ✅ | — |
|
||
| 组件类型 | ❌ | UI 组件 |
|
||
| 所在目录 | ❌ | `src/components/` |
|
||
| Props / Emits | ❌ | 根据需求推断 |
|
||
|
||
类型与目录：`core`→`src/components/core/`、`custom`→`custom/`、`layout`→`layouts/`、`page`→`views/<module>/components/`、`form`→`custom/`。
|
||
|
||
### 2. 扫描项目模式
|
||
|
||
读取 `src/components/` 确认 Props 声明、样式方案、命名前缀约定、已有的 core 组件列表。
|
||
|
||
### 3. 生成文件结构
|
||
|
||
按步骤 0.5 输出的结构逐文件生成，**禁止将多个组件合并到一个文件**。
|
||
|
||
```
|
||
src/components/<type>/<ComponentName>/
|
||
├── <ComponentName>.vue
|
||
├── <ComponentName>.test.ts
|
||
└── index.ts
|
||
```
|
||
|
||
### 4. 组件模板
|
||
|
||
根据类型选择：基础 UI / 表格 / 表单对话框 / 复合组件。完整模板与设计决策树见 **Tier 3**。
|
||
|
||
**单组件行数限制**：
|
||
- template 区域 ≤ 80 行
|
||
- script 区域 ≤ 60 行（超出提取 composable）
|
||
- 整个 SFC ≤ 150 行（超出必须拆分子组件）
|
||
|
||
### 4.5 设计决策树（必须执行）
|
||
|
||
- ≥3 布尔 prop？→ 显式变体组件
|
||
- 多子组件共享状态？→ provide/inject
|
||
- script 逻辑 > 60 行？→ 提取 `use<ComponentName>.ts` composable（**必须遵循 `010-typescript.mdc` 的 Composable 类型规范**：参数有类型、`ref` 有泛型、业务类型用 `import type`）
|
||
- >2 处复用？→ `src/components/` + slot
|
||
- 同一 UI 结构重复 ≥3 次？→ 提取基础组件（见步骤 0.5C）
|
||
- 否则 → 基础 UI 模板
|
||
|
||
### 5. 测试与 Barrel export
|
||
|
||
测试至少包含渲染测试。`index.ts` 导出：`export { default as ComponentName } from './ComponentName.vue'`。详细测试见 `vue-testing` 技能。
|
||
|
||
## 验证
|
||
|
||
1. [ ] ESLint 无报错
|
||
2. [ ] Props 使用对象语法 `defineProps({ key: { type, default } })`，**若模板可直接访问 props 字段则不保存返回值**（避免 `unused-vars` 报错；仅当 script 中需要访问 `props.xxx` 时才保存：`const props = defineProps(...)`）
|
||
3. [ ] Emits 使用数组语法，事件名使用 camelCase（非 kebab-case）
|
||
4. [ ] 包含 `data-testid`
|
||
5. [ ] 测试至少一个渲染测试
|
||
6. [ ] 管理端：Element Plus 用于组件，Tailwind 用于布局；用户端：Headless UI + Tailwind（禁止 Element Plus）
|
||
7. [ ] barrel export 正确
|
||
8. [ ] **单 SFC ≤ 150 行**
|
||
9. [ ] **重复 UI 结构（≥3 次）已提取为基础组件**
|
||
10. [ ] **表单输入 ≥3 个已复用 FormInput.vue**（用户端）
|
||
11. [ ] **子组件模板中无 `v-model` 直接绑定 prop 嵌套属性**（参见 `011-vue.mdc` Props 数据流模式）
|
||
12. [ ] **提取的 composable（use*.ts）参数有类型注解、`ref([])` / `ref(null)` 有泛型标注**（参见 `010-typescript.mdc` Composable 类型规范）
|
||
|
||
### Red Flags（触发则停止并重构）
|
||
|
||
- ❌ 未输出文件结构直接写代码 → 停止，先输出步骤 0.5D 的结构
|
||
- ❌ 单 SFC > 150 行 → 拆分子组件
|
||
- ❌ 相同 Tailwind 输入框结构写了 ≥3 次 → 提取 FormInput.vue
|
||
- ❌ Options API → 改用 `<script setup>`
|
||
- ❌ `const props = defineProps(...)` 但 script 中从不访问 `props.xxx` → 去掉 `const props =`，避免 `unused-vars` lint 报错
|
||
- ❌ `catch (e) { ... }` 但 catch 块中不使用 `e` → 改为 `catch { ... }`（无参 catch），避免 `unused-vars` 报错
|
||
- ❌ 直接修改 props → 通过 emit（含隐蔽变体：`v-model="prop.field"`、`v-model="prop[key]"`、事件回调中 `prop[k] = v`）
|
||
- ❌ watch deep:true 滥用 → 精准监听
|
||
- ❌ script 逻辑 > 60 行未提取 → 拆分为 use*.ts
|
||
- ❌ composable 参数无类型 / `ref([])` 无泛型 → 补全类型注解（`strict: true` 下必报错）
|
||
- ❌ ≥3 布尔 prop 控制渲染 → 拆分变体
|
||
- ❌ prop drilling 传递同状态 → 改用 provide/inject
|
||
|
||
## Tier 3 深度参考
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `references/component-templates.md` | 基础/表格/表单/复合组件模板、决策树、Prop 反模式、错误处理、UI 反模式 |
|
||
| `references/vue-api-reference.md` | Vue 3 完整 API 索引 |
|
||
| `references/naming-conventions.md` | 组件命名规范 |
|