# UniApp_Template

**Repository Path**: wang119c/UniApp_Template

## Basic Information

- **Project Name**: UniApp_Template
- **Description**: 通用模版
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# uni-app 跨平台项目框架模板

## 📋 项目简介

这是一个基于 `uni-app` 和 `Vue 3` 的跨平台应用框架模板，旨在提供一个结构清晰、功能完善的基础架构，帮助开发者快速启动新的 `uni-app` 项目。该模板整合了状态管理 (Vuex)、API 请求封装、权限控制、全局组件/插件等常用功能，并提供了良好的目录规范。

## 🚀 快速开始

1.  **克隆或下载项目**: 将此模板项目作为新项目的起点。
2.  **安装依赖**: 在项目根目录运行 `npm install` 或 `yarn install`。
3.  **运行项目**: 使用 HBuilderX 或命令行工具运行到不同平台。
    ```bash
    # 开发模式，运行到H5
    npm run dev:h5
    # 开发模式，运行到微信小程序
    npm run dev:mp-weixin
    # 更多运行方式请参考 uni-app 官方文档
    ```

## 📁 目录结构

```
[项目根目录]/
├── main.js                 # 应用入口文件，注册Vuex和全局插件
├── App.vue                 # 根组件
├── pages.json              # 页面路由配置和TabBar配置
├── manifest.json           # uni-app 应用配置清单
├── package.json            # 依赖管理和项目信息
├── config.js               # 环境配置文件 (开发/生产环境API等)
├── uni.scss                # 全局 Sass 样式变量
├── main.scss               # 全局样式入口，导入 static/styles/index.scss
├── permission.js           # 权限配置文件，包含导航拦截逻辑
├── components/             # 公共组件目录
│   ├── CustomTabbar/       # 自定义底部导航栏组件
│   ├── AnimatedBackground/ # 动画背景组件
│   ├── GlobalPopup/        # 全局弹窗组件
│   └── ThemeSelector/      # 主题选择器组件
├── api/                    # API 接口层，按模块划分
│   ├── system.js           # 系统相关接口
│   ├── user.js             # 用户相关接口
│   └── business_module.js  # 业务模块接口示例
├── store/                  # Vuex 状态管理目录
│   ├── index.js            # Vuex Store 入口
│   ├── getters.js          # 全局 Getters
│   └── modules/            # 模块化 Store
│       ├── theme.js        # 主题状态模块
│       └── user.js         # 用户状态模块
├── utils/                  # 工具函数库
│   ├── request.js          # 网络请求封装
│   ├── auth.js             # 认证工具 (Token管理)
│   ├── crypto.js           # 加密工具
│   ├── storage.js          # 存储工具 (uni.setStorageSync等封装)
│   ├── validate.js         # 验证工具
│   ├── common.js           # 通用工具函数
│   ├── constant.js         # 常量定义
│   └── business_util.js    # 业务工具函数示例
├── static/                 # 静态资源目录
│   ├── styles/             # 全局样式文件
│   │   ├── index.scss      # 主样式文件，导入 variables.scss
│   │   ├── variables.scss  # 样式变量定义
│   │   └── harmony-override.css # 鸿蒙系统样式覆盖
│   ├── images/             # 图片资源
│   ├── icons/              # 图标资源
│   └── tabbar/             # TabBar 图标资源
├── plugins/                # 全局插件目录
│   ├── index.js            # 插件入口，注册所有插件
│   └── global-popup.js    # 全局弹窗插件实现
├── pages/                  # 页面目录，按模块划分
│   ├── home/               # 首页
│   ├── login/              # 登录页
│   ├── quizBank/           # 题库页面
│   └── my/                 # 我的页面
└── uni_modules/            # uni-app 第三方模块目录 (若有)
```

## ✨ 核心功能

### 1. 状态管理 (Vuex)

项目采用 `Vuex` 进行状态管理，并使用模块化组织方式，方便管理不同业务模块的状态。

-   **入口**: `store/index.js`
-   **模块**: `store/modules/` (例如 `user.js` 管理用户状态，`theme.js` 管理主题)
-   **使用**: 在 Vue 组件中通过 `useStore` 访问。

### 2. 网络请求封装

`utils/request.js` 封装了 `uni.request`，提供了统一的请求拦截、响应拦截、错误处理等功能，便于 API 调用。

### 3. 权限控制

`permission.js` 通过 `uni.addInterceptor` 实现了全局导航拦截器，在页面跳转前进行登录状态和权限检查，确保用户访问合法的页面。

-   **登录判断**: 依赖 `utils/auth.js` 中的 `getToken` 函数。
-   **白名单**: `permission.js` 中定义了无需登录即可访问的页面列表。

### 4. 全局弹窗插件

`plugins/global-popup.js` 提供了一个全局弹窗机制，可以在任何页面通过 `this.$globalPopup.show()` 调用，实现统一的弹窗体验。

### 5. 环境配置

`config.js` 根据 `process.env.NODE_ENV` 自动切换开发环境和生产环境的配置，主要用于管理不同环境下的 API 基础路径。

### 6. 统一的样式管理

-   `static/styles/variables.scss` 定义了全局的样式变量。
-   `static/styles/index.scss` 导入了变量，并可在此定义全局样式。
-   `main.scss` 作为项目的全局样式入口，负责导入 `static/styles/index.scss`。

## ⚙️ 配置说明

-   **`pages.json`**: 配置所有页面的路径、导航栏样式、底部 `tabBar` 列表等。请根据您的业务需求修改 `pages` 和 `tabBar` 部分。
-   **`manifest.json`**: 配置应用名称、AppID、版本信息、权限、各平台特有配置 (如微信小程序 AppID、App 端打包配置等)。
-   **`config.js`**: 修改 `development` 和 `production` 对象中的 `baseURL` 属性，以适应您的后端服务地址。

## 🛠️ 开发指南

-   **添加新页面**: 在 `pages/` 目录下创建新文件夹和 `.vue` 文件，并在 `pages.json` 中注册该页面。
-   **添加 API 模块**: 在 `api/` 目录下创建新的 JavaScript 文件 (例如 `product.js`)，封装产品相关的 API 请求。
-   **添加新组件**: 在 `components/` 目录下创建新文件夹和 `.vue` 文件。
-   **添加 Vuex 模块**: 在 `store/modules/` 目录下创建新的 JavaScript 文件 (例如 `product.js`)，定义该模块的 `state`、`mutations`、`actions` 和 `getters`，并在 `store/index.js` 中引入。
-   **添加工具函数**: 在 `utils/` 目录下创建新的 JavaScript 文件，封装常用的工具函数。

## ⚠️ 注意事项

-   **文件命名**: 遵循 Vue 社区和 `uni-app` 的推荐命名规范。
-   **代码风格**: 建议配置 ESLint 和 Prettier 保持代码风格一致性。
-   **平台差异**: 针对不同平台 (App、H5、小程序等) 的特殊需求，请使用 `uni-app` 的条件编译 (`#ifdef`, `#ifndef`) 处理。

---

**祝您开发顺利！**