# Vue Project Page Builder

> 先分析目标 Vue 项目，再按项目现有规范创建或修改页面、页面级组件和业务组件。适用于需要在现有项目中开发或调整 Vue 视图、路由页面、列表页、表单页、详情页等场景，并要求优先复用已有组件、遵循仓库现有目录结构与代码风格、避免另起一套写法，同时判断页面局部内容应保留在页面内还是抽成可复用组件。

- Skill: `hwm09110/vue-project-page-builder` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add hwm09110/vue-project-page-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hwm09110/vue-project-page-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: hwm09110 (https://skillmd.com/u/hwm09110)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hwm09110/vue-project-page-builder

---


# Vue 项目页面开发规范

开始写代码前先读项目。优先复用项目里已经存在的能力，再决定是否新增组件。页面实现必须贴合当前仓库的既有规范，而不是引入另一套新的开发风格。

除非用户明确要求使用其他语言，否则默认使用中文响应。

## 工作流程

### 1. 先建立项目上下文

至少读取下面这些内容，确认项目的实际开发方式：

- `package.json`
- Vite、Vue CLI、Nuxt 或其他构建配置
- `src/router/**` 或等价的路由注册位置
- `src/views/**`、`src/pages/**`、`src/components/**`
- 共享布局、表格、表单、弹窗、查询区、卡片、详情区相关组件
- `src/api/**`、`src/services/**`、`src/stores/**`、`src/composables/**`
- lint、prettier、stylelint、TypeScript、提交规范等配置
- 全局样式、主题变量、设计 token、工具类约定

优先确认这些关键信息：

- 项目使用的是 Vue 2 还是 Vue 3
- 项目以 Options API、Composition API 还是混合风格为主
- 项目使用的是 Element Plus、Ant Design Vue、Naive UI、Vant，还是内部组件库
- 页面常见结构模式，例如 `查询 + 表格 + 分页`、`Tabs + 详情`、`抽屉 + 表单`、`弹窗 + 表单`
- 接口请求、权限、枚举、字典等通用逻辑的处理方式

如果仓库里已经给出了答案，就优先遵循仓库做法，而不是套用通用最佳实践。

### 2. 从真实代码中归纳项目规范

不要凭经验猜“Vue 项目一般怎么写”。至少参考一个相似页面和一个相似可复用组件，再归纳规范。

重点检查并遵循：

- 文件与目录命名方式
- SFC 代码块顺序，例如 `template`、`script`、`style`
- 是否以 `script setup` 为主
- props、emits、refs、接口返回、表格行数据的 TypeScript 写法
- 事件命名、属性命名、`v-model` 约定
- 样式方案是 scoped SCSS、CSS Modules、工具类还是 design tokens
- 状态放在局部、composables、Pinia 还是 Vuex
- 接口调用是在页面内直接发起，还是走共享 service 层

如果任务较大或场景不明确，在正式改代码前先简要总结识别到的项目规范。

### 3. 按严格优先级复用现有组件

选择组件时按下面顺序优先：

1. 同业务语义的已有页面级区块
2. 同业务域下已有业务组件
3. 项目中已被多处使用的通用共享组件
4. 仓库中已成标准的第三方 UI 基础组件
5. 只有在复用明显不够时，才新建自定义组件

在创建新组件前，优先搜索：

- 相似表单
- 相似表格和列渲染
- 相似查询筛选区
- 相似卡片、列表、详情模块
- 相似弹窗、抽屉、上传、选择器、树选择器

如果已有组件不完全匹配，优先考虑按现有风格扩展它，而不是重造一个平行版本。

### 4. 判断是否需要抽离组件

满足以下任一情况时，优先考虑把页面区块抽成组件：

- 该区块有清晰的业务语义，且名称明确
- 同类区块已经或即将在两个及以上页面复用
- 该区块本身包含较复杂的交互、校验或局部状态
- 抽离后能显著降低页面文件复杂度，提高可读性
- 该区块需要稳定的对外接口，例如 props、emits、slots

出现以下情况时，优先保留在页面内：

- 逻辑高度耦合当前页面，基本不会复用
- 抽离之后只是搬运模板，没有形成清晰抽象
- 代码本身较短，留在页面里更直观
- 项目中同类结构通常就是直接写在页面中

抽组件时要保持抽象克制，不要为了“以后可能复用”而提前做成泛化组件。

### 5. 新代码必须说项目里的“语言”

新增页面或组件时，必须贴合仓库主流实现方式：

- 使用项目中占主流的 API 风格
- 遵循已有 props、emits、slots、expose 的设计方式
- 保持和周边文件一致的命名方式
- 遵循既有路径别名与 barrel 导出规则
- 遵循既有表单 schema、表格 schema、弹窗调用方式
- 保持一致的空态、加载态、权限控制、错误处理方式

如果必须新增组件：

- 放到符合当前项目习惯的目录中
- 名称优先体现业务语义，而不是纯视觉语义
- 对外 API 尽量小而明确
- 只在当前证据足够时才做成可复用组件

### 6. 实施过程中的输出要求

在执行任务时，必须明确说明：

- 复用了哪些现有文件或组件
- 识别到了哪些项目规范
- 是否新建了组件
- 为什么必须新建组件，或者为什么更适合保留在页面里

如果关键项目上下文还不够，先继续读代码，不要猜。

在进行较大规模实现前，先输出一份中文“开发前检查”。必须按下面结构填写真实内容，不能保留占位符：

```md
## 开发前检查

### 1. 已识别的项目规范

- 技术栈：
- 页面组织方式：
- 状态管理方式：
- 样式方案：
- 接口调用方式：
- 组件书写习惯：

### 2. 可复用组件与代码

- 复用组件/模块 1：`路径`
  复用原因：
- 复用组件/模块 2：`路径`
  复用原因：

### 3. 本次页面实现方案

- 页面拆分思路：
- 准备直接复用的部分：
- 需要新增的部分：

### 4. 是否需要封装新组件

- 结论：需要 / 不需要
- 判断依据 1：
- 判断依据 2：
- 如果封装：组件名称、放置目录、对外 props/emits
- 如果不封装：为什么保留在页面内更合适
```

如果任务很小，可以写得简洁，但不能省略这四部分。

在通用检查单之后，再补一份“页面类型专项分析”：

- 以查询、表格、批量操作、分页、Tabs、行操作为主的页面，使用“列表页模板”
- 以新增、编辑、提交、校验、分步表单、抽屉表单、弹窗表单为主的页面，使用“表单页模板”
- 以记录展示、资料页、分组区块、时间线、卡片区、只读信息展示为主的页面，使用“详情页模板”
- 如果页面混合多种模式，选择主模式，并简要说明次要模式

只要是实质性的页面开发任务，就不要省略页面类型专项分析。

实现完成后，再按下面结构输出中文总结：

```md
## 实现结果

- 已复用组件：
- 新增组件：
- 未封装组件的部分：
- 主要遵循的项目规范：
- 如有取舍，说明原因：
```

如果没有新建组件，要明确写出来。

## 决策原则

- 优先保证一致性，而不是追求技巧性。
- 优先遵循本项目先例，而不是外部习惯。
- 优先做小步、可组合的修改，而不是大拆大改。
- 优先扩展已有组件，而不是新建平行体系。
- 组件命名优先体现业务语义，而不是 `InfoBox`、`ListItemWrapper` 这类视觉语义。
- 只有在代码库里有现实依据时，才判断值得抽成复用组件，不为想象中的未来复用提前设计。
- 当你声称识别了某项规范或某个复用依据时，尽量给出具体文件路径作为证据。

## 禁止事项

- 不要在没看现有页面前就生成一套全新页面架构
- 不要在一次改动里混用多种代码风格
- 不要引入一套新的组件命名体系
- 不要创建项目里本来不存在的“基础组件体系”
- 不要过度抽象只属于当前页面的逻辑
- 不要忽视已有的查询区、表格、表单、弹窗、布局组件
- 不要静默替换项目既有的接口、状态管理、样式方案

## 参考文件

按需读取这些参考文件：

- `references/project-scan-checklist.md`：编码前的项目扫描清单
- `references/component-extraction-rules.md`：判断是否需要抽组件的规则
- `references/chinese-output-template.md`：开发前检查和实现后总结模板
- `references/page-analysis-templates.md`：列表页、表单页、详情页的固定分析模板