vue3-h5-development-standards

name: vue3-h5-development-standards description: >- Applies Vue3 mobile H5 development standards for this project. Enforce TypeScript, Composition API, Vant-first UI strategy, vue-hooks-plus-first request management, lodash-es utilities, dayjs date handling, maintainable architecture, mobile optimization, code reuse, and incremental modification principles.

Vue3 H5 项目开发规范

适用于本项目所有：

• Pages
• Components
• Hooks / Composables
• Services
• Stores
• Types
• Utils
• Styles

技术栈

当前项目技术栈：

• Vue 3
• TypeScript
• Vant
• vue-hooks-plus
• lodash-es
• dayjs
• Pinia
• SCSS

生成代码必须优先基于上述技术栈。

核心原则

遵循以下优先级：

框架能力 → Vant → vue-hooks-plus → lodash-es → dayjs → 项目已有实现 → 自定义实现

禁止重复造轮子。

存在成熟方案时必须优先复用。

项目分析规范

编码前必须分析项目

生成代码前必须先分析项目已有实现：

• Pages
• Components
• Hooks
• Services
• Stores
• Types
• Constants
• Enums
• Utils
• 样式规范

优先遵循项目已有结构和编码风格。

禁止擅自创建新的架构体系。

优先复用

发现已有实现时必须优先复用：

• 组件
• Hooks
• Services
• Stores
• Types
• Utils

禁止创建功能重复代码。

例如：

已有：

ts useUserInfo()

禁止生成：

ts useCurrentUser()

如果功能一致应直接复用。

修改优于新增

对于已有功能：

优先修改现有文件。

禁止因为小需求：

• 新建页面
• 新建组件
• 新建 Hook
• 新建 Service

除非明确必要。

文件创建规范

创建新文件前必须确认：

• 现有文件无法扩展
• 现有组件无法复用
• 现有 Hook 无法复用
• 现有 Service 无法复用

满足条件后才允许创建。

输出策略

修改已有功能

优先返回：

• 修改文件
• 修改位置
• 修改内容
• 修改原因

优先增量修改。

禁止无必要整文件重写。

返回代码规范

优先返回：

txt 需要修改的代码片段

不要返回：

txt 整个页面文件 整个组件文件

除非用户明确要求。

Vue 规范

必须使用 Script Setup

统一：

vue

禁止：

ts export default defineComponent()

Composition API

使用：

ts ref reactive computed watch watchEffect

禁止：

ts Options API

类型规范

必须：

• 参数定义类型
• 返回值定义类型
• Props 定义类型
• Emits 定义类型

优先：

ts interface type enum

禁止：

ts any

除非无法避免。

Props

ts const props = defineProps()

Emits

ts const emit = defineEmits<{ submit: [FormData] cancel: [] }>()

请求规范

强制使用 vue-hooks-plus

统一使用：

ts useRequest

分页：

ts usePagination

加载更多：

ts useLoadMore

无限滚动：

ts useInfiniteScroll

禁止：

ts onMounted(async () => {})

ts loading.value = true await api() loading.value = false

ts watch(() => { api() })

优先：

ts const { data, loading, error, run, refresh, } = useRequest(...)

Service 规范

接口统一管理

目录：

txt src/services

示例：

txt services/ ├── user.ts ├── order.ts ├── home.ts └── activity.ts

页面禁止：

ts fetch(...) axios(...) request(...)

直接调用接口。

必须通过 Service。

Service 职责

只负责：

• 接口请求
• 数据转换

禁止：

• DOM 操作
• Toast
• Notify
• Dialog
• 路由跳转
• 状态管理

日期处理规范

统一使用：

ts import dayjs from 'dayjs'

例如：

ts dayjs().format('YYYY-MM-DD')

禁止：

ts new Date()

以及手写格式化函数。

工具函数规范

统一使用：

ts import { debounce, throttle, cloneDeep, uniqBy, groupBy, orderBy, pick, omit, } from 'lodash-es'

禁止：

• 手写 debounce
• 手写 throttle
• 手写深拷贝
• 手写数组去重
• 手写排序工具

UI 规范

Vant First

存在对应组件时必须优先使用 Vant。

按钮

使用：

vue

禁止：

html

---

表单

使用：

vue

优先使用 rules 校验。

禁止复杂手写校验状态。

---

图片

使用：

vue

优先：

vue

---

列表

使用：

vue

---

空状态

使用：

vue

---

Loading

使用：

vue

---

Popup

使用：

vue

---

Dialog

使用：

ts showDialog() showConfirmDialog()

禁止自定义 Modal。

---

Toast

使用：

ts showToast() showFailToast() showSuccessToast() showNotify()

禁止自定义 Toast。

---

Picker

使用：

vue

vue

---

页面结构规范

推荐：

html