# 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日将截止维护