You've already forked template-MP
307 lines
10 KiB
Markdown
307 lines
10 KiB
Markdown
# 项目概述 - IFLOW 上下文
|
||
|
||
这是一个基于 UniApp + Vue3 + uView-Plus 的微信小程序项目模板。它提供了一个基础的项目结构和一些常用的工具函数，方便快速开发微信小程序。
|
||
|
||
## 技术栈
|
||
|
||
* **UniApp**: 跨平台开发框架，用于构建微信小程序。
|
||
* **Vue3**: 渐进式 JavaScript 框架，用于构建用户界面。
|
||
* **uView-Plus**: 基于 UniApp 的 UI 组件库。
|
||
* **z-paging**: 一个用于处理分页加载的组件库。
|
||
* **Vuex**: 状态管理库，用于统一管理应用状态。
|
||
* **Vite**: 现代化构建工具，配置了自定义插件用于manifest.json的appid替换。
|
||
* **luch-request**: 网络请求库，提供请求封装和拦截器功能。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.
|
||
├── api/ # 接口相关
|
||
│ ├── modules/ # 业务接口（目录存在待完善）
|
||
│ └── request.js # 请求封装
|
||
├── common/ # 公共资源
|
||
│ ├── styles/ # 全局样式
|
||
│ │ ├── common.css # codefun原子类样式（预留）
|
||
│ │ └── base.scss # 全局样式变量（预留）
|
||
│ └── utils/ # 工具函数
|
||
│ └── tool.js # 常用工具函数
|
||
├── components/ # 公共组件（目录存在待完善）
|
||
├── wxcomponents/ # 微信原生组件
|
||
│ └── painter/ # 海报绘制组件
|
||
├── uni_modules/ # uni-app 组件
|
||
│ └── z-paging/ # 分页组件库
|
||
├── lib/ # 第三方库
|
||
│ └── luch-request/ # luch-request 网络请求库
|
||
├── uview-plus/ # uView-Plus 组件库
|
||
├── mixins/ # Vue 混入
|
||
│ └── global.js # 全局混入
|
||
├── pages/ # 主包页面
|
||
│ └── index/ # 首页
|
||
├── subPages/ # 分包页面
|
||
│ └── welcome/ # 欢迎页
|
||
├── static/ # 静态资源文件
|
||
│ └── assets/ # 静态图片资源
|
||
├── store/ # 状态管理
|
||
├── App.vue # 应用入口
|
||
├── main.js # 主入口文件
|
||
├── pages.json # 页面配置
|
||
├── manifest.json # 应用配置
|
||
├── uni.scss # 全局样式变量
|
||
├── vite.config.js # Vite 编译配置
|
||
├── .nvmdrc # Node.js 版本要求
|
||
├── .env # 环境变量
|
||
├── .iflow/ # iFlow CLI 配置
|
||
├── package.json # 项目依赖配置
|
||
└── uni.promisify.adaptor.js # uni-app promise 适配器
|
||
```
|
||
|
||
## 开发环境与运行
|
||
|
||
### 环境要求
|
||
|
||
* Node.js (版本信息在 `.nvmdrc` 文件中指定，当前为 24.0.1)
|
||
* npm 或 yarn
|
||
|
||
### 当前依赖
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"dotenv": "^17.2.2",
|
||
"dayjs": "*",
|
||
"vue": "^3.5.21"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 运行项目
|
||
|
||
由于这是一个 UniApp 项目，通常需要使用 HBuilderX 或其他支持 UniApp 的 IDE 来运行和调试：
|
||
|
||
1. 使用 HBuilderX 打开项目
|
||
2. 选择"运行到小程序模拟器"或"运行到手机或模拟器"
|
||
3. 选择微信开发者工具
|
||
|
||
### 构建项目
|
||
|
||
同样，构建项目也需要使用 HBuilderX 或相应的 CLI 工具。
|
||
|
||
## 代码规范与开发约定
|
||
|
||
## 样式规范
|
||
|
||
* `uni.scss` 提供了全局样式变量
|
||
* **全局样式**: 位于 `common/styles/` 目录
|
||
* `common.css`: CodeFun原子类样式，用于快速布局
|
||
* `base.scss`: SCSS变量、Mixins和常用样式类生成器
|
||
* **样式规范**: 遵循项目中已有的样式风格，统一使用原子类
|
||
|
||
## JavaScript规范
|
||
|
||
* **ES6+**: 严格遵循ES6+语法规范
|
||
* **函数式编程**: 优先使用函数式编程范式
|
||
* **函数定义**: 使用 `function` 关键字定义方法函数
|
||
* **响应式数据**:
|
||
* 少于4个 `ref` 时直接使用 `ref`
|
||
* 超过4个时使用 `reactive` 进行封装
|
||
* **生命周期**: 通过 `@dcloudio/uni-app` 按需导入，如：
|
||
```javascript
|
||
import { onLoad, onShow, onHide } from '@dcloudio/uni-app'
|
||
```
|
||
* **变量命名**:
|
||
* 小驼峰命名法: `userName`, `orderList`
|
||
* 常量全大写: `MAX_LENGTH`, `DEFAULT_VALUE`
|
||
* 状态类变量: `isLogin`, `isOpen`, `isLoading`
|
||
* 事件方法: `onClick`, `onSelect`, `onSubmit`
|
||
* **注释规范**: 变量和方法必须有注释说明和类型说明
|
||
* **异步处理**: 所有Promise类方法使用 `async/await` 写法，避免 `.then` 嵌套
|
||
* **字符串拼接**: 使用ES6模板语法 `` `string ${variable}` ``
|
||
|
||
## 静态资源
|
||
|
||
* **资源路径**: 使用全局混入的 `ASSETSURL` 变量
|
||
* **使用方式**:
|
||
```javascript
|
||
// 在template中
|
||
background-image: url($ASSETSURL + 'image.png')
|
||
|
||
// 在JavaScript中
|
||
const imageUrl = `${ASSETSURL}image.png`
|
||
```
|
||
|
||
## 工具函数 (tool.js)
|
||
|
||
`common/utils/tool.js` 提供完整的工具函数库：
|
||
|
||
### 提示与加载
|
||
* `alert()`: 文字轻提示
|
||
* `loading()`: 显示加载状态
|
||
* `hideLoading()`: 隐藏加载状态
|
||
|
||
### 页面跳转
|
||
* `navigateTo()`: 跳转到指定页面
|
||
* `redirectTo()`: 关闭当前页面并跳转
|
||
* `reLaunch()`: 关闭所有页面并跳转
|
||
* `switchTab()`: 跳转到TabBar页面
|
||
* `navigateBack()`: 返回上一页面
|
||
|
||
### 本地存储
|
||
* `storage()`: 设置或获取本地存储
|
||
* `removeStorage()`: 移除本地存储项
|
||
* `getStorageInfo()`: 获取存储信息
|
||
|
||
### 其他功能
|
||
* `copy()`: 复制文本到剪贴板
|
||
* `saveImageToPhotos()`: 保存图片到相册
|
||
* `requestPayment()`: 发起微信支付
|
||
* `upload()`: 文件上传
|
||
* `loadFont()`: 动态加载字体
|
||
|
||
### 网络请求
|
||
|
||
* 网络请求使用 `lib/luch-request` 库进行封装。
|
||
* 全局配置在 `api/request.js` 中定义，包括基础URL、请求头、SSL验证等。
|
||
* 包含请求和响应拦截器，用于处理通用逻辑（如错误提示、鉴权等）。
|
||
* 基础URL通过环境变量 `VITE_BASE_URL` 配置。
|
||
* 各业务板块的接口都应存放在 `api/modules` 下，并将单个接口进行导出以便页面按需导入。
|
||
|
||
### 状态管理 (Vuex)
|
||
|
||
* 项目集成了Vuex进行全局状态管理。
|
||
* 状态管理文件位于 `store/index.js`。
|
||
* 使用 `createStore` 创建store实例。
|
||
* 目前处于基础状态，包含空的state、mutations、actions和getters。
|
||
|
||
## 组件规范
|
||
|
||
* `uni_modules` 目录中的组件无需导入直接可以进行使用。
|
||
* **组件库**: 集成 `uView-Plus` 和 `z-paging`
|
||
* **自动导入**: `uView-Plus` 通过 `easycom` 自动导入
|
||
```javascript
|
||
// 直接使用，无需import
|
||
<u-button>按钮</u-button>
|
||
<u-icon name="home" />
|
||
```
|
||
* **组件分类**:
|
||
* **全局组件**: 放在 `components/` 目录
|
||
* **页面组件**: 放在页面根目录的 `components/` 目录
|
||
* **微信原生组件**: 放在页面根目录的 `wxcomponents/` 目录
|
||
|
||
## 分页功能
|
||
|
||
* **分页组件**: 使用 `z-paging` 实现高性能分页
|
||
* **使用方式**:
|
||
```vue
|
||
<template>
|
||
<z-paging
|
||
ref="paging"
|
||
v-model="dataList"
|
||
@query="queryList"
|
||
>
|
||
<view v-for="item in dataList" :key="item.id">
|
||
{{ item.name }}
|
||
</view>
|
||
</z-paging>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref } from 'vue'
|
||
|
||
const paging = ref(null)
|
||
const dataList = ref([])
|
||
|
||
// 分页查询函数
|
||
const queryList = async (pageNo, pageSize) => {
|
||
try {
|
||
const result = await api.getList({ pageNo, pageSize })
|
||
paging.value.complete(result.data.list)
|
||
} catch (error) {
|
||
paging.value.complete(false)
|
||
}
|
||
}
|
||
|
||
// 刷新数据
|
||
const refresh = () => {
|
||
paging.value.reload()
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 路由配置
|
||
* **主包页面**: 放在 `pages/` 目录
|
||
* **分包页面**: 放在 `subPages/` 目录
|
||
* **TabBar配置**: 在 `pages.json` 中配置底部导航
|
||
|
||
### Vite 配置
|
||
|
||
* `vite.config.js` 包含了自定义插件用于在编译时替换 `manifest.json` 中的 appid
|
||
* 仅在首次编译时执行，避免热重载时重复执行导致内存占用高
|
||
* 支持环境变量配置：
|
||
* `VITE_APPID` - 微信小程序APPID
|
||
* `VITE_UNI_APPID` - uni-app APPID
|
||
* `VITE_LIBVERSION` - 微信小程序基础库版本
|
||
|
||
### 环境配置
|
||
|
||
* 项目使用环境变量管理不同环境的配置，通过 `.env` 文件配置：
|
||
* `VITE_BASE_URL` - 接口地址
|
||
* `VITE_ASSETSURL` - 资源地址
|
||
* `VITE_APPID` - 小程序APPID
|
||
* `VITE_UNI_APPID` - UNI-APPID
|
||
* `VITE_LIBVERSION` - 微信小程序基础库版本
|
||
|
||
### 全局配置
|
||
|
||
* `main.js` 中配置了 `uni.$zp` 全局配置：
|
||
* `'empty-view-text'` - 空数据提示文字
|
||
* `'refresher-enabled'` - 是否启用下拉刷新
|
||
|
||
## 代码提交规范
|
||
|
||
### 提交信息格式
|
||
* **新增功能**: `新增 功能描述`
|
||
* **错误修复**: `修复 问题描述`
|
||
* **性能优化**: `优化 优化内容`
|
||
* **文档更新**: `文档 更新内容`
|
||
|
||
### 示例
|
||
```bash
|
||
git commit -m "新增 推广海报生成功能"
|
||
git commit -m "修复 购物车数量计算错误"
|
||
git commit -m "优化 接口请求性能"
|
||
```
|
||
|
||
### 其他
|
||
|
||
* 项目中的分享功能应该使用微信原生的分享功能，通过 `button` 或 `u-button` 组件的 `open-type="share"` 属性实现。
|
||
* 项目中的头像编辑和获取功能应该使用微信原生获取头像昵称的开放能力，通过 `button` 或 `u-button` 组件的 `open-type="chooseAvatar"` 属性和其触发的 `@chooseavatar` 事件实现。
|
||
* 项目中的昵称编辑和获取功能应该使用微信原生获取头像昵称的开放能力，通过 `input` 或 `u-input` 组件的 `open-type="nickname"` 属性实现。
|
||
* 项目集成了promise适配器 `uni.promisify.adaptor.js`，用于统一处理异步操作。
|
||
|
||
## 最佳实践
|
||
|
||
### 页面开发
|
||
* 使用Composition API (setup语法糖)
|
||
* 遵循Vue3响应式原理
|
||
* 合理使用computed和watch
|
||
|
||
### 组件开发
|
||
* 保持组件单一职责
|
||
* 使用props进行父子通信
|
||
* 合理使用emits进行事件派发
|
||
|
||
### 状态管理
|
||
* 合理划分store模块
|
||
* 避免过度依赖全局状态
|
||
* 及时清理不需要的状态
|
||
|
||
### 性能优化
|
||
* 使用z-paging进行列表优化
|
||
* 合理使用图片懒加载
|
||
* 避免不必要的重复渲染 |