# specification

**Repository Path**: eBlueIce/specification

## Basic Information

- **Project Name**: specification
- **Description**: 前端开发规范
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-03-21
- **Last Updated**: 2022-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### 前端开发规范

## 一、前端项目目录规范

```
|-- .env.development ------------ dev 环境变量
|-- .env.production-stage ------- stage 环境变量
|-- .env.production ------------- prod 环境变量
|-- .vscode --------------------- 统一 VSCode 配置
|-- README.md ------------------------ 说明文档，简单介绍项目情况
|-- public
|   |-- favicon.ico
|   |-- index.html
|   |-- libs -------------------- 不支持模块化加载的第三方 ES5 类库/模块 (只能通过全局变量引用)
|-- library
    |-- components -------------- 存放通用组件
    |   |-- Fxxx --- 已F为开头的驼峰命名
    |   |   |-- index.vue --- 该组件命名必须为index.vue
    |   |-- styles ---------------------- 公共样式文件目录
    |       |-- loading.scss
    |       |-- youbip.scss --- 该文件用于存放修改element-plus通用组件样式
|-- src
    |-- main.js
    |-- App.vue
    ├── api                           请求地址配置
    │   ├── command.ts                通用相关接口配置
    |-- libs -------------------- 支持模块化加载但是无法通过 npm 安装的第三方 ES5 类库/模块
    |-- assets ------------------ 静态资源目录，图片存放目录
    |-- config ------------------ 配置文件存放目录
    |-- library ----------------- 通用表格页面组件目录
    |-- router -------------------- 路由配置
    |   |-- index.js
    |   |-- hideRoutes.js
    |-- store -------------------- 项目共用数据（state）
    |   |-- index.js
    |   |-- getters.js
    |   |-- xxx.js
    |-- utils -------------------- 通用方法
    |   |-- common.ts ------------------ 存放通用方法
    |   |-- menu.ts -------------------- 存放路由相关方法
    |   |-- judgeType.ts --------------- 存放类型判断方法
    |-- views
    |   |-- command ----------------- 低代码相关页面
    |       |-- command.vue --------- 配置管理页面
    |       |-- views.vue --------- 视图管理页面
    |       |-- forms.vue --------- 表单管理页面
    |       |-- models.vue --------- 模型管理页面
    |-- components ----------------- 低代码通用配置组件
    |   |-- common ----------------- 公共组件
    |       |-- CommonAdd.vue --------- 表格上方新增组件
    |       |-- CommonEdit.vue --------- 操作栏按钮组件
    |       |-- CommonExport.vue --------- 导出组件
    |       |-- CommonImport.vue --------- 导入组件
```

## 二、Vue项目中的命名

```
- 命名可遵循以下规则：
-  1、有意义的名词、简短、具有可读性
-  2、以小写开头，采用驼峰命名，例如helloWorld
-  3、公共组件命名以F开头命名(FXx.vue)
-  4、文件夹命名主要以功能模块代表命名
-  5、组件内部禁止使用全局变量，全局样式，如特殊情况必须使用，必须增加命名空间杜绝全局污染，变量声明只能使用let const 杜绝var 
```


## 三、vue文件基本结构

```
  <template>
    <div class="demo">
      <!--必须在一个标签中编写页面-->
    </div>
  </template>
  <script>
    export default defineComponent({
      name: 'CommonAdd', // name必须有，且唯一
      components : {
      },
      setup(props, { emit }) {
        const state = reactive({
        })
        const handleClose = () => {}

        return {
        ...toRefs(state),
        handleClose,
      }
      })
    })
  </script>
  <!--声明语言，并且添加scoped-->
  <style lang="scss" scoped>
    .demo { -----所有样式包在最外层class里面，避免样式污染全局
      ...
    }
  </style>
```

- vue文件方法声明顺序
```
  - name
  - components
  - setup
```

- 页面结构命名

```
  - page: 代表整个页面，用于最外层。
  - wrap: 外套，将所有元素包在一起的一个外围包，用于最外层
  - wrapper: 页面外围控制整体布局宽度，用于最外层
  - container: 一个整体容器，用于最外层
  - head, header: 页头区域，用于头部
  - nav: 导航条
  - content: 内容，网站中最重要的内容区域，用于网页中部主体
  - main: 网站中的主要区域（表示最重要的一块位置），用于中部主体内容
  - column: 栏目
  - sidebar: 侧栏
  - foot, footer: 页尾、页脚。网站一些附加信息放置区域，（或命名为 copyright）用于底部
  导航命名
  - nav, navbar, navigation: 导航条或导航包，代表横向导航
  - topnav: 顶部导航
  - mainbav: 主导航
  - subnav: 子导航
  - sidebar: 边导航
  - leftsidebar: 左导航
  - rightsidebar: 右导航
  - title: 标题
  - summary: 摘要
  - menu: 菜单，区域包含一般的链接和菜单
  - submenu: 子菜单
  - drop: 下拉
  - dorpmenu: 下拉菜单
  - links: 链接菜单
功能命名
  - logo: 标记网站logo标志
  - banner: 标语、广告条、顶部广告条
  - login: 登陆
  - loginbar: 登录条
  - register: 注册
  - tool, toolbar: 工具条
  - search: 搜索
  - searchbar: 搜索条
  - searchinput: 搜索输入框
  - shop: 功能区，表示现在的
  - icon: 小图标
  - label: 商标
  - homepage: 首页
  - subpage: 二级页面子页面
  - hot: 热门热点
  - list: 文章列表
  - scroll: 滚动
  - tab: 标签
  - sitemap: 网站地图
  - msg 或 message: 提示信息
  - current: 当前的
  - joinus: 加入
  - status: 状态
  - btn: 按钮
  - tips: 小技巧
  - note: 注释
  - guild: 指南
  - arr, arrow: 标记箭头
  - service: 服务
  - breadcrumb: (即页面所处位置导航提示）
  - download: 下载
  - vote: 投票
  - siteinfo: 网站信息
  - partner: 合作伙伴
  - link, friendlink: 友情链接
  - copyright: 版权信息
```

## 四、注释规范

## 代码注释

- 文件头部注释

  - 脚本文件、样式文件

    ```js
    /**
     * 说明
     * @author 作者
     */
    ```

  - vue 文件
    ```html
    <!-- 说明 -->
    <!-- @author 作者 -->
    ```

- js 注释 

  - 注释格式

    ```js
    /**
     * 文件头部、大的区块
     */

    /* 一般的区块 */

    // 小的区块、行
    ```


    ```js
    /**
     * 使用 param 表示函数形参
     * 使用 returns 表示函数返回值
     * @param {Object} [title]    - 参数说明
     * @param {String} [columns] - 参数说明
     * @returns {类型}
     */
    // 例如
    /*
    * 参数说明：
    * number：要格式化的数字
    * decimals：保留几位小数
    * dec_point：小数点符号
    * thousands_sep：千分位符号
    * */
    export function myMethod(data, options) {}

    /**
     * 使用 type 进行类型断言
     * @type {import('vue-router').RouteConfig[]}
     */
    const routes = []

    /**
     * 使用 typedef 定义类型，方便多处使用（命名时需要首字母大写）
     * @typedef {routes[0]} RouteConfig
     * @param {(meta: object, route: RouteConfig) => boolean} filterCallback
     * @returns {RouteConfig[]}
     */
    export const filterMapRoutes = function(filterCallback) {}

    /**
     * 类型参考：https://www.tslang.cn/docs/handbook/basic-types.html
     *
     * 基本
     * @type {boolean}
     * @type {string}
     * @type {number}
     * @type {'a' | 'b' | 'c'}
     * @type {1 | 2 | 3}
     *
     * 数组
     * @type {Array}
     * @type {string[]}
     *
     * 函数
     * @type {Function}
     * @type {(data) => void}
     * @type {(data: Array) => void | boolean}
     *
     * 对象
     * @type {object}
     *
     * 联合
     * @type {number | string}
     * @type {boolean | (() => boolean)}
     *
     * 导入 ts 类型
     * @type {import('xxx').Yyy}
     *
     * 从现有的 js 变量或 ts 类型进行推导
     * @type {Parameters<fn>} 取函数形参的类型
     * @type {Parameters<fn>[0]} 取函数第一个形参的类型
     * @type {ReturnType<fn>} 取函数返回值的类型
     * @type {obj['xxx']} 取指定属性值的类型（不能使用点语法）
     * ...
     */
    ```


- css 注释

  - 全局样式需要写注释

    ```less
    /* 说明 */
    .g-class1 {
    }

    /* 说明 */
    .g-class2 {
    }
    ```

- vue template 注释

  - 适当使用注释与空行

    ```html
    <!-- 说明 -->
    <div>block1</div>

    <!-- 说明 -->
    <div>block2</div>
    ```

---