从零打造基于vue3+ts+tsx+vite的antdv中后台管理系统(一)项目总览和环境搭建
一、前言
接触和使用 vue3 快 1 年了, 时至今日, vue3 的生态已经趋于成熟, 已结陆陆续续有不少公司开始使用 vue3 开发项目, 学习和使用 vue3 已是大势所趋. vue3-ts-antd-admin是基于 vue3、ts、tsx、vite 开发的一套中后台管理系统模板, 简洁轻量, 适合中小型中后台项目的开发.
本文会介绍该模板的功能和技术栈, 并从零开始介绍该系统的构造过程.
Github: 传送门
演示地址:传送门
编辑器预览:
二、技术栈
-
前端
vue3: 核心框架 pinia: 状态管理 less: css 预编译器 ant design: 组件库 ts/tsx: 开发和模板语言 vite2: 前端构建工具
-
服务端
koa2: 核心框架 mysql: 数据库 redis: 缓存 ts:开发语言
三、功能
本项目并不复杂, 只实现和保留了(我认为)最核心的部分. 后续会按重要程度和普适性增加功能, 如果有需要的功能也可以给我留言.
目前项目功能如下:
从业务上看, 系统包含:
-
登录注册
-
完整的权限管理模块, 包括 用户管理、角色管理、菜单管理等
-
系统风格样式设置, 如主题色切换、布局切换、整体风格切换、色弱模式等等
从开发的角度上, 系统也对常见功能做了封装:
-
ts、tsx 支持
-
antdv 按需引入
-
基于 eslint、prettier、husky 的完整的校验和格式化支持
-
环境变量支持
-
vue-router 路由支持
-
pinia 状态管理
-
自定义 icon 引入
-
less 支持
-
表单封装
-
图片预览封装
-
常见 筛选表单 + 按钮组 + 表格页面封装
-
axios 请求封装和全局拦截
-
gzip
四、目录结构
├── .husky husky # 脚本
├── .vscode vscode # 配置
├── public
│ └── favicon.ico # 网站图标
├── src
│ ├── api # Api ajax 等
│ ├── assets # 本地静态资源
│ ├── config # 项目全局设置
│ ├── components # 通用组件
│ ├── core # 自定义指令等
│ ├── lib # 依赖包引入
│ ├── router # Vue-Router
│ ├── store # Pinia
│ ├── typings # .d.ts 描述文件
│ ├── utils # 工具库
│ ├── views # 业务页面入口和常用模板
│ └── App.vue # Vue 模板入口
│ └── env.d.ts # 环境变量定义文件
│ └── main.ts # Vue 入口 ts
│ └── permission.ts # 路由守卫(路由权限控制)
└── .env # 环境变量
└── .env.development # 开发环境变量
└── .env.production # 生产环境变量
└── .eslintrc.json # eslint 配置
└── .prettierrc.json # prettier 配置
└── deploy.sh # 部署脚本
└── index.html # Vue 入口模板
└── README.md
└── package.json
└── tsconfig.json
└── tsconfig.node.json
└── vite.config.ts
五、环境搭建
1. 项目创建
使用 vite 社区模板, 即可轻松创建基于 vue3 和 ts 的项目模板
npm init vite@latest
然后按照提示, 依次选择 vue 、 vue-ts , 即可创建 vue3 + ts + vite 项目
2. eslint、 prettier 和 husky 配置
安装依赖
yarn add eslint eslint-config-prettier eslint-plugin-prettier eslint-plugin-vue @typescript-eslint/eslint-plugin @typescript-eslint/parser prettier -D
配置 eslint 和 prettier
- 新增.eslintrc.json
// .eslintrc.json
{
"env": {
"browser": true,
"es2021": true,
"node": true,
"vue/setup-compiler-macros": true
},
"extends": [
"eslint:recommended",
"plugin:vue/vue3-recommended",
"plugin:@typescript-eslint/recommended",
"plugin:prettier/recommended"
],
"parser": "vue-eslint-parser",
"parserOptions": {
"ecmaVersion": "latest",
"parser": "@typescript-eslint/parser",
"sourceType": "module"
},
"plugins": ["vue", "@typescript-eslint"],
"rules": {
"vue/comment-directive": "off",
"prettier/prettier": "off",
// 允许单字单词作为组件名
"vue/multi-word-component-names": "off",
"@typescript-eslint/no-non-null-assertion": "off"
}
}
- 新增.prettierrc.json
// .prettierrc.js
{
"printWidth": 80,
"tabWidth": 2,
"useTabs": false,
"semi": true,
"singleQuote": true
}
- 安装 vscode 插件
安装下列 vscode 插件(已安装可跳过)
- Vue Language Features (Volar)
- Prettier - Code formatter
Volar 可以简单理解为是 vue3 的 Vetur, 如果是既有 vue2 项目又有 vue3 项目的, 可在工作区修改设置
新建.vscode 文件夹, 在.vscode 新建 extensions.json 和 settings.json
// .vscode/extensions.json
{
"recommendations": ["johnsoncodehk.volar"]
}
// .vscode/settings.json
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
"source.fixAll": true
},
"vetur.format.enable": true,
"vetur.validation.script": false,
"vetur.validation.style": false,
"vetur.validation.template": false
}
- 安装 husky
husky 支持所有 git 钩子, 可以用来在提交校验代码
安装 husky
husky 是一款 git-hooks 执行工具, 帮助我们在提交代码时执行一些代码检查或其他的操作, 这里只用到 pre-commit 钩子。
yarn add husky -D
husky 配置
在根目录新建 .husky 文件夹, 在 .husky 下新建 pre-commit 文件
# pre-commit
#!/bin/sh#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx --no-install lint-staged
配置 lint 相关命令
修改 package.json
// package.json
...
"scripts": {
"dev": "vite --mode development",
"build": "vue-tsc --noEmit && vite build --mode production",
"preview": "vite preview",
"lint": "eslint . --ext .vue,.ts,.jsx,.tsx --fix",
"format": "prettier --write ./**/*.{vue,ts,tsx,js,jsx,css,less,scss,json,md}",
"prepare": "husky install"
}
执行 npm run prepare 或者当每次执行 npm install 时, 会初始化 husky, 即在.husky 目录生成*_*文件夹
当我们提交代码时, 会对代码进行全量检查
配置 lint-staged
// package.json
"lint-staged": {
"*.{js,vue,ts,jsx,tsx}": [
"prettier --write",
"eslint --fix"
],
"*.{html,css,less,scss,md}": [
"prettier --write"
]
}
lint-staged 的作用在于可以只对 git staged(暂存区) 中要提交的代码进行检查
3. 路径别名配置 和 文件后缀省略
// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import path from "path";
// https://vitejs.dev/config/
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
"@": resolve("./src"),
"~@": resolve("./src"),
},
// 省略文件后缀
extensions: [".js", ".ts", ".json", ".jsx", ".tsx"],
},
});
4. 添加 css 预处理器 less
安装 less
yarn add less -D
自定义全局 less 变量
在 assets 新建 styles 目录存放样式, 在 styles 下新建 common 目录存放公共样式和变量, 在 common 下新建 common.less、var.css 和 var.less
/* src/assets/styles/common/var.css 存放css变量 */
:root {
--ant-primary-color: #18a058;
}
/* src/assets/styles/common/var.less 存放less变量 */
@primary-color: var(--ant-primary-color, #18a058);
/* src/assets/styles/common/common.less 存放公共样式 */
a {
color: @primary-color;
}
在 vite.config.ts 引入 var.less, var.less 里定义的 less 变量便可以在全局使用
// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import path from "path";
function resolve(url: string): string {
return path.resolve(__dirname, url);
}
// https://vitejs.dev/config/
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
"@": resolve("./src"),
"~@": resolve("./src"),
},
},
css: {
preprocessorOptions: {
less: {
// 全局添加less
additionalData: `@import '@/assets/styles/common/var.less';`,
javascriptEnabled: true,
},
},
},
});
此时 ts 并不能识别 nodejs 的模块, path 会报错, 需要安装@types/node
yarn add @types/node -D
然后修改 tsconfig.node.json
// tsconfig.node.json
{
"compilerOptions": {
"composite": true,
"module": "esnext",
"moduleResolution": "node",
"allowSyntheticDefaultImports": true
},
"include": ["vite.config.ts"]
}
在 App.vue 里引入 var.css 和 common.less
<!-- src/App.vue -->
<script setup lang="ts">
// This starter template is using Vue 3 <script setup> SFCs
// Check out https://vuejs.org/api/sfc-script-setup.html#script-setup
import HelloWorld from "./components/HelloWorld.vue";
</script>
<template>
<HelloWorld msg="Hello Vue 3 + TypeScript + Vite" />
</template>
<style>
@import url("@/assets/styles/common/var.css");
@import url("@/assets/styles/common/common.less");
</style>
5. 开发服务器配置
// vite.config.ts
export default defineConfig({
...
server: {
port: 8001, // 端口
proxy: { // 请求转发
'/api': {
target: 'http://localhost:9002',
ws: false,
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '/api/v1'),
},
'/resource': {
target: 'https://static.fhtwl.cc',
ws: false,
changeOrigin: true,
rewrite: (path) => path.replace(/^\/resource/, ''),
},
},
},
});
6. ts/tsx 配置
在创建项目时, 我们选择 ts - vue-ts ,此时项目已经支持 ts , 支持 tsx 还需要安装插件
yarn add @vitejs/pugin-vue-jsx
配置插件
// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import vueJsx from "@vitejs/plugin-vue-jsx";
export default defineConfig({
plugins: [vue(), vueJsx()],
});
7. antdv 按需引入
安装 antdv
yarn add ant-design-vue
yarn add @ant-design/icons-vue -D
按需加载
安装按需加载插件
yarn add unplugin-vue-components -D
引入插件
// vite.config.ts
import Components from "unplugin-vue-components/vite";
import { AntDesignVueResolver } from "unplugin-vue-components/resolvers";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import vueJsx from "@vitejs/plugin-vue-jsx";
export default defineConfig({
plugins: [
vue(),
vueJsx(),
// 按需加载
Components({
include: [/\.vue$/, /\.tsx$/], // 支持 vue和tsx
resolvers: [
AntDesignVueResolver({
// 不加载css, 而是手动加载css. 通过手动加载less文件并将less变量绑定到css变量上, 即可实现动态主题色
importStyle: false,
// 加载所有icon
resolveIcons: true,
}),
],
}),
],
});
unplugin-vue-components 在监测到项目使用 ts 后, 会在项目根目录生成一个 components.d.ts, 里面即是根据组件内容生成的类型声明, 为 volar 提供类型提示, 他会自动根据文件变动进行更新(注意: compnents.d.ts 文件会在 vue-tsc 运行的时候进行更新,建议把他加入 gitignore 中,以免出现频繁更改导致 git 监测到项目内容一直变动的问题)
unplugin-vue-components 还支持项目中开发的公共组件的自动引入, 即 dirs 配置, 其默认值 就是 src/components, 也就是说, src/components 下的组件同样会被自动引入
挂载全局变量
在 src/lib 下新建 ant-design-vue 目录, 在 ant-design-vue 下新建 index.ts
// src/lib/ant-design-vue/index.ts
import { message, Modal, notification } from "ant-design-vue";
import { App } from "vue";
export default function setupAtnd(app: App<Element>) {
app.config.globalProperties.$message = message;
app.config.globalProperties.$confirm = Modal.confirm;
app.config.globalProperties.$notification = notification;
}
然后在 main.ts 里执行
// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import setupAtnd from "@/lib/ant-design-vue";
const app = createApp(App);
setupAtnd(app);
app.mount("#app");
此时使用 this.message_ 会报错, 提示不存在 _message 这个属性, 因此还需要对这些自定义全局变量进行声明
// src/typings/common/index.d.ts
import { MessageApi } from "ant-design-vue/lib/message";
import { ModalFunc } from "ant-design-vue/lib/modal/Modal";
import { NotificationApi } from "ant-design-vue/lib/notification";
declare module "@vue/runtime-core" {
// 定义绑定在全局vue示例上的变量
interface ComponentCustomProperties {
$message: MessageApi;
$confirm: ModalFunc;
$notification: NotificationApi;
}
}
总结
本文是 从零打造基于 vue3+ts+tsx+vite 的 antdv 中后台管理系统 系列的第一篇, 主要对项目进行了一个整体的介绍以及对开发环境的搭建, 下一步就可以正常开始开发
文中若有错误或者可优化之处, 望请不吝赐教. 如果对你有帮助的话, 麻烦点个赞
转载自:https://juejin.cn/post/7137093609915940878