template-MP/IFLOW.md

项目概述 - 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

安装依赖

npm install

运行项目

# 开发环境运行
npm run dev

# 构建生产环境
npm run build

# 预览构建结果
npm run preview

# 代码检查和修复
npm run lint

# 代码格式化
npm run format

构建项目

构建项目使用 Vite 工具链：

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" 属性实现。