前端 Vue3 开发手册

使用 JavaFree Web 前端 Vue3 模板工程 是快速构建企业级应用的理想起点。该模板已集成以下现代前端技术栈：

• UI 组件库：TDesign Vue Next + Element Plus（双库兼容）
• 构建工具：Vite 5（极速冷启动与热更新）
• 状态管理：Pinia（TypeScript 友好）
• 路由方案：Vue Router 4（动态路由支持）
• 语言支持：TypeScript + JSX/TSX（可选）
• 工程规范：ESLint + Prettier + Husky（代码质量保障）
• 样式预处理器：Less（variables.less 主题变量）

本章将引导您基于该模板高效完成页面开发、权限控制、主题定制等核心任务。

1. 项目初始化与启动

获取代码

💡 关键说明：前端是私有项目，需要获得开发者授权才可访问

git clone https://gitee.com/javafree-cloud/javafree-cloud-web-vue3.git
cd javafree-cloud-web-vue3

安装依赖

推荐使用 pnpm（更快、更节省磁盘）：

pnpm install
# 或 npm install / yarn install

配置环境

1. 后端接口地址 编辑 .env.development：

   VITE_API_URL=http://127.0.0.1:7080

2. 前端开发端口 修改 package.json 中的 dev 脚本：

   "scripts": {
     "dev": "vite --open --port 8000 --mode development"
   }

启动开发服务器

pnpm dev

✅ 成功启动后，浏览器将自动打开 http://localhost:8000

2. 项目结构概览

src/
├── api/                # 接口定义（按模块组织）
│   ├── login/
│   │   └── model/      # 请求/响应模型
│   └── system/
│       ├── detail.ts
│       ├── list.ts
│       └── permission.ts
├── assets/             # 静态资源（图片、字体等）
├── components/         # 全局公共组件
├── config/             # 全局配置（常量、主题色等）
│   ├── color.ts        # 主题色彩配置
│   ├── global.ts       # 全局常量定义
│   └── style.ts        # 布局样式常量
├── constants/          # 业务常量（状态码、枚举等）
├── directives/         # 自定义指令（如 v-permission）
│   └── permission.ts
├── hooks/              # 自定义 Composition API
├── layouts/            # 页面布局组件（默认/空白/设置页等）
├── locales/            # 国际化语言包
├── pages/              # 业务页面（按功能模块划分）
│   ├── dashboard/      # 示例：仪表盘
│   └── system/         # 示例：系统管理
├── router/             # 路由配置（含动态路由逻辑）
├── store/              # Pinia 状态管理（模块化）
│   └── modules/
│       └── index.ts
├── style/              # 全局样式（重置、变量、布局）
│   ├── reset.less      # 样式重置
│   ├── variables.less  # 设计 Token 变量（主色、字体等）
│   ├── layout.less     # 布局通用样式
│   ├── font-family.less # 字体配置（腾讯体W7）
│   └── index.less      # 全局样式入口
├── types/              # TypeScript 类型定义
├── utils/              # 工具函数（请求、路由、工具类）
├── App.vue             # 根组件
└── main.ts             # 应用入口

💡 关键说明：

• 样式使用 Less，所有全局样式均在 src/style/ 下管理
• variables.less 是主题变量的核心文件，用于覆盖 TDesign/Element Plus 的主题色
• index.less 为全局样式入口，通常包含 @import 所有其他样式文件

3. 创建新页面示例

用户管理（树表联动示例）

界面示意图：

步骤 1：创建页面组件

创建入口 页面，本页面包括左右两部分

路径：src/pages/system/orgmanager/user/index.vue

<template>
  <LeftRightLayout
    :left-width="260"
    :min-height="200"
    :divider-width="3"
  >
    <template #left>
      <DeptTree ref="deptTreeRef" @node-click="handleNodeClick" />
    </template>
    <template #right>
      <UserTable :dept-id="selectedDeptId" @refresh-tree="handleRefreshTree" />
    </template>
  </LeftRightLayout>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import DeptTree from './components/DeptTree.vue'
import UserTable from './components/UserTable.vue'

const selectedDeptId = ref<string | null>(null)
const deptTreeRef = ref<InstanceType<typeof DeptTree> | null>(null)

const handleNodeClick = (deptId: string) => {
  selectedDeptId.value = deptId
}

const handleRefreshTree = () => {
  deptTreeRef.value?.refreshTree()
}
</script>

✅ 关键点说明：

• 使用 <LeftRightLayout> 布局组件实现左右分栏
• 通过 ref 调用子组件方法（需在子组件暴露 defineExpose）
• 数据通过 props 传递，事件通过 $emit 通信
• DeptTree和UserTable组件详见前端代码工程

步骤 2：配置路由（开发阶段）

📌 正式环境请通过「菜单管理」动态配置路由（系统管理 → 授权管理 → 菜单管理）

菜单管理界面：

本地测试可临时添加路由（src/router/index.ts）：

{
  path: '/system/user',
  name: 'UserManager', // 必须与组件 name 一致，用于多页签状态保持
  component: () => import('@/pages/system/orgmanager/user/index.vue'),
  meta: { title: '用户管理', requiresAuth: true }
}

步骤 3：定义 API 接口

路径：src/api/system/org/user/index.ts

// src/api/system/org/user/index.ts
import { ApiParamBody, ApiResponse } from '@/types/common';
import { requestExt } from '@/utils/request';
import { UserVO } from './typings';

const Api = {
  UsersTable: '/org-user/findUsersTable',
  SaveUser: '/sa-user/saveUserWithPassword',
  UserDetail: '/org-user/getUserById',
  DeleteUser: '/org-user/deleteUsersByIds',
};

// 删除用户
export function removeUsers(ids: string) {
  return requestExt.delete<ApiResponse<any>>({
    url: `${Api.DeleteUser}?ids=${ids}`,
  });
}

// 获取用户列表
export function getUsersTable(data: ApiParamBody<UserVO>) {
  return requestExt.post<ApiResponse<any>>({
    url: Api.UsersTable,
    data,
  });
}

// 获取用户详情
export function getUserById(id: string) {
  return requestExt.get<ApiResponse<any>>({
    url: `${Api.UserDetail}?id=${id}`,
  });
}

// 保存用户（含密码）
export function saveUser(data: Record<string, any>) {
  return requestExt.post<ApiResponse<UserVO>>({
    url: Api.SaveUser,
    data,
  });
}

4. 构建与部署

构建生产包

pnpm build

产物位于 dist/ 目录。

Nginx 部署示例

server {
  listen 8070;
  root /usr/share/nginx/html;
  index index.html;

  # 前端路由 fallback
  location / {
    try_files $uri $uri/ /index.html;
  }

  # API 代理（解决跨域）
  location /api {
    proxy_pass http://localhost:7080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    rewrite ^/api/(.*)$ /$1 break;
  }

  # 启用 Gzip
  gzip on;
  gzip_types text/css application/javascript;
}

🌐 部署建议：

• 生产环境务必开启 Gzip
• 静态资源建议配置 CDN
• 后端接口通过 Nginx 代理，避免前端暴露真实地址

5. 开发最佳实践

类别	建议
代码规范	严格遵循 ESLint + Prettier 规则
组件设计	优先封装到 components/，避免页面内重复逻辑
API 管理	所有接口集中管理，禁止在组件内直接写 URL
类型安全	为 Props、API 响应、Store 状态定义 TypeScript 接口
性能优化	路由组件使用懒加载 () => import(...)
文档查阅	• TDesign Vue Next • Element Plus

🎯 总结： JavaFreeCloud Vue3 模板已为您搭建好企业级应用的“高速公路”。 您只需专注业务逻辑开发，遵循本手册规范，即可高效交付高质量前端应用。