# common-template-v3

**Repository Path**: rawcloud/common-template-v3

## Basic Information

- **Project Name**: common-template-v3
- **Description**: 一套基于 Vue 3 + Vite + TypeScript 的通用前端项目模板，内置了可视化大屏常用的基础能力与组件，开箱即用。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/rawcloud/common-template-v3
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-07-22
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# common-template-v3

> 📖 English version: [README.en.md](./README.en.md)

一套基于 **Vue 3 + Vite + TypeScript** 的通用前端项目模板，内置了后台管理系统与可视化大屏常用的基础能力与组件，开箱即用。

## 技术栈

| 分类 | 技术 |
| --- | --- |
| 框架 | [Vue 3](https://vuejs.org/)（`<script setup>` 语法） |
| 构建工具 | [Vite 5](https://vitejs.dev/) |
| 语言 | TypeScript 5 |
| 状态管理 | [Pinia](https://pinia.vuejs.org/) |
| 路由 | [Vue Router 4](https://router.vuejs.org/) |
| UI 组件库 | [Element Plus](https://element-plus.org/)（按需自动导入） |
| 图表 | [ECharts 5](https://echarts.apache.org/) |
| 三维地图 | [Vue Cesium](https://vue-cesium.com/) + 天地图 Token |
| 网络请求 | [Axios](https://axios-http.com/)（封装于 `src/plugins/axios.ts`、`src/utils/request.ts`） |
| 事件总线 | [mitt](https://github.com/developit/mitt)（`src/utils/bus.ts`） |
| 样式 | Sass |
| 代码规范 | ESLint（Vue 官方 TS 配置） |
| 单元测试 | [Vitest](https://vitest.dev/) + jsdom |

## 目录结构

```
common-template-v3/
├── conf.js                 # 全局配置（接口地址、系统名称、天地图 Token 等）
├── vite.config.ts          # Vite 配置（别名、Element Plus 自动导入、代理示例）
├── src/
│   ├── api/                # 接口定义（按需补充）
│   ├── assets/             # 静态资源（图片、样式、视频）
│   ├── components/         # 公共组件
│   │   ├── HelloWorld.vue
│   │   ├── MyCharts.vue    # ECharts 封装组件
│   │   └── ScaleBox.vue    # 大屏自适应缩放容器
│   ├── directive/          # 自定义指令
│   │   ├── drag.ts         # 拖拽
│   │   ├── permission.ts   # 权限控制
│   │   └── preReclick.ts   # 防重复点击
│   ├── plugins/            # 插件（axios 实例等）
│   ├── router/             # 路由配置
│   ├── stores/             # Pinia 状态管理
│   ├── utils/              # 工具函数
│   │   ├── auth.ts         # 认证 / Token
│   │   ├── bus.ts          # 事件总线
│   │   ├── common.ts       # 通用方法
│   │   ├── dateUtil.ts     # 日期处理
│   │   ├── rem.ts          # 大屏 rem 适配
│   │   ├── request.ts      # 请求封装
│   │   └── validate.ts     # 校验规则
│   ├── views/              # 页面视图
│   │   ├── common/
│   │   ├── demo/
│   │   ├── HomeView.vue
│   │   └── AboutView.vue
│   ├── App.vue
│   └── main.ts
└── ...
```

## 环境要求

- Node.js 20+
- npm（或 pnpm / yarn）

## 快速开始

```sh
# 安装依赖
npm install

# 启动开发服务器（默认自动打开浏览器）
npm run dev
```

开发服务器默认开启 `server.open`，启动后会自动打开浏览器。如需配置接口代理，取消 `vite.config.ts` 中 `server.proxy` 的注释并按需修改。

## 常用脚本

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 启动开发服务器，支持热更新 |
| `npm run build` | 类型检查 + 生产构建（先 `vue-tsc` 再 `vite build`） |
| `npm run preview` | 本地预览生产构建产物 |
| `npm run test:unit` | 运行 Vitest 单元测试 |
| `npm run lint` | 使用 ESLint 检查并自动修复代码 |
| `npm run type-check` | 仅执行 TypeScript 类型检查 |
| `npm run build-only` | 仅执行 Vite 生产构建（不做类型检查） |

## 全局配置

项目根目录下的 `conf.js` 存放全局运行配置，可按需修改：

```js
const conf = {
  baseURL: "http://10.1.100.81/",   // 接口基础地址
  sysName: "XXXX系统",              // 系统名称
  tdtToken: "xxxxxxxx",             // 天地图 Token（Cesium 底图使用）
};
```

## 功能特性

- **Element Plus 按需自动导入**：基于 `unplugin-auto-import` 与 `unplugin-vue-components`，无需手动 `import` 组件与 API。
- **大屏自适应**：提供 `ScaleBox` 缩放容器与 `rem.ts` 适配方案，适合可视化大屏项目。
- **ECharts 封装**：`MyCharts.vue` 提供开箱即用的图表容器。
- **三维地图**：集成 Vue Cesium，结合 `conf.js` 中的天地图 Token 加载底图。
- **请求封装**：Axios 实例统一封装，含拦截器与 `request.ts` 便捷方法。
- **权限与指令**：内置 `permission` 权限指令、`drag` 拖拽指令、`preReclick` 防重复点击指令。
- **事件总线**：基于 mitt 的全局事件通信（`utils/bus.ts`）。

## 推荐开发工具

- [VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) 扩展（**请禁用 Vetur**）。
- 类型支持：使用 `vue-tsc` 进行类型检查；在编辑器中借助 Volar 让 TypeScript 语言服务识别 `.vue` 类型。

## 自定义配置

- Vite 配置参考：[Vite 官方文档](https://vitejs.dev/config/)。
- TypeScript 相关配置见 `tsconfig.json`、`tsconfig.app.json`、`tsconfig.node.json`。

## 许可证

详见 [LICENSE](./LICENSE)。