目录
一、环境安装
二、创建项目
三、前端工程化配置
四、引入组件库
五、选择 API 风格
1、选项式 API (Options API)
2、组合式 API (Composition API)
六、页面信息修改
七、通用布局选择
1、基础布局结构
2、全局底部栏
3、动态替换内容
4、全局顶部栏
八、引入 Axios 请求库
1、请求工具库
2、全局自定义请求
3、自动生成请求代码
4、测试请求
补充：
一、环境安装
截止2025.2.6 ，官网发布的vue 3 稳定版本是 V 3.5.13
根据此时的官方文档要求，node 版本需要大于等于 V 18.3
于是使用 nvm 安装 v 20.18.0
二、创建项目
使用 Vue 官方推荐的脚手架 create-vue 快速创建 Vue3 的项目:
快速上手 | Vue.js
在终端中输入命令: npm create vue@latest 但若后续文档升级还想创建现在版本的框架的话，输入 npm create vue@3.12.1
接下来按照如下选项创建项目，脚手架会自动帮我们安装 Vue Router 路由、Pinia 全局状态管理等实用类库 :
然后用 Webstorm 打开项目，先在终端执行 npm install 安装依赖，然后执行 npm run dev
能访问网页就成功了。
运行项目之后，会发现Vue 脚手架提供了一个调试工具 devtools(http://localhost:5173/devtools/)，可以使用它来调试分析项目 :
三、前端工程化配置
脚手架已经帮我们整合了 Prettier 代码美化、ESLint 自动校验、TypeScript 类型校验，无需再自行整合。但是需要在 webstorm 里开启代码美化插件 :
在 vue 文件中执行格式化快捷键，不报错，表示配置工程化成功。如果发现格式化效果不好，也没关系，之后可以使用另外一种格式化快捷键
修改 eslint.config.js、.prettierrc.json、tsconfig.json 文件可以改变校验规则。如果不使用脚手架，就需要自己整合这些工具:
代码规范:https://eslint.org/docs/latest/use/getting-started
代码美化:https://prettier.io/docs/en/install.htm!
直接整合:https://github.com/prettier/eslint-plugin-prettier#recommended-configuration(包括https://github.com/prettier/eslint-config-prettier#installation)
对于前端新手来说，不需要深入了解这些，纯当工具去使用即可，尽快上手项目。
四、引入组件库
引入 Ant Design Vue 组件库，参考 官方文档 快速上手 - Ant Design Vue 快速上手。
注意，本教程使用的是 v4.2.6 的组件库版本，如果后续阅读本教程中发现有组件或语法不一致，以官方文档为主，或者在网站右上角切换对应版本的文档即可:
执行命令：
npm i --save ant-design-vue@4.x
改变主入口文件 main.ts，全局注册组件((为了方便)
import App from './App.vue'
import router from './router'
import Antd from "ant-design-vue";
import "ant-design-vue/dist/reset.css";const app = createApp(App)
app.use(Antd);
app.use(createPinia())
app.use(router)app.mount('#app')
然后在 App.vue 中增加一个按钮组件，测试 Ant Design Vue 组件是否安装成功。
五、选择 API 风格
1、选项式 API (Options API)
使用选项式 API，可以用包含多个选项的对象来描述组件的逻辑，例如 data,methods 和 mounted。选项所定义的属性都会暴露在函数内部的 this 上，它会指向当前的组件实例。
<script>
export default {// data() 返回的属性将会成为响应式的状态// 并且暴露在 `this` 上data() {return {count: 0}},// methods 是一些用来更改状态与触发更新的函数// 它们可以在模板中作为事件处理器绑定methods: {increment() {this.count++}},// 生命周期钩子会在组件生命周期的各个不同阶段被调用// 例如这个函数就会在组件挂载完成后被调用mounted() {console.log(`The initial count is ${this.count}.`)}
}
</script>
<template><button @click="increment">Count is: {{ count }}</button>
</template>2、组合式 API (Composition API)
通过组合式 API，可以使用导入的 API 函数来描述组件逻辑。在单文件组件中，组合式 API 通常会与 <script setup> 搭配使用。这个 setup attribute 是一个标识，告诉 Vue 需要在编译时进行一些处理，让我们可以更简洁地使用组合式 API。比如，<script setup> 中的导入和顶层变量/函数都能够在模板中直接使用。
下面是使用了组合式 API 与 <script setup> 改造后和上面的模板完全一样的组件：
<script setup>
import { ref, onMounted } from 'vue'// 响应式状态
const count = ref(0)// 用来修改状态、触发更新的函数
function increment() {count.value++
}// 生命周期钩子
onMounted(() => {console.log(`The initial count is ${count.value}.`)
})
</script><template><button @click="increment">Count is: {{ count }}</button>
</template>建议遵循 Vue3 的组合式 API(Composition API)，而不是 选项式 AP!,开发更自由高效一些。
六、页面信息修改
修改 html 文件中的 title 和 ico 部分，设置成适合自己项目的信息：
<!DOCTYPE html>
<html lang="">
<head><meta charset="UTF-8"><link rel="icon" href="/bitbug_favicon.ico"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>智能云图库平台</title>
</head>
<body>
<div id="app"></div>
<script type="module" src="/src/main.ts"></script>
</body>
</html>
还可以替换 public 目录下默认的 ico 图标为自己的，有很多 现成的网站（如：在线制作ico图标 | 在线ico图标转换工具 方便制作favicon.ico - 比特虫 - Bitbug.net） 可以制作 ico 图标。效果如图:
七、通用布局选择
1、基础布局结构
在 layouts 日录下新建一个布局 BasicLayout.vue，在 App.vue 全局页面入口文件中引入。App.vue 代码如下 :
<template><div id="app"><BasicLayout/></div>
</template><script lang="ts" setup>
import BasicLayout from "@/layouts/BasicLayout.vue";
</script>
可以移除页面内的默认样式、并且移除 main.ts 中默认引入的 main.css，防止样式污染 :
<style>
#app {
}
</style>
选用 Ant Design 组件库的 Layout 组件 布局 Layout - Ant Design Vue，先把【上中下】布局编排好，然后再填充内容 :
<template><div id="basicLayout"><a-layout style="min-height: 100vh"><a-layout-header>Header</a-layout-header><a-layout-content>Content</a-layout-content><a-layout-footer>Footer</a-layout-footer></a-layout></div>
</template><script setup lang="ts"></script><style scoped>
#basicLayout {
}
</style>并且移除脚手架自带的样式 ，这些都用不上。
2、全局底部栏
通常用于展示版权信息 :
<a-layout-footer class="footer"><a href="https://www.baidu.com" target="_blank"> 智能云图库 by Asukabai</a>
</a-layout-footer>#basicLayout .footer {background: #efefef;padding: 16px;position: fixed;bottom: 0;left: 0;right: 0;text-align: center;
}
3、动态替换内容
项目使用了 Vue Router 路由库 介绍 | Vue Router，可以在 router/index.ts 配置路由，能够根据访问的页面地址找到不同的文件并加载渲染。（比如，此处当路由是 / 时 ，加载的组件是 HomeView , 而 HomeView 组件中又加载了 TheWelcome 于是 <router-view /> 将会把 TheWelcome 的内容显示出来 ）
于是，修改 BasicLayout 内容部分的代码如下 :
<a-layout-content class="content"><router-view />
</a-layout-content>
修改样式，要和底部栏保持一定的外边距，否则内容会被遮住 ：
<style scoped>
#basicLayout .content {background: linear-gradient(to right, #fefefe, #fff);margin-bottom: 28px;padding: 20px;
}
</style>
修改之后，发现即使页面拉倒底，也不会有内容被 footer 所挡住 ：
4、全局顶部栏
由于顶部栏的开发相对复杂，可以基于 Ant Design 的菜单组件 导航菜单 Menu - Ant Design Vue来创建 GlobalHeader 全局顶部栏组件，组件统一放在 components 日录中 。先直接复制现成的组件示例代码到 GlobalHeader 中即可 （此处选择了“水平的顶部导航菜单”）
在基础布局中引入顶部栏组件 :
<a-layout-header class="header"><GlobalHeader />
</a-layout-header>
效果如下 :
样式代码如下:可以修改下全局 Header 的样式，清除一些默认样式(比如背景色等)
接下来要修改 GlobalHeader 组件，完善更多内容。
1) 给菜单外套一层元素，用于整体控制样式 :
<div id="globalHeader"><a-menu v-model:selectedKeys="current" mode="horizontal" :items="items" />
</div>
2) 根据我们的需求修改菜单配置，key 为要跳转的 URL 路径, 并且在组件中选择 icon 切换自己想要的图标：
<script lang="ts" setup>
import { h, ref } from 'vue'
import { HomeOutlined } from '@ant-design/icons-vue'
import { MenuProps } from 'ant-design-vue'const current = ref<string[]>(['home'])
const items = ref<MenuProps['items']>([{key: '/',icon: () => h(HomeOutlined),label: '主页',title: '主页',},{key: '/about',label: '关于',title: '关于',},{key: 'others',label: h('a', { href: 'https://www.baidu.com', target: '_blank' }, '百度一下'),title: '百度一下',},
])
</script>
效果如图: （ “主页” 前多了一个图标显示）
3) 完善全局顶部栏，左侧补充网站图标和标题。
先把 logo.png 放到 src/assets 日录下，替换掉原本的默认 Logo : 修改 GlobalHeader 代码，补充 HTML :
<RouterLink to="/"><div class="title-bar"><img class="logo" src="../assets/logo.png" alt="logo" /><div class="title">鱼皮云图库</div></div>
</RouterLink>
其中，RouterLink 组件的作用是支持超链接跳转(不刷新页面) ，补充 CSS 样式 ：
<style scoped>
.title-bar {display: flex;align-items: center;
}.title {color: black;font-size: 18px;margin-left: 16px;
}.logo {height: 48px;
}
</style>
得到的效果如图所示 ：
4) 完善顶部导航栏，右侧展示当前用户的登录状态 (暂时用登录按钮代替)
<div class="user-login-status"><a-button type="primary" href="/user/login">登录</a-button>
</div>
5) 优化导航栏的布局，采用 栅格组件 的自适应布局 (左中右结构，左侧右侧宽度固定，中间菜单栏自适应)
<a-row :wrap="false"><a-col flex="200px"><RouterLink to="/"><div class="title-bar"><img class="logo" src="../assets/logo.png" alt="logo" /><div class="title">智能云图库</div></div></RouterLink></a-col><a-col flex="auto"><a-menuv-model:selectedKeys="current"mode="horizontal":items="items"/></a-col><a-col flex="120px"><div class="user-login-status"><a-button type="primary" href="/user/login">登录</a-button></div></a-col>
</a-row>
效果如图，可以尝试缩小浏览器窗口观察导航条的变化:
6) 修改路由配置, 目标: 点击菜单项后，可以跳转到对应的页面;并且刷新页面后，对应的菜单自动高亮。按需修改 router/index.ts 文件的 routes 配置，定义我们需要的页面路出，每个 path 对应一个component (要加载的组件)
routes: [{path: '/',name: 'home',component: HomeView,},{path: '/about',name: 'about',// route level code-splitting// this generates a separate chunk (About.[hash].js) for this route// which is lazy-loaded when the route is visited.component: () => import('../views/AboutView.vue'),},
],
观察上述代码，会发现 component 支持直接传入组件、或者使用 impor 按需懒加载组件，按需加载是一种优化首次打开站点性能的方式 。路由跳转: 给 GlobalHeader 的菜单组件绑定跳转事件 :
import { useRouter } from "vue-router";
const router = useRouter();// 路由跳转事件
const doMenuClick = ({ key }: { key: string }) => {router.push({path: key,});
};
修改 HTML 模板，绑定事件 :
<a-menuv-model:selectedKeys="current"mode="horizontal":items="items"@click="doMenuClick"
/>
刷新页面后，你会发现当前菜单项并没有高亮，所以需要同步路由的更新到菜单项高亮
同步高亮原理:
1.点击菜单时，Ant Design 组件已经通过 v-model 绑定 current 变量实现了高亮。
2.刷新页面时，需要获取到当前 URL 路径，然后修改 current 变量的值，从而实现同步。
使用 Vue Router 的 afterEach 路由钩子实现，每次改变路由或刷新页面时都会自动更新 current 的值，从而实现高亮:
const router = useRouter();
// 当前选中菜单
const current = ref<string[]>([]);
// 监听路由变化，更新当前选中菜单
router.afterEach((to, from, next) => {current.value = [to.path];
});
但目前 路由和菜单配置中，有一些是重复的 有没有更好地方式来配置路由和菜单项，不用每次修改时都要改两边的代码呢? ( 答案就是将路由配置数组传递给菜单组件 )
八、引入 Axios 请求库
一般情况下，前端只负责界面展示和动效交互，尽量避免写复杂的逻辑;当需要获取数据时，通常是向后端提供的接口发送请求，由后端执行操作(比如保存数据)并响应数据给前端。
前端如何向后端发送请求呢?最传统的方式是使用 AJAX 技术。但其代码有些复杂，我们可以使用第三方的封装库，来简化发送请求的代码，比如主流的请求工具库 Axios。
1、请求工具库
安装请求工具类 Axios，参考官方文档: https://axios-http.com/docs/intro Getting Started | Axios Docs
npm install axios
2、全局自定义请求
需要自定义全局请求地址等，参考 Axios 官方文档，编写请求配置文件 request.ts 。包括全局接口请求地址、超时时间、自定义请求响应拦截器等。
响应拦截器的应用场景: 需要对接口的 通用响应 进行统一处理，比如从 response 中取出 data; 或者根据 code 去集中处理错误。这样不用在每个接口请求中都去写相同的逻辑。比如可以在全局响应拦截器中，读取出结果中的 data，并校验 code 是否合法，如果是未登录状态，则自动登录。示例代码如下，其中 withcredentials:true 一定要写，否则无法在发请求时携带 Cookie，就无法完成登录。代码如下 :
import axios from 'axios'
import { message } from 'ant-design-vue'// 创建 Axios 实例
const myAxios = axios.create({baseURL: 'http://localhost:8123',timeout: 60000,withCredentials: true,
})// 全局请求拦截器
myAxios.interceptors.request.use(function (config) {// Do something before request is sentreturn config},function (error) {// Do something with request errorreturn Promise.reject(error)},
)// 全局响应拦截器
myAxios.interceptors.response.use(function (response) {const { data } = response// 未登录if (data.code === 40100) {// 不是获取用户信息的请求，并且用户目前不是已经在用户登录页面，则跳转到登录页面if (!response.request.responseURL.includes('user/get/login') &&!window.location.pathname.includes('/user/login')) {message.warning('请先登录')window.location.href = `/user/login?redirect=${window.location.href}`}}return response},function (error) {// Any status codes that falls outside the range of 2xx cause this function to trigger// Do something with response errorreturn Promise.reject(error)},
)export default myAxios
3、自动生成请求代码
如果采用传统开发方式，针对每个请求都要单独编写代码，很麻烦。推荐使用 OpenAP| 工具，直接自动生成即可:https://www.npmjs.com/package/@umijs/openapi按照官方文档的步骤，先安装:
npm i --save-dev @umijs/openapi
openapi.config.js ，根据自己的需要定制生成的代码:
在 **项目根目录 **新建
import { generateService } from '@umijs/openapi'generateService({requestLibPath: "import request from '@/request'",schemaPath: 'http://localhost:8123/api/v2/api-docs',serversPath: './src',
})
注意，要将 schemaPath 改为自己后端服务提供的 Swagger 接口文档的地址。
在package.json的script 中添加"openapi":"node openapi.config.js"
执行即可生成请求代码，还包括 TypeScript 类型:
如果生成过程中出现，环境没装，根据提示安装即可
如此处执行 npm install tslib --save-dev 即可，以后每次后端接口变更时，只需要重新生成一遍就好，非常方便
4、测试请求
可以尝试在任意页面代码中调用 AP1 :
import { healthUsingGet } from '@/api/mainController'healthUsingGet().then((res) => {console.log(res)
})
按 F12 打开开发者工具查看请求，由于我们后端已经添加了全局跨域配置，正常情况下应该能看到如下响应 :
解决跨域 (可选)
如果发现请求错误，要查看错误信息具体分析。比如遇到跨域问题，这是由于前端网页地址和后端请求接口地址不同导致的 :
这种情况下，可以通过修改后端代码，增加全局跨域配置或者跨域注解来解决，如果后端代码无法修改，还可以通过前端代理服务器来解决，如果项目使用 Vite，内置了代理服务器。可以修改 vite.config.ts 文件，增加代理配置 :
export default defineConfig({server: {proxy: {'/api': 'http://localhost:8123',}},
})
同时修改 request.ts，移除请求前缀 :
// 创建 Axios 实例
const myAxios = axios.create({baseURL: '',timeout: 60000,withCredentials: true,
})
这样一来，前端发送的请求域名就等同于当前 URL 的域名，就不会出现跨域。但是访问到 /api开头的接口时，会被代理到请求 8123 端口的后端服务器，从而完成请求。当然，前端还有很多代理工具，比如 Whistle 。
补充：
在后续开发中你会发现，Ant Design Vue 默认使用的是英文文案，如果需要替换为中文，可以参考 国际化文档，只需给整个应用包裹一层组件即可完成。
