You've already forked template-MP
216 lines
9.1 KiB
Markdown
216 lines
9.1 KiB
Markdown
# 项目概述 - IFLOW 上下文
|
||
|
||
这是一个基于 UniApp + Vue3 + uView-Plus 的微信小程序项目模板。它提供了一个基础的项目结构和一些常用的工具函数、自定义Hooks、组件等，方便快速开发微信小程序。
|
||
|
||
## 技术栈
|
||
|
||
* **UniApp**: 跨平台开发框架，用于构建微信小程序。
|
||
* **Vue3**: 渐进式 JavaScript 框架，用于构建用户界面，采用 Composition API 和 setup 语法糖。
|
||
* **uView-Plus**: 基于 UniApp 的 UI 组件库。
|
||
* **z-paging**: 一个用于处理分页加载的组件库。
|
||
* **luch-request**: 网络请求库，用于封装 HTTP 请求。
|
||
* **ESLint & Prettier**: 代码规范和格式化工具。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.
|
||
├── api/ # 接口相关
|
||
│ ├── modules/ # 业务接口模块
|
||
│ ├── index.js # API统一导出入口
|
||
│ └── request.js # 请求封装
|
||
├── common/ # 公共资源
|
||
│ ├── constants/ # 常量定义
|
||
│ ├── styles/ # 全局样式
|
||
│ │ ├── common.css # codefun原子类样式
|
||
│ │ ├── base.scss # 全局样式变量和工具类
|
||
│ │ └── dark-mode.scss # 暗黑模式样式
|
||
│ └── utils/ # 工具函数
|
||
│ ├── tool.js # 常用工具函数
|
||
│ └── env.js # 环境变量工具
|
||
├── components/ # 公共组件
|
||
│ └── common/ # 通用业务组件
|
||
├── directives/ # 自定义指令
|
||
├── hooks/ # Vue Composition API Hooks
|
||
│ ├── index.js # Hooks统一导出入口
|
||
│ ├── useRequest.js # 通用请求Hook
|
||
│ ├── useApi.js # API相关Hook
|
||
│ └── useState.js # 状态管理Hook
|
||
├── uni_modules/ # uni-app 组件
|
||
│ └── z-paging/ # 分页组件库
|
||
├── lib/ # 第三方库
|
||
│ └── luch-request/ # luch-request 网络请求库
|
||
├── uview-plus/ # uView-Plus 组件库
|
||
├── mixins/ # Vue 混入
|
||
│ └── global.js # 全局混入
|
||
├── pages/ # 主包页面
|
||
├── static/ # 静态资源文件
|
||
│ └── assets/ # 静态图片资源
|
||
├── store/ # 状态管理
|
||
├── subPages/ # 分包页面
|
||
├── App.vue # 应用入口
|
||
├── main.js # 主入口文件
|
||
├── pages.json # 页面配置
|
||
├── manifest.json # 应用配置
|
||
├── uni.scss # 全局样式变量
|
||
├── vite.config.js # Vite 编译配置
|
||
├── .nvmdrc # Node.js 版本要求
|
||
├── .env # 环境变量
|
||
├── .eslintrc.js # ESLint 配置
|
||
├── .prettierrc.js # Prettier 配置
|
||
├── .eslintignore # ESLint 忽略文件
|
||
└── .prettierignore # Prettier 忽略文件
|
||
```
|
||
|
||
# 开发环境与运行
|
||
|
||
## 环境要求
|
||
|
||
* Node.js (版本信息在 `.nvmdrc` 文件中指定，当前为 20.0.0)
|
||
* npm 或 yarn
|
||
|
||
## 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
## 运行项目
|
||
|
||
```bash
|
||
# 开发环境运行
|
||
npm run dev
|
||
|
||
# 构建生产环境
|
||
npm run build
|
||
|
||
# 预览构建结果
|
||
npm run preview
|
||
|
||
# 代码检查和修复
|
||
npm run lint
|
||
|
||
# 代码格式化
|
||
npm run format
|
||
```
|
||
|
||
## 构建项目
|
||
|
||
构建项目使用 Vite 工具链：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
# 代码规范与开发约定
|
||
|
||
## 样式
|
||
|
||
* 全局样式文件位于 `common/styles/` 目录下，包括 `common.css` 和 `base.scss`。
|
||
* `common.css` 提供了codefun原子类样式，用于快速布局。
|
||
* `base.scss` 提供了SCSS变量和mixins，以及常用的样式类生成器。
|
||
* 支持暗黑模式，通过 `dark-mode.scss` 实现。
|
||
* 样式规范应遵循项目中已有的风格。
|
||
|
||
## JavaScript
|
||
|
||
* 严格遵循ES6+规范。
|
||
* 遵循JavaScript函数式编程范式。
|
||
* 方法类函数应该使用 `function` 进行定义。
|
||
* 避免出现超过4个以上的 `ref`，超过4个则使用 `reactive`。
|
||
* 页面的生命周期需要通过 `@dcloudio/uni-app` 依赖进行按需导入，如(`import { onLoad } from '@dcloudio/uni-app'`)。
|
||
* 全局变量都集中放置于代码顶部。
|
||
* 变量名使用小驼峰命名法。
|
||
* 常量名使用全大写。
|
||
* 状态类变量命名参考 `isLogin`、`isOpen`。
|
||
* 事件类方法命名参考 `onClick`、`onSelect`。
|
||
* 变量都应该写有注释说明、类型说明。
|
||
* 所有 `Promise` 类方法使用 `async` `await` 写法，避免出现 `.then` 嵌套，并进行容错、错误抛出处理。
|
||
* 在需要页面跳转、提示、加载、本地存储、或其他功能的时候，优先使用工具函数 `common/utils/tool.js` 中存在的函数。
|
||
* 字符串拼接使用ES6的模板语法。
|
||
* 组件使用 Vue3 的 Composition API (setup语法糖) 编写。
|
||
|
||
## 静态资源
|
||
|
||
* 静态资源变量 `ASSETSURL` 已进行全局混入，可以在 `<template></template>` 中直接使用。
|
||
* 所有静态资源URL应该使用 `ASSETSURL` 进行拼接，使用方式为：`${ASSETSURL}simple.png`、`background-image: url($ASSETSURL + 'b23bbf0c4c8e59f88f8fd883cb5d6b27.png')`。
|
||
|
||
## 工具函数 (tool.js)
|
||
|
||
`common/utils/tool.js` 文件提供了一系列常用的工具函数：
|
||
|
||
* **提示与加载**: `alert`, `loading`, `hideLoading`
|
||
* **页面跳转**: `navigateTo`, `redirectTo`, `reLaunch`, `switchTab`, `navigateBack`
|
||
* **本地存储**: `storage`, `removeStorage`, `getStorageInfo`
|
||
* **其他功能**: `copy` (复制文本), `saveImageToPhotos` (保存图片), `requestPayment` (微信支付), `upload` (文件上传), `loadFont` (加载字体)
|
||
* **日期处理**: `formatDate` (日期格式化)
|
||
* **工具函数**: `deepClone` (深拷贝), `debounce/throttle` (防抖节流)
|
||
* **表单验证**: `getValidator` (表单验证工具)
|
||
* **主题切换**: `toggleDarkMode`, `getCurrentTheme` (暗黑模式切换)
|
||
* **权限管理**: `hasPermission`, `setPermissions`, `getUserPermissions` (权限检查和管理)
|
||
|
||
## 网络请求
|
||
|
||
* 网络请求使用 `lib/luch-request` 库进行封装。
|
||
* 全局配置在 `api/request.js` 中定义，包括基础URL、请求头、SSL验证等。
|
||
* 包含请求和响应拦截器，用于处理通用逻辑（如错误提示、鉴权等）。
|
||
* 支持请求缓存机制和重试机制。
|
||
* 各业务板块的接口都应存放在 `api/modules` 下，并将单个接口进行导出以便页面按需导入。
|
||
* 提供 `useGet` 和 `usePost` 等 Hooks 用于在组件中便捷地发起请求。
|
||
|
||
## 自定义Hooks
|
||
|
||
项目提供了多个可复用的 Vue Composition API Hooks，位于 `hooks/` 目录下：
|
||
|
||
* `useRequest`: 通用请求Hook，支持自动执行、手动执行、loading状态等
|
||
* `useGet`: GET请求Hook
|
||
* `usePost`: POST请求Hook
|
||
* `useState`: 状态管理Hook
|
||
* `useStorageState`: 本地存储状态Hook
|
||
* `useFormState`: 表单状态Hook
|
||
|
||
## 组件
|
||
|
||
* 项目集成了 `uView-Plus` 和 `z-paging` 两个组件库。
|
||
* 所有 `uni_modules` 目录中的组件无需导入直接可以进行使用。
|
||
* `uView-Plus` 组件已通过 `easycom` 自动导入，可以直接使用，如：`<u-button>`、`<u-icon>`。
|
||
* 自定义公共组件放在 `components/common/` 目录下，采用 Vue3 的 setup 语法糖编写。
|
||
* 页面独立组件放在页面根目录下的 `components/`。
|
||
* 微信的原生组件放在页面根目录下的 `wxcomponents/`，并在使用了组件的对应页面路由配置中添加组件的引用属性 `"usingComponents": { "components": "/wxcomponents/components/components" }`。
|
||
* 组件编写应遵循项目中已有的风格。
|
||
|
||
## 自定义指令
|
||
|
||
* 项目支持自定义指令，位于 `directives/` 目录下
|
||
* 包括防重复点击、长按、权限控制、拖拽等指令
|
||
* 在 `main.js` 中已全局注册
|
||
|
||
## 常量管理
|
||
|
||
* 项目常量统一管理在 `common/constants/` 目录下
|
||
* 包括应用信息、页面路径、存储键名、事件常量等
|
||
|
||
## 环境变量
|
||
|
||
* 环境变量通过 `.env` 文件配置
|
||
* 提供 `common/utils/env.js` 工具进行环境变量验证和获取
|
||
|
||
## 页面
|
||
|
||
* 页面配置在 `pages.json` 中管理。
|
||
* 主包页面放在 `pages/` 目录下，分包页面放在 `subPages/` 目录下，如果页面不属于一级页面且没有包含在 `pages.json` 中的 `tabbar`，则应该放置在分包目录下。
|
||
* 页面使用 Composition API (setup语法糖) 编写。
|
||
* 注释、结构规范应遵循项目中已有的风格。
|
||
|
||
## 代码提交规范
|
||
|
||
* 提交信息应清晰描述变更内容，如 `修复 搜索功能空值检查` 或 `新增 删除按钮功能`。
|
||
* 对于功能性的新增或修改，使用 `新增` 前缀。
|
||
* 对于错误修复，使用 `修复` 前缀。
|
||
* 对于性能优化、代码重构（既不修复错误也不添加功能），使用 `优化` 前缀。
|
||
* 对于文档更新，使用 `文档` 前缀。
|
||
* 提交信息应使用中文。
|
||
|
||
## 其他
|
||
|
||
* 页面中的分享功能应该使用原生的微信分享功能，通过 `button` 或 `<u-button>` 组件的 `open-type="share"` 属性实现。 |