# customFrame
**Repository Path**: tswsoft/custom-frame
## Basic Information
- **Project Name**: customFrame
- **Description**: 基于vue3+vite+pinia的一个完整的前端框架
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 4
- **Created**: 2025-07-08
- **Last Updated**: 2025-07-08
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 前端项目公共框架
| 分支名称 | 分支说明 | 备注 |
| ------------------- | ------------------ | ------------------------------ |
| master | 主分支 | 说明文档 |
| frame-web | vue2 浏览器端框架 | 已完成,后续非必要不会再更新 |
| frame-phone | vue2 移动端框架 | 已完成,后续非必要不会再更新 |
| frame-web-vue3 | vue3 浏览器端框架 | 已完成,后续主要在此更新 |
| frame-phone-vue3 | vue3 移动端框架 | 已完成,后续主要在此更新 |
| frame-web-vue3-TS | vue3+TS 浏览器框架 | 已完成,后续主要在此更新 |
| frame-phone-vue3-TS | vue3+TS 移动端框架 | 已完成,后续主要在此更新 |
| frame-empty-vue3-TS | | 类似快速启动项目,对内对外使用 |
[TOC]
## 前言
大家在平常开发可能都会遇到类似情况:
- 项目代码风格各式各样,没有统一风格,也没有review的习惯,迭代一个需求,就需要熟悉一种新的风格
- 代码可维护性差,更换开发人员,开发时间急剧拉长
- 想做统一的业务组件库或者UI组件库 提升效率,因为各种风格不统一,很难实现
- 沟通时间可能大于开发时间
现实中我们都知道很大一部分开发人员很反感这些条条框框,本身开发就是自由的,不受约束的,但是现在基本都是合作开发项目,所以它不是一个人的事情,对软件来说,适当的规范和标准绝不是消灭代码内容的创造性、优雅性,而是限制过度个性化,以一种普遍认可的统一方式一起做事,提升协作效率,降低沟通成本,开发合作起来是快乐的。
## 一、前端规范说明
1. 如何规范开发代码
1. 采用 `ESLint`,共同遵守对应的lint规范
2. 采用 `TypeScript`,共同采用对应 `TypeScript`写法
2. 我司前端 `Vue` 技术栈 :
团队每个人都会有自己的想法,其实很难去统一,对基本做以下说明:
| 风格 | 方案 | 备注 |
| ---------- | :----------------------------------------------------------- | ------------------------------------------------------------ |
| `UI`组件库 | Vue2:
PC端: [Element UI](https://element.eleme.cn/#/zh-CN/component/)
移动端: [Vant UI](https://vant-contrib.gitee.io/vant/#/zh-CN/)
Vue3:
PC端:[Element Plus](https://element-plus.gitee.io/zh-CN/#/zh-CN),[Naive UI](https://www.naiveui.com/zh-CN/light)
移动端:Vant UI | 其次考虑 [View UI](https://www.iviewui.com/),[Ant Design of Vue](https://www.antdv.com/docs/vue/introduce-cn/),[VUX](https://doc.vux.li/zh-CN/)等 |
| 包管理工具 | [npm](https://www.npmjs.cn/)、[yarn](https://yarn.bootcss.com/docs/)、[pnpm](https://pnpm.io/zh/) | 推荐使用 pnpm |
| 构建工具 | Vue2:
@vue-cli4脚手架内置[webpack](https://webpack.docschina.org/)
Vue3:
[Vite](https://cn.vitejs.dev/) | [rollup](https://www.rollupjs.com/) |
| 微信开发 | [uni-app](https://uniapp.dcloud.io/) | UI组件库使用 [uview-plus](https://uiadmin.net/uview-plus/) |
| 地图开发 | [高德地图](https://lbs.amap.com/api/javascript-api/summary):1.4.x版本
[AMapUI](https://lbs.amap.com/api/amap-ui/intro):1.1版本
[天地图](https://www.tianditu.gov.cn/)
[ArcGIS Developer](https://developers.arcgis.com/) | 高德地图自2021年12月02日升级,升级之后所申请的 key 必须配备安全密钥 **jscode** 一起使用 |
| 可视化 | [echarts](https://echarts.apache.org/examples/zh/index.html)、 [AntV](https://antv.gitee.io/zh/#products) 、[DataV](http://datav.jiaminghi.com/guide/) | 其次考虑其他 |
| 字体图标 | [iconfont](https://www.iconfont.cn/) | 阿里巴巴矢量图标库,其他 |
| 微前端开发 | [qiankun](https://qiankun.umijs.org/zh) | 已有搭建好的微前端框架 |
| 低代码开发 | 待定 | 待定 |
注意:**非必要情况下,不要使用过多组件,导致项目过大**
1. **规约采用阿里巴巴前端规约和配套工具,你可以使用 [F2ELint](https://www.npmjs.com/package/f2elint) 等配套工具来为项目接入规约。**
| 规约 | Lint工具 | 规则包 |
| -------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
| 《JavaScript 编码规约》
《Vue 编码规约》 | [ESLint](https://eslint.org/) | [eslint-config-ali](https://www.npmjs.com/package/eslint-config-ali) |
| 《CSS 编码规约》 | [stylelint](https://stylelint.io/) | [stylelint-config-ali](https://www.npmjs.com/package/stylelint-config-ali) |
| 《Git 规约》 | [commitlint](https://commitlint.js.org/#/) | [commitlint-config-ali](https://www.npmjs.com/package/commitlint-config-ali) |
| 《文档通用规约》 | [markdownlint](https://github.com/DavidAnson/markdownlint) | [markdownlint-config-ali](https://www.npmjs.com/package/markdownlint-config-ali) |
2. **前端代码管理规范**
1. 克隆仓库
1. SSH key 生成
1. 安装[git](https://www.git-scm.com/download/win)
2. 鼠标右击 选择 Git Bash Here
3. ssh-keygen -t rsa -C "xxxxx@xxxxx.com(sshkey名称)"
4. 找到C:\Users\xxx\.ssh 目录,里面有两个文件:id_rsa和id_rsa.pub
5. gitlab -> settings -> SSH keys -> Add an SSH key(copy id_rsa.pub里面的内容)
2. 获取源码
1. git clone #自己的git仓库# -b 选择分支(默认master)
2. 安装依赖 `pnpm install`
3. 启动项目 `pnpm run serve`
2. 分支管理
- `develop` - 开发/功能分支
- 新功能相关从develop切,命名 `feat-功能名-日期-姓名首字母缩写`
- 功能开发分支 合并 develop,develop再合release, release合hotfix
- feat分支删除:功能开发结束且hotfix分支删除后
- **如果遇到发布正式环境devlop暂停合并release直到发布结束**
- `hotfix` - 缺陷分支
- hotfix和release保持同步,作为bug修改的分支,命名 `hotfix-功能名-日期-姓名首字母缩写`
- bug分支修改完 合并回 hotfix,hotfix合并release,复测结束 release 合并 hotfix,hotfix合并develop
- bug分支删除:bug复测结束,无其他问题后删除
- `release` - 测试环境/预发布分支
- 遇到紧急开发新功能要合并到master,从分支切 命名 `release-功能名-日期-姓名首字母缩写`
- 急功能分支开发完合并 release,release 合并 hotfix,hotfix 合并 develop
- `main/master` - 生产环境分支
- 无特殊情况 只和release分支做交互
- `Tags`相关
- 发布线上环境 需要打相关 tags,命名规则 `版本-日期`
- 不同的线上环境匹配不同tags
- 如果某个tags不再需要,及时清理
3. 代码提交流程
1. 代码提交时 确保本地代码是最新的,再进行提交
2. 提交 commit 注释写清楚
1. `git pull`
2. `git add .`
3. `git commit -m '写清楚对应完成功能或修改'`
4. `git push`
3. 提交前缀说明
- `feat`:新功能、新特性
- `fix`:修改bug
- `perf`:更改代码,以提高性能(在不影响代码内部行为的前提下,对程序性能进行优化)
- `refactor`:代码重构(在不影响代码内部行为、功能下的代码修改)
- `docs`:文档修改
- `config`: 配置文件修改
- `release`: 发布新版本
- `build`:影响项目构建或依赖项修改
- `style`:代码格式修改
- `test`:测试用例的新增、修改
- `revert`:恢复上一次提交
- `ci`:持续集成相关文件修改
- `chore`:其他修改
- `workflow`:工作流相关文件修改
- 其他...
4. 常用命令
1. `git fetch origin` 拉去远程分支
2. `git remote update origin -p` 更新远程分支
3. `git branch | xargs git branch -d` 清除当前本地分支的其他分支
3. **前端环境说明**
- 原生支持 `ES2015` 的浏览器
- Node >= 16版本
- `TypeScript` 环境
- `Eslint` 环境
## 二、协作规约
1. **需求分析**
对提出的需求,各参会人员项目经理、产品、前端、后端、测试等人员应当在认知上达成一致
2. **技术方案评审**
开发之前进行技术方案评审,再次确保各方在需求的认知上统一,可对某些细节再次进行讨论
3. **接口设计**
后端人员应该提供接口文档,
前端人员应该遵循后端提供的接口文档进行开发
4. **并行开发**
前后端人员在开发时,各方必须进行自测
5. **联调**
前后端人员自测完成在开发环境完成接口联调
## 三、编程规约
1. **命名规范**
1. 项目命名
项目仓库统一由管理员建立: **dh.对应项目名.web**
2. 目录命名
1. 全部采用小写,有复数采用复数命名法,缩写不用复数
举例:`plugins / styles / img / doc`
2. Vue项目中组件文件,采用大驼峰命名(参考 [Vue风格指南](https://cn.vuejs.org/v2/style-guide/))
1. **单文件组件大小写:单词大写开头对于代码编译器自动补全最为友好**
举例:`TodoList.vue `
2. **基础组件名:应用特定样式和约定的基础组件 (也就是展示类的、无逻辑的或无状态的组件) 应该全部以一个特定的前缀开头,比如 `Base`、`App` 或 `V`。**
举例: `BaseButton.vue`
3. **单例组件名:只应该拥有单个活跃实例的组件应该以 `The` 前缀命名,以示其唯一性。**
举例:`TheHeading.vue`
4. **紧密耦合的组件名:和父组件紧密耦合的子组件应该以父组件名作为前缀命名**
举例:`TodoListItem.vue`
5. **组件名中单词顺序:组件名应该以高级别的 (通常是一般化描述的) 单词开头,以描述性的修饰词结尾。**
举例:正:`SearchButtonClear.vue` 反:`ClearSearchButton.vue`
6. **完整单词的组件名:组件名应该倾向于完整单词而不是缩写,保证其明确性**
举例:正:`UserProfileOptions.vue` 反:`UProfOpts.vue`
3. 图片文件命名 短横线连接
举例:`pom-logo.png`
4. 命名严谨性
**代码中的命名严禁使用拼音与英文混搭方式,更不允许直接使用中文方式。正确的英文拼写和语法可以让阅读者易于理解,避免歧义,提高代码可读性。**
2. **HTML(Vue Template)规范**
1. 语义化标签的使用
2. 缩进:缩进使用2个空格(1个tab),嵌套的节点应该缩进
3. 分块注释:在每一个单独的分块,应当有其对应的注释
3. **`CSS`,`SCSS`规范**
1. 类名使用小写字母,短横线连接
2. `id,ref`采用小驼峰式命名
3. `css` 选择器中避免使用标签名
4. 组件中 `style` 要使用 `scoped`属性,不影响全局样式
5. `SCSS `( `BEM`规范)
```css
// BEM规范 block element modifier
$dh-namespace: 'dh' !default; // 修饰命名空间
$dh-common-separator: '-' !default; // 公共分隔符
$dh-element-separator: '__' !default; // 划分空间分隔符
$dh-modifier-separator: '--' !default; // 修饰类型
$dh-state-prefix: 'is-' !default; // 修饰状态
```
4. **JavaScript规范**
1. 变量声明 尽量使用 `const`,其次 `let`,不使用 `var`
2. 优先使用 `ES6`,`ES7` 新增语法糖和函数
3. 采用小驼峰命名 `lowerCamelCase`,命名均不能以下划线开头,也不能以下划线或美元符号结束
4. 缩进:缩进使用2个空格(1个 `tab`)
5. 注释:函数方法 要写注释,形参数量过多,采用 `jsdoc` 注释形式
6. 条件判断:条件判断能使用三目运算符和逻辑运算符解决的,就不要使用条件判断,但是不要写过长的三目运算符, 条件判断使用 ===
5. **注释说明**
1. 公共组件的使用说明
2. service目录中后端接口说明
3. Vue文件中 `template` `script` `style` 三部分 中完整部分(模块) 需加注释说明
6. **特殊说明**
1. 尽量不要手动操作 `DOM`
2. 及时删除无用代码
3. 及时在生命周期 `destroyed` 中清除定时器,监听器等
4. `Vue3` 项目,插件,`UI` 组件等采用按需引入,更好的 `tree-shaking`
## 四、Vue 规约说明
#### 1、Vue3 相关规约
1. 标签属性 (使用/变动小的尽可能放最上,事件放最下)
- ref、id、class、style 第一位,尽可能不使用style全部采用class
- v-if、v-show、 v-for 等指令或者自定义指令 第二位
- 属性相关 第三位
- 事件最末尾
```vue
点击
```
2. Script 相关引入
```vue
```
3. `components` 等相关组件中
- ts 类型引入 第一位
- `defineProps` 第二位
- `defineEmits` 第三位
- 其他
- `defineExpose` 最末尾
```vue
```
4. `Pinia` 相关
```typescript
// 最上 引入后台相关API
import {} from '@/service/xxApi';
// element-plus相关提示
import { ElMessage } from 'element-plus';
// ts类型
import type { IAnyItem } from '@/typing/xxx';
// pinia引入
import { defineStore } from 'pinia';
// ...相关函数
// store
const store = defineStore('唯一命名(一般文件名-大驼峰)', {
state: () => ({
testObj: {},
testArr: [],
}),
persist: { // 持久化
key: '', // 持久化的key
paths: [''], // 持久化相关变量
},
getters: {},
actions: {},
});
export default store;
```
5. `CSS` 相关
- 可以使用 `element-plus` 定义好的 `css变量` 具体看 `:root {}`
- 项目中也定义了相应 `BEM规范`,也可以使用定义好的 `css变量` 具体看 `:root {}`
- 在写 `css\scss` 时,尽可能使用 `css变量`
**总结:**
`1、基本都遵循 变动/使用少的尽可能往上方,以此类推`
`2、文件的命名采用大驼峰`
`3、Id,ref 命名采用小驼峰, class采用短横线`
`4、尽可能使用 css变量`
`5、全局采用eslint,请安装和配置相关eslint环境`
#### 2、Vue2 相关规约
1. 生命周期推荐书写顺序
```vue
```
2. `Vuex` 相关
**须使用命名空间,区分不同文件使用的store, 每个store文件也要填写对应的name**
```javascript
import { getMenuApi } from '@/service/dscMenuApi';
import { Message } from 'element-ui';
const store = {
namespaced: true,
name: 'xxx',
state: {
menuList: [],
},
getters: {},
mutations: {
SET_MENU_LIST(state, payload) {
state.menuList = payload;
},
},
actions: {
getMenuList({ commit }, params) {
getMenuApi(params).then((res) => {
if (res.code === 200) {
commit('SET_MENU_LIST', res.data);
return;
}
Message.warning(res.message);
});
}
},
}
```
#### 3、框架目录介绍
1. 框架结构目录
| 目录名称 | 作用 | 备注 |
| -------------------- | -------------------------------------------- | ------------------------------------------------------------ |
| `dist` | 打包目录 | 测试/生产环境发布默认读取此文件,可在项目配置文件中修改相应名称 |
| `public` | 公共静态文件 | `build` 不会打包此目录 |
| `src` | 业务目录 | |
| `.env.xxx` | 配置不同环境变量文件 | 不同环境变量在`public`目录中`config`目录中配置 |
| `.editorconfig` | 编译器配置文件 | |
| `.eslintrc.js` | 代码校验文件 | |
| `.gitignore` | git上传忽略文件 | |
| `babel.config.js` | babel配置文件 | |
| `index.html` | 公共模板 | `vue2`的版本在`public`目录下,`vue3`放到了外面 |
| `package.json` | 项目所需依赖包 | |
| `xxx-lock.xxx` | 锁定安装时的包的版本号及包的依赖的版本号 | `package-lock.json` `pnpm-lock.yaml` `yarn.lock` |
| `README.md` | 项目介绍文件 | |
| `tsconfig.json` | ts的配置文件 | `vue3版本` |
| `tsconfig.node.json` | node环境下ts配置文件ts的配置文件 | `vue3版本` |
| `unocss.config.ts` | 原子化css配置文件ts的配置文件 | `vue3版本` |
| `vite.config.ts` | 项目配置文件 | `vue2版本` `vue.config.js` |
| `auto-imports.d.ts` | 自动导入 Element Plus 相关函数 | `vue3版本` 使用 `unplugin-auto-import` 插件 |
| `components.d.ts` | 自动导入 Element Plus 或者自己定义的相关组件 | `vue3版本` 使用 `unplugin-element-plus` 和 `unplugin-vue-components` 插件 |
2. 业务目录 `src`
| 目录名称 | 作用 | 备注 |
| ------------- | ------------------------- | ----------------------------------------- |
| `assets` | 资源目录 | 存放图片,mock等文件 |
| `components` | 公共组件目录 | |
| `composables` | 公共组件函数目录 | `vue3版本` - 抽离组件中公用的Fun |
| `config` | 配置文件目录 | 配置接口前缀,公共路径等 |
| `directives` | vue自定义指令目录 | |
| `plugins` | 插件目录 | |
| `router` | 路由目录 | |
| `service` | 接口目录 | 后端接口存放位置 |
| `store` | 状态管理目录 | 首选`Pinia` |
| `styles` | 样式目录 | 字体,主题,公共样式, `BEM`规范 |
| `types` | ts声明文件目录 | `Vue3版本` `global.d.ts`、`xx.d.ts` |
| `typings` | 定义数据的ts类型目录 | `Vue3版本` |
| `utils` | 公共函数库 | 封装`axios` 、`ws`、 `lodash`、公共函数等 |
| `views` | 视图组件目录 | |
| `APP.vue` | 根实例文件 | |
| `env.d.ts` | ts声明 相关 `module` 组件 | |
| `main.ts` | 入口文件 | |
#### 特殊说明
1. 组件库采用 `element-plus`,因 `Icon` 改变了方式,在 `main.ts` 中统一由组件方式进行注册
2. `styles` 目录中配置了 `element` 目录,可以对 `element` 样式进行重构
3. 添加 `unocss`
4. 非必要不要在 `index.html` 中以 `script` 引 `js/ts`文件
5. `Vue3` 只支持 `[原生支持ES2015的浏览器](https://caniuse.com/es6)`,这并不包括 `IE11`
6. `Vue2` 在2023年12月31日将截止维护