# vue3TsPro

**Repository Path**: code_tjf/vue3-ts-pro

## Basic Information

- **Project Name**: vue3TsPro
- **Description**: 前端基础框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue3 + TypeScript + Ant Design Vue 前端框架

## 项目介绍

这是一个基于 Vue 3 + TypeScript + Ant Design Vue + Pinia + Router + Vite 构建的前端基础框架，包含了完整的用户登录、权限管理、主题切换、路由配置等功能，可作为实际项目的起点。

## 技术栈

- **Vue 3** - 前端框架
- **TypeScript** - 类型系统
- **Ant Design Vue** - UI 组件库
- **Pinia** - 状态管理
- **Vue Router** - 路由管理
- **Vite** - 构建工具
- **Less** - CSS 预处理器
- **pinia-plugin-persistedstate** - Pinia 持久化插件

## 快速开始

### 环境要求

- Node.js >= 16
- npm >= 7 或 pnpm >= 6

### 安装依赖

```bash
# 使用 npm
npm install

# 使用 pnpm
pnpm install
```

### 启动开发服务器

```bash
# 使用 npm
npm run dev

# 使用 pnpm
pnpm dev
```

### 构建生产版本

```bash
# 使用 npm
npm run build

# 使用 pnpm
pnpm build
```

### 预览生产构建

```bash
# 使用 npm
npm run preview

# 使用 pnpm
pnpm preview
```

## 项目结构

```
vue3TsPro/
├── public/             # 静态资源
├── src/
│   ├── assets/         # 资源文件
│   ├── components/     # 组件
│   │   ├── HorizontalMenu.vue  # 水平菜单
│   │   ├── ThemeSwitch.vue     # 主题切换
│   │   └── VerticalMenu.vue    # 垂直菜单
│   ├── router/         # 路由配置
│   │   └── index.ts
│   ├── stores/         # 状态管理
│   │   ├── index.ts    # Pinia 初始化
│   │   ├── permission.ts  # 权限管理
│   │   ├── theme.ts    # 主题管理
│   │   └── user.ts     # 用户管理
│   ├── utils/          # 工具类
│   │   ├── array.ts    # 数组处理
│   │   ├── confirm.ts  # 确认对话框
│   │   ├── date.ts     # 日期处理
│   │   ├── debounce.ts # 防抖节流
│   │   ├── index.ts    # 工具类入口
│   │   ├── message.ts  # 消息提示
│   │   ├── request.ts  # API 请求
│   │   ├── storage.ts  # 本地存储
│   │   └── string.ts   # 字符串处理
│   ├── views/          # 页面
│   │   ├── role/       # 角色管理
│   │   ├── user/       # 用户管理
│   │   ├── 404View.vue
│   │   ├── AboutView.vue
│   │   ├── HomeView.vue
│   │   └── LoginView.vue
│   ├── App.vue         # 根组件
│   └── main.ts         # 入口文件
├── .gitignore
├── index.html
├── package.json
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts
```

## 核心功能

### 1. 路由管理

- **动态路由** - 根据权限生成路由
- **路由守卫** - 登录验证和权限检查
- **嵌套路由** - 支持多级菜单

### 2. 状态管理

- **用户管理** - 登录、登出、用户信息管理
- **权限管理** - 菜单权限和按钮权限
- **主题管理** - 浅色/深色主题切换
- **持久化** - 使用 pinia-plugin-persistedstate 实现状态持久化

### 3. UI 组件

- **菜单组件** - 水平菜单和垂直菜单
- **主题切换** - 支持浅色/深色主题
- **用户信息** - 顶部用户信息显示和退出登录
- **模态框** - 封装的模态框组件
- **表格** - 封装的表格组件

### 4. 工具类

- **API 请求** - 支持多域名、文件上传下载
- **消息提示** - 封装的消息提示框
- **确认对话框** - 封装的确认对话框
- **日期处理** - 日期格式化和计算
- **字符串处理** - 字符串格式化和验证
- **数组处理** - 数组去重、排序、分组等
- **本地存储** - 封装的本地存储操作
- **防抖节流** - 防抖和节流函数

## 使用说明

### 登录

1. 访问 `/login` 页面
2. 使用默认账号密码登录：
   - 用户名：`admin`
   - 密码：`123456`

### 主题切换

- 在顶部导航栏右侧点击主题切换按钮，可在浅色和深色主题之间切换
- 主题设置会自动保存，刷新页面后保持不变

### 退出登录

- 点击顶部导航栏右侧的用户头像，在下拉菜单中选择“退出登录”
- 退出后会跳转到登录页面

### 路由配置

- **静态路由** - 在 `src/router/index.ts` 中配置
- **动态路由** - 在 `src/stores/permission.ts` 中生成
- **路由元信息** - 支持以下元信息：
  - `hidden` - 是否在菜单中隐藏
  - `hiddenFullMenu` - 是否隐藏全屏菜单（如登录页、404页）
  - `hiddenSider` - 是否隐藏侧边栏（只显示顶部菜单）

### 菜单配置

- **垂直菜单** - 位于左侧，支持多级菜单
- **水平菜单** - 位于顶部，显示一级菜单
- **菜单数据** - 在 `src/stores/permission.ts` 中配置
- **菜单显示** - 根据路由元信息和用户权限动态生成

### 页面布局

- **正常布局** - 顶部菜单 + 侧边菜单 + 内容区域
- **全屏布局** - 只显示内容区域（如登录页、404页），通过 `hiddenFullMenu: true` 实现
- **无侧边栏布局** - 顶部菜单 + 内容区域，通过 `hiddenSider: true` 实现

### 面包屑导航

- **功能** - 显示当前页面的路径，支持点击跳转
- **位置** - 位于内容区域的顶部
- **实现** - 在 `src/components/Breadcrumb.vue` 中实现
- **显示逻辑** - 根据当前路由自动生成，全屏页面不显示面包屑
- **路由配置** - 通过路由的 `meta.title` 属性设置面包屑标题

### 全局样式配置

- **实现** - 在 `src/styles/global.less` 中定义
- **内容** - 包含变量定义、全局重置、基础样式、工具类和响应式设计
- **使用方法** - 直接在组件中使用定义的变量和类名
- **主题支持** - 支持浅色和深色主题
- **变量定义** - 包含颜色、字体、间距等基础变量

### 动态表单组件

- **实现** - 在 `src/components/DynamicForm.vue` 中实现
- **功能** - 根据配置动态生成表单项，支持多种表单控件类型
- **支持的控件类型** - 输入框、密码框、文本域、下拉选择、单选框、复选框、日期选择器、时间选择器、开关、滑块、嵌套表单、动态数组
- **使用方法** - 通过配置对象定义表单项，支持表单验证、数据双向绑定
- **示例** - 在 `src/views/DynamicFormDemo.vue` 中提供了完整的使用示例

**使用示例：**
```vue
<template>
  <dynamic-form
    v-model:form-data="formData"
    :form-config="formConfig"
    :rules="rules"
    @submit="handleSubmit"
    @reset="handleReset"
  />
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue'
import DynamicForm from '@/components/DynamicForm.vue'

// 表单配置
const formConfig = ref([
  {
    key: 'name',
    label: '姓名',
    type: 'input',
    placeholder: '请输入姓名',
    required: true
  },
  {
    key: 'gender',
    label: '性别',
    type: 'radio',
    options: [
      { value: 'male', label: '男' },
      { value: 'female', label: '女' }
    ]
  }
])

// 表单数据
const formData = reactive({
  name: '',
  gender: 'male'
})

// 表单验证规则
const rules = {
  name: [{ required: true, message: '请输入姓名', trigger: 'blur' }]
}

// 处理表单提交
const handleSubmit = (data) => {
  console.log('表单提交数据:', data)
}

// 处理表单重置
const handleReset = () => {
  console.log('表单重置')
}
</script>
```



### 树形列表组件

- **功能** - 显示树形结构数据，支持选择、勾选、展开/折叠、拖拽等功能
- **实现** - 在 `src/components/TreeList.vue` 中实现
- **使用示例**：
  ```vue
  <tree-list
    :tree-data="treeData"
    :default-expanded-keys="['1', '2']"
    :default-selected-keys="['1-1']"
    :checkable="true"
    @select="handleSelect"
    @check="handleCheck"
  >
    <template #title="{ title, level }">
      <span>{{ level }}级: {{ title }}</span>
    </template>
  </tree-list>
  ```

### 级联选择组件

- **功能** - 用于选择层级关系数据，支持搜索、清除、标签展示等功能
- **实现** - 在 `src/components/CascadeSelect.vue` 中实现
- **使用示例**：
  ```vue
  <cascade-select
    v-model="selectedValue"
    :options="options"
    placeholder="请选择地区"
    :show-search="true"
    @change="handleChange"
  >
    <template #option="{ node }">
      <span>{{ node.label }}</span>
    </template>
  </cascade-select>
  ```

### 权限管理

- 菜单权限在 `src/stores/permission.ts` 中配置
- 按钮权限可使用 `usePermissionStore().hasPermission()` 方法检查

## 部署

### 构建生产版本

```bash
npm run build
```

构建产物会生成在 `dist` 目录中，可部署到任何静态文件服务器。

### Nginx 配置示例

```nginx
server {
  listen 80;
  server_name example.com;
  
  location / {
    root /path/to/dist;
    index index.html;
    try_files $uri $uri/ /index.html;
  }
}
```

## 注意事项

1. **API 请求** - 实际项目中需要修改 `src/utils/request.ts` 中的 `baseURL` 为真实的 API 地址
2. **登录逻辑** - 实际项目中需要修改 `src/views/LoginView.vue` 中的登录逻辑，调用真实的登录 API
3. **权限管理** - 实际项目中需要从后端获取菜单和权限数据，修改 `src/stores/permission.ts` 中的 `generateRoutes` 方法
4. **主题样式** - 可根据项目需求修改 `src/App.vue` 中的深色主题样式
5. **组件扩展** - 可根据项目需求扩展或修改现有组件

## 开发规范

1. **命名规范**
   - 组件名：大驼峰命名法（PascalCase）
   - 变量名：小驼峰命名法（camelCase）
   - 文件名：小驼峰命名法（camelCase）或短横线分隔（kebab-case）

2. **代码风格**
   - 使用 TypeScript 类型注解
   - 使用 ES6+ 语法
   - 遵循 ESLint 规则

3. **目录结构**
   - 按功能模块组织代码
   - 组件放在 `components` 目录
   - 页面放在 `views` 目录
   - 工具类放在 `utils` 目录

## 常见问题

### 1. 登录后页面显示 404

- 检查路由配置是否正确
- 检查路由守卫是否正常工作
- 检查动态路由是否正确生成

### 2. 主题切换不生效

- 检查 `src/stores/theme.ts` 中的配置
- 检查 `src/App.vue` 中的深色主题样式

### 3. 退出登录后仍能访问受保护的路由

- 检查路由守卫中的登录验证逻辑
- 检查 `src/stores/user.ts` 中的 `logout` 方法

## 许可证

MIT