# one-admin-vue3-sfc-web

**Repository Path**: nbnat/one-admin-vue3-sfc-web

## Basic Information

- **Project Name**: one-admin-vue3-sfc-web
- **Description**: 项目使用无构建工具的开发方式，依赖 vue3-sfc-loader 完美加载 Vue3 ,element-plus前端,element-icon图标库,Pinia状态管理,VueRouter路由管理

- **Primary Language**: HTML/CSS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://www.nbnat.com
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-09
- **Last Updated**: 2025-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# One-Admin 项目说明文档

## 项目概述

One-Admin 是一个基于 Vue 3 的后台管理系统示例项目，采用了现代化的前端技术栈，包括 Vue 3、Vue Router、Pinia、Element Plus 和 One-Admin-Plus 组件库。项目使用了无构建工具的开发方式，通过 vue3-sfc-loader 实现了 Vue 单文件组件的动态加载。

## 技术栈

项目使用了以下主要技术和库：

- **Vue 3**：核心框架，用于构建用户界面
- **Vue Router**：官方路由管理器
- **Pinia**：Vue 的状态管理库，替代 Vuex
- **Element Plus**：基于 Vue 3 的组件库
- **One-Admin-Plus**：自定义管理系统组件库
- **Axios**：HTTP 客户端，用于发送请求
- **vue3-sfc-loader**：动态加载 Vue 单文件组件

## 项目结构

```
one-admin
├── api                 # API 接口定义
├── assets              # 静态资源
├── components          # 公共组件
│   ├── RedirectLayout  # 重定向布局组件
│   └── RouterLayout    # 路由布局组件
├── layout              # 布局相关组件
│   └── components      # 布局子组件
├── router              # 路由配置
├── static              # 第三方库静态资源
├── store               # Pinia 状态管理
├── styles              # 全局样式
├── util                # 工具函数
└── view                # 页面视图组件
```

## 引入的 JS 文件说明

### 核心框架

1. **Vue 3**
   - 文件：`./static/vue/dist/vue.global.prod.js`
   - 用途：提供 Vue 3 核心功能，包括响应式系统、组件系统等
   - 使用方式：通过 `const { createApp } = Vue` 创建应用实例

2. **Vue Router**
   - 文件：`./static/vue-router/dist/vue-router.global.js`
   - 用途：提供路由管理功能
   - 使用方式：通过 `window.appRouter` 全局访问路由实例

3. **Pinia**
   - 文件：`./static/pinia/pinia.iife.js`
   - 用途：状态管理库，替代 Vuex
   - 使用方式：通过 `Pinia.createPinia()` 创建 Pinia 实例，并通过 `useUserStore` 和 `useThemeStore` 访问状态

### UI 组件库

1. **Element Plus**
   - 文件：
     - `./static/element-plus/dist/index.full.js`（JS）
     - `./static/element-plus/dist/index.css`（CSS）
     - `./static/element-plus/dist/icon.js`（图标）
     - `./static/element-plus/dist/locale/zh-cn.min.js`（中文语言包）
   - 用途：提供丰富的 UI 组件
   - 使用方式：通过 `app.use(ElementPlus, { locale: window.ElementPlusLocaleZhCn })` 全局注册

2. **One-Admin-Plus**
   - 文件：
     - `./static/one-admin/one-admin-plus.umd.cjs`（组件库）
     - `./static/one-admin/one-admin-icons.umd.cjs`（图标库）
     - `./static/one-admin/one-admin-plus.css`（样式）
   - 用途：提供管理系统专用组件
   - 使用方式：通过 `app.use(OneAdminPlus.default)` 全局注册

### 工具库

1. **Axios**
   - 文件：`./static/axios/dist/axios.min.js`
   - 用途：HTTP 客户端，用于发送 API 请求
   - 使用方式：通过 `app.config.globalProperties.$http = axios` 全局注册

2. **vue3-sfc-loader**
   - 文件：`./static/vue3-sfc-loader/dist/vue3-sfc-loader.js`
   - 用途：动态加载 Vue 单文件组件
   - 使用方式：通过 `window.loadModule` 加载 Vue 组件

3. **Lodash**
   - 文件：`./static/lodash.js`（CDN）
   - 用途：提供实用的 JavaScript 工具函数
   - 使用方式：通过全局 `_` 对象访问

### 自定义工具和配置

1. **工具函数**
   - 文件：
     - `./util/token-util.js`：Token 相关工具
     - `./util/use-page-tab.js`：页签管理工具
     - `./util/core.js`：核心工具函数
     - `./util/use-form-data.js`：表单数据处理
     - `./util/common.js`：通用工具函数
     - `./util/request.js`：请求封装
   - 用途：提供各种工具函数和封装

2. **路由配置**
   - 文件：
     - `./router/routes.js`：路由定义
     - `./router/index.js`：路由配置和初始化
   - 用途：定义应用的路由结构

3. **API 请求**
   - 文件：
     - `./api/login.js`：登录相关 API
     - `./api/layout.js`：布局相关 API
   - 用途：封装 API 请求函数

4. **状态管理**
   - 文件：
     - `./store/user.js`：用户状态管理
     - `./store/theme.js`：主题状态管理
   - 用途：管理应用状态

## 主要组件使用

### 布局组件

项目使用 `ele-pro-layout` 作为主要布局组件，提供了以下功能：

1. **菜单管理**：支持多级菜单、菜单折叠、唯一展开等功能
2. **页签管理**：支持多页签、页签排序、右键菜单等功能
3. **布局切换**：支持多种布局模式（默认、顶部、混合）
4. **主题定制**：支持自定义主题颜色、布局风格等

### 图标组件

项目同时使用了 Element Plus 和 One-Admin 的图标库：

```javascript
// 全局注册 Element Plus 图标
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(key, component)
  window.ICONS.push(key);
}

// 全局注册 One-Admin 图标
for (const [key, component] of Object.entries(OneAdminIconsVue)) {
  app.component(key, component)
  window.ICONS.push(key);
}
```

### 路由组件

项目使用 `router-view` 和自定义的 `router-layout` 组件来渲染路由内容：

```html
<ele-app>
  <router-view />
</ele-app>
```

## 全局配置

项目定义了多个全局配置常量：

```javascript
/** 项目名称 */
const PROJECT_NAME = "测试项目";
/** 不需要登录的路由 */
const WHITE_LIST = ["/login", "/forget"];
/** 首页路径, 为空则取第一个菜单的地址 */
const HOME_PATH = "/";
/** 外层布局的路由地址 */
const LAYOUT_PATH = "/";
/** 刷新路由的路由地址 */
const REDIRECT_PATH = "/redirect";
/** 开启页签栏后是否缓存组件 */
const TAB_KEEP_ALIVE = true;
/** token本地缓存的名称 */
const TOKEN_CACHE_NAME = "token";
```

## 应用初始化流程

1. 创建 Pinia 实例并挂载到全局
2. 配置 vue3-sfc-loader 选项
3. 创建 Vue 应用实例
4. 加载状态管理模块（user.js 和 theme.js）
5. 初始化路由
6. 注册全局插件（Router、Pinia、Element Plus、One-Admin-Plus）
7. 注册全局图标组件
8. 设置全局属性
9. 挂载应用到 DOM

## 开发指南

1. 页面开发：在 `view` 目录下创建对应的页面组件
2. 路由配置：在 `router/routes.js` 中添加路由配置
3. API 开发：在 `api` 目录下添加 API 请求函数
4. 状态管理：在 `store` 目录下添加 Pinia store

## 注意事项

1. 项目使用无构建工具的开发方式，依赖 vue3-sfc-loader 加载 Vue 组件
2. 全局变量和函数通过 window 对象暴露，便于跨文件访问
3. 项目使用 Element Plus 作为 UI 组件库，遵循其设计规范