首页 前端知识 Vue 3 搭建前端模板并集成 Ant Design Vue(2025)

Vue 3 搭建前端模板并集成 Ant Design Vue(2025)

2025-03-15 13:03:38 前端知识 前端哥 936 75 我要收藏

目录

一、环境安装

二、创建项目

三、前端工程化配置

四、引入组件库

五、选择 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-menu
      v-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-menu
  v-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 sent
    return config
  },
  function (error) {
    // Do something with request error
    return 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 error
    return 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 默认使用的是英文文案,如果需要替换为中文,可以参考 国际化文档,只需给整个应用包裹一层组件即可完成。

转载请注明出处或者链接地址:https://www.qianduange.cn//article/23763.html
标签
评论
会员中心 联系我 留言建议 回顶部
复制成功!