Gi Admin Pro

简介

Gi Admin Pro 是一个基于 Vue3、Vite、TypeScript、Arco Design Vue、Pinia、VueUse 等的免费中后台模版，它使用了最新的前端技术栈，内置丰富的主题配置，有着极高的代码规范，基于 mock 实现的动态数据展示，开箱即用的模板，也可用于学习参考。

Gi 前缀含义： G：代表全局 i：代表我的

Gi 用来定义全局组件前缀，如 GiNavBar、GiTitle、GiLoading

特性

• 最新技术栈：使用 Vue3 / Vite 等前端前沿技术开发，使用高效率的 npm 包管理器
• TypeScript：应用程序级 JavaScript 的语言
• 主题：丰富可配置的主题、暗黑模式
• 代码规范：丰富的规范插件及极高的代码规范

预览

代码仓库

项目示例图

安装使用

• 安装依赖

npm install

• 运行

npm run dev

• 打包

npm run build

vs code 插件安装

1. Prettier - Code formatter2. Vue - Official3. Vue 3 Snippets

注意

由于升级了vite3，根据官方规定，node版本必须是14.18.0以上

注：现在已更新到了 Vite5.x，node的版本要求请参考官网要求

vite 官网地址：https://cn.vitejs.dev/

开源作者

Lin

常见问题

为什么安装依赖不成功？

检查node版本，最好使用原生镜像npm

还原镜像

npm config set registry https://registry.npmjs.org/

为什么选择 Arco 组件库，而不是 Element Plus?

Element Plus 对比 Arco design

为什么全局组件使用前缀 Gi?

全局组件设置了按需引入，使用前缀，方便和局部组件做区分

为什么组件使用单词大写开头 (PascalCase)命名写法？

本项目.vue文件名以及在模板使用中，均采用大写开头 (PascalCase)命名方式

参考 Vue2 官网-风格指南: https://v2.cn.vuejs.org/v2/style-guide/

组件命名：单文件组件的文件名应该要么始终是单词大写开头 (PascalCase)，要么始终是横线连接 (kebab-case)

其他优点：方便搜索（横线连接 (kebab-case)对搜索没那么方便）

为什么 css 类名推荐横线连接 (kebab-case)

参考大部分大网站，都是这个命名规则，别整：.myClass这种

页面显示异常？

页面必须要保留一个根元素！！！

Vue3 权限管理对路由进行排序和格式化处理方式

使用xe-utils 这个 js 库，简化数据处理

文章地址

页面无法缓存？

请检查页面是否配置了name，且名称是否与数据一致

defineOptions({ name: 'AboutIndex' })

{ path: '/about/index', name: 'AboutIndex', // 检查name是否一致 component: () =>import('@/views/about/index.vue')}

项目规范

.vue 文件行数规范

一般来说，一个 .vue 文件行数建议不超过 400行，超过建议组件化拆分

变量命名

常用前缀

一些通用缩写

vue 相关的命名

写法技巧

尽量使用三元表达式

// 优化前let isEdit = truelet title = ''if (isEdit) { title = '编辑'} else { title = '新增'}// 优化后let title = isEdit ? '编辑' : '新增'

善用 includes 方法

// 优化前if (type === 1 || type === 2 || type === 3) {}// 优化后，此种方式在vue模板也可使用if ([1, 2, 3].includes(type)) {}

使用箭头函数简化函数

// 优化前function add(num1, num2) { return num1 + num2}// 优化后const add = (num1, num2) => num1 + num2

尽量减少 if else if

// 优化前const status = 200const message = ''if (status === 200) { message = '请求成功'} else if (status === 404) { message = '请求出错'} else if (status === 500) { message = '服务器错误'}// 优化后const status = 200const messageMap = { 200: '请求成功', 404: '请求出错', 500: '服务器错误'}const message = messageMap[status]

如果函数参数超过两个，建议优化

接口 api 的命名

方案一

如果你后端的接口命名相对简约，那么可以采用以下命名规则（注意ts类型的命名规则)

命名规范： 操作名 + 后端模块名 + 功能名

前缀为（操作名）动词，动词 eg：add / update / delete / get / save等

import type * as T from './type'import http from '@/utils/http'/** 获取用户列表 */export function getUserList() { return http.get>('/user/list')}/** 获取用户详情 */export function getUserDetail() { return http.get('/user/detail')}/** 新增用户 */export function addUser(data: any) { return http.post('/user/add', data)}/** 编辑用户 */export function updateUser(data: any) { return http.post('/user/update', data)}/** 删除用户 */export function deleteUser(data: { id: string }) { return http.post('/user/delete', data)}

以上命名规范可以确保 api 命名不会冲突，加上模块名能快速定位以及更加方便维护

// @/apis/index.tsexport * from './user'export * from './user/type'

方案一的api引入

import { getUserList, addUser, type UserAddResult } from '@/apis'

方案一接口的ts类型命名规则

const url1 = '/user/list' // UserItem[] 或者 UserListItem[]const url2 = '/user/detail' // UserDetail 或者 UserDetailResultconst url3 = '/role/list' // RoleItem[] 或者 RoleListItem[]const url4 = '/role/detail' // RoleDetail 或者 RoleDetailResult

方案二

如果你后端的接口命名相对没那么简约，那么可以采用以下命名规则（注意ts类型的命名规则)

import type * as T from './type'import http from '@/utils/http'/** 获取用户列表 */export function getUserList() { return http.get>('/user/getUserList')}/** 获取用户详情 */export function getUserDetail() { return http.get('/user/getUserdetail')}/** 新增用户 */export function addUser(data: any) { return http.post('/user/addUser', data)}/** 编辑用户 */export function updateUser(data: any) { return http.post('/user/updateUser', data)}/** 删除用户 */export function deleteUser(data: { id: string }) { return http.post('/user/deleteUser', data)}

以上命名规范可以确保 api 命名不会冲突，加上模块名能快速定位以及更加方便维护

方案二的api引入

import { getUserList, addUser, type AddUserResult } from '@/apis/user' // 需要具体到模块名

接口 api 的 ts 类型导入

import http from '@/utils/http'import { prefix } from '../config'import type * as T from './type'/** 获取部门数据 */export function getSystemDeptList() { return http.get>(`${prefix}/system/dept/list`)}/** 获取用户数据 */export function getSystemUserList() { return http.get>(`${prefix}/system/user/list`)}/** 获取角色数据 */export function getSystemRoleList() { return http.get>(`${prefix}/system/role/list`)}

不建议以下方式导入 ts 类型，不够方便

import type { SystemDeptItem, SystemUserItem, SystemRoleItem } from './type'

接口调用书写

写法一

不需要 loading，不需要错误打印的 情况

// getUserListApi 是一个 Promise 异步函数，Promise 最后只有 成功 / 失败 两种状态 // getUserListApi 是基于 axios封装的，在 axios 响应拦截器做了处理 // 当 res.success === false 的时候 Promise.reject(),也就异步失败，异步失败不会往下执行

写法二

需要 loading，需要错误打印的情况

写法三

需要 loading, 不需要错误打印（不进行错误处理）的情况

// catch 可以省略

正则使用示例

文件位置：@/utils/regexp.ts

/** @desc 正则-手机号码 */export const Phone = /^1[3-9]\d{9}$//** @desc 正则-邮箱 */export const Email = /^\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$//** @desc 正则-6位数字验证码正则 */export const Code_6 = /^\d{6}$//** @desc 正则-4位数字验证码正则 */export const Code_4 = /^\d{4}$//** @desc 正则-16进颜色值 #333 #8c8c8c */export const ColorRegex = /^#?([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$//** @desc 正则-只能是中文 */export const OnlyCh = /^[\u4e00-\u9fa5]+$/gi/** @desc 正则-只能是英文 */export const OnlyEn = /^[a-zA-Z]*$//** @desc 登录注册-密码 6-16位大小写字母、数字的js正则 */export const Password = /^[a-zA-Z0-9]{6,16}$/

使用

页面模板 CSS 类名采用半角连接符(-)

全局组件--命名规范

组件命名：单文件组件的文件名应该要么始终是单词大写开头 (PascalCase)，要么始终是横线连接 (kebab-case)

可参考 Vue2 官网-风格指南: https://v2.cn.vuejs.org/v2/style-guide/

GiTitle.vueGiThemeBtn.vueGiSvgIcon.vue

局部组件--命名规范

组件命名：单文件组件的文件名应该要么始终是单词大写开头 (PascalCase)，要么始终是横线连接 (kebab-case)

可参考 Vue2 官网-风格指南: https://v2.cn.vuejs.org/v2/style-guide/

Pane1.vuePane2.vuePaneQuota1.vuePaneQuota2.vueStep1.vueStep2.vueAddModal.vueEditDrawer.vueDetailModal.vue

文件夹命名--命名规范 (采用中划线-)

1、文件名建议只使用小写字母，不使用大写字母

2、名称较长时采用半角连接符(-)分隔

home/index.vueuser/index.vueuser-detail/index.vue

弹窗组件 Modal、抽屉组件 Drawer 的一般封装

使用

模板里使用自定义组件：使用大写开头驼峰，双击好复制，对于搜索便利

GiForm 使用示例(2024-10-25更新：采用更强大的Grid布局)

GiForm 是一个 JSON 配置表单组件，能够快速通过 JSON 构建表单布局

基本示例

新版文档

options配置

columns配置

结合Modal函数实现更高效的表单对话框

GiTable 使用示例

GiTable继承了a-table的所有属性和配置，只是多了一些插槽，以及prop属性，具体看源码

Hooks 目录结构

hooks 下默认存放公共的，非接口请求的 hooks

hooks/app 下主要存放通用接口的 hooks

/hooks/app/useDept.ts

import { ref } from 'vue'import { getSystemDeptList } from '@/apis'import type { SystemDeptItem } from '@/apis'/** 部门模块 */export function useDept() { const loading = ref(false) const deptList = ref([]) const getDeptList = async () => { try { loading.value = true const res = await getSystemDeptList() deptList.value = res.data.records } catch (error) { } finally { loading.value = false } } return { deptList, getDeptList, loading }}

使用

TSX 方式使用表格

usePagination(hooks) 的使用

文件位置：@/hooks/modules/usePagination.ts

旧版：

import { ref } from 'vue'type Callback = () => voidtype Options = { defaultPageSize: number}export default function usePagination(callback: Callback, options: Options = { defaultPageSize: 10 }) { const current = ref(1) const pageSize = ref(options.defaultPageSize) const total = ref(0) function changeCurrent(size: number) { current.value = size callback && callback() } function changePageSize(size: number) { current.value = 1 pageSize.value = size callback && callback() } function setTotal(value: number) { total.value = value } const pagination = computed(() => { return { showPageSize: true, // ...其他配置 total: total.value, current: current.value, pageSize: pageSize.value, onChange: changeCurrent, onPageSizeChange: changePageSize } }) return { current, pageSize, total, pagination, changeCurrent, changePageSize, setTotal }}

上面这种方案已经废弃，最新方案如下

改良版（兼容旧版）：

import { reactive, toRefs } from 'vue'import type { PaginationProps } from '@arco-design/web-vue'type Callback = () => voidtype Options = { defaultPageSize: number}export default function usePagination(callback: Callback, options: Options = { defaultPageSize: 10 }) { const pagination = reactive({ showPageSize: true, current: 1, pageSize: options.defaultPageSize, total: 0, onChange: (size: number) => { pagination.current = size callback && callback() }, onPageSizeChange: (size: number) => { pagination.current = 1 pagination.pageSize = size callback && callback() } }) const changeCurrent = pagination.onChange const changePageSize = pagination.onPageSizeChange function setTotal(value: number) { pagination.total = value } const { current, pageSize, total } = toRefs(pagination) return { current, pageSize, total, pagination, changeCurrent, changePageSize, setTotal }}

使用方式 1

使用方法 2 (改良版，更少代码)

注意：

改为

或者

useTable(hooks) 的使用

使用

提示

使用 useTable 的时候不传入类型，tableData 也会根据入参自动推导出类型

最后提示

在最新版的useTable中，selectKeys已经改为selectedKeys，同时加了其他新功能，具体查看源码

useResetReactive(hooks) 的使用

作用：有时候需要重置表单数据，这个hooks提供很大便捷性

代码：useResetReactive.ts

import { reactive } from 'vue'import { cloneDeep } from 'lodash-es'export function useResetReactive(value: T) { const getInitValue = () => cloneDeep(value) const state = reactive(getInitValue()) const reset = () => { Object.keys(state).forEach((key) => delete state[key]) Object.assign(state, getInitValue()) } return [state, reset] as const}

使用

import { useResetReactive } from '@/hooks'const [form, resetForm] = useResetReactive({ id: '', name: '', phone: '', status: false})// 重置表单数据resetForm()

注意

resetForm方法为什么要加上以下代码

for (const key in form) { delete form[key]}

比如一个编辑弹窗，点击编辑，会根据 id 查详情，有时候为了方便，直接把详情的数据赋值到 form 里面，这就会导致重置的时候，有详情的属性冗余，以下举个例子

const form = { name: '' }const detail = { name: '张三', status: 1 }Object.assign(form, detail)console.log(form) // { name: '张三', status: 1 }// 如果直接重置Object.assign(form, { name: '' })console.log(form) // { name: '', status: 1 } 有额外属性冗余，status会不经意的随着保存操作提交到后台

TSX 方式调起弹窗

方式 1

tool.tsx

使用

方式 2

AddUserForm.vue

使用

方式 3

组件使用建议

能使用组件尽量使用组件实现页面布局

flex 布局尽量使用 Row组件

按钮间间隔尽量使用Space组件

状态色文本，尽量使用

Link 组件使用场景

CSS 命名规范

建议采用全小写，多单词使用-连接符(参考大部分网站，包括掘金，码云等，都是采用这个规则)

或者采用BEM命名规范BEM 命名规范

// 推荐.header.footer.main.content.container.page.detail.pane-left.pane-right.list.list-item// 不推荐.Header.listItem.list-Item.List-Item;

BEM 命名规范

.article { max-width: 1200px; &__body { padding: 20px; } &__button { padding: 5px 8px; &--primary { background: blue; } &--success { background: green; } }}

CSS 全局类名-命名规范

采用下划线_，好复制

.gi_line_1 .gi_line_2 .gi_margin .gi_box

// 文件位置: @/styles/global.scss.gi_line_1 { overflow: hidden; white-space: nowrap; text-overflow: ellipsis;}.gi_line_2 { -webkit-line-clamp: 2;}.gi_line_3 { -webkit-line-clamp: 3;}.gi_line_4 { -webkit-line-clamp: 4;}.gi_line_5 { -webkit-line-clamp: 5;}.gi_line_2,.gi_line_3,.gi_line_4,.gi_line_5 { overflow: hidden; word-break: break-all; text-overflow: ellipsis; display: -webkit-box; // 弹性伸缩盒 -webkit-box-orient: vertical; // 设置伸缩盒子元素排列方式}.gi_padding { padding: $padding;}.gi_margin { margin: $margin;}.gi_relative { position: relative;}.gi_absolute { position: absolute;}.gi_rotate_90deg { transform: rotate(90deg);}.gi_rotate_-90deg { transform: rotate(-90deg);}.gi_rotate_180deg { transform: rotate(180deg);}.gi_rotate_-180deg { transform: rotate(-180deg);}.gi_mt { margin-top: $margin;}.gi_mb { margin-bottom: $margin;}.gi_ml { margin-left: $margin;}.gi_mr { margin-right: $margin;}.gi_mx { margin: 0 $margin;}.gi_my { margin: $margin 0;}.gi_m0 { margin: 0;}.gi_pt { padding-top: $margin;}.gi_pb { padding-bottom: $margin;}.gi_pl { padding-left: $margin;}.gi_pr { padding-right: $margin;}.gi_px { padding: 0 $padding;}.gi_py { padding: $padding 0;}.gi_p0 { padding: 0;}// 使用场景，页面内容超出高度会自动滚动.gi_page { flex: 1; padding: $margin; box-sizing: border-box; overflow-y: auto;}// 通用盒子.gi_box { background: var(--color-bg-1); border-radius: $radius-box; overflow: hidden;}

全局 scss 变量-命名规范

$color-theme: rgb(var(--primary-6)); // 主题色$color-primary: rgb(var(--primary-6)); // 主题色$color-success: rgb(var(--success-6));$color-warning: rgb(var(--warning-6));$color-danger: rgb(var(--danger-6));$color-info: rgb(var(--gray-6));$title-color: xxx; // 已弃用，写起来繁琐，易忘$text-color: xxx; // 已弃用$text-sub-color: xxx; // 已弃用$text-sup-color: xxx; // 已弃用// 借鉴了Arco Design命名规则$color-text-1: var(--color-text-1); // 标题、重点文本字体颜色$color-text-2: var(--color-text-2); // 文本-全局默认字体颜色$color-text-3: var(--color-text-3); // 二级文本颜色$color-text-4: var(--color-text-4); // 辅助文本颜色$margin: 16px; // 盒子间距$padding: 16px; // 盒子和内容的间距

如下图：

位置 1： 使用 $margin 全局 scss 变量

位置 2：使用 $padding 全局 scss 变量

建议尽量使用全局 scss 变量来开发，可以有效提高效率和团队协作

CSS 的命名词汇

前一个 prev后一个 next当前的 current显示的 show隐藏的 hide打开的 open关闭的 close选中的 selected有效的 active默认的 default反转的 toggle禁用的 disabled危险的 danger主要的 primary成功的 success提醒的 info警告的 warning出错的 error大型的 lg小型的 sm超小的 xs

文档 doc头部 header(hd)主体 body尾部 footer(ft)主栏 main侧栏 side容器 box/container

列表 list列表项 item表格 table表单 form链接 link标题 caption/heading/title菜单 menu集合 group条 bar内容 content结果 result

按钮 button(btn)下拉菜单 dropdown工具栏 toolbar分页 page缩略图 thumbnail警告框 alert进度条 progress导航条 navbar导航 nav子导航 subnav面包屑 breadcrumb(crumb)标签 label徽章 badge巨幕 jumbotron面板 panel洼地 well标签页 tab提示框 tooltip弹出框 popover轮播图 carousel手风琴 collapse定位浮标 affix

品牌 brand标志 logo额外部件 addon版权 copyright注册 regist(reg)登录 login搜索 search热点 hot帮助 help信息 info提示 tips开关 toggle新闻 news广告 advertise(ad)排行 top下载 download

左浮动 fl右浮动 fr清浮动 clear

其他规范

可参考 Vue2 官网-风格指南: https://v2.cn.vuejs.org/v2/style-guide/ , 其中一些规范也可借鉴

可参考Gi Admin Pro源码，如有更好的规范建议，可以联系作者本人

Vue 相关

Vue3 官网

Vue-Router

Vite

Pinia

插件推荐

Arco Design 组件库

Day.js 一个极简的 JavaScript 库，可以为现代浏览器解析、验证、操作和显示日期和时间 2K 大小

Lodash 一个一致性、模块化、高性能的 JavaScript 实用工具库

Xe-utils 一个 JavaScript 函数库、工具类

VueUse 一个 Vue3 Hooks 库

VueRequest 一个 Vue 请求库

V-Viewer 基于 viewer.js 的 vue 图像查看器组件，支持旋转、缩放等操作

Vue-Color-Kit 一个 vue3 颜色选择器组件

Vxe-Table

其他

VCalendar 日历组件

Vue Cal 日历组件

VueDraggablePlus 支持 Vue2 和 Vue3 的拖拽组件

推荐书籍

Vue 入门指南与实战案例

深入理解 TypeScript

前端宝典

Web 开发人员需要知道的 CSS 技巧

阮一峰 ES6

阮一峰 flex 布局

开源项目集合

Vue3 开源项目集合

React 开源项目集合

工具

菜鸟工具

代码生成图片

JSON-TO-ANY 对象转 ts 类型

在线三角形样式生成器

iTab

捐赠