# uniapp-frame

**Repository Path**: wanchuang_software/uniapp-frame

## Basic Information

- **Project Name**: uniapp-frame
- **Description**: 基于vue3+ts+uview-pro+webscoket搭建的uniapp开发框架
- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 3
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于vue3+ts+uview-pro+webscoket搭建的uniapp开发框架（更新完善中...）

## 安装依赖
```javascript
npm install
node 版本号 22.20.00
```
## 相关文档
api文档：[uniapp](https://uniapp.dcloud.net.cn/)、[uview-pro](https://uviewpro.cn/zh/guide/intro.html)、[z-paging](https://z-paging.zxlee.cn/)、[day.js](https://dayjs.fenxianglu.cn/)、[uni-app 路由管理](https://mengxi-studio.github.io/uni-router/)、[Pinia 持久化插件](https://socket.dev/npm/package/@rdeam/pinia-plugin-uni-persist-next)
## 目录结构
```javascript
|-api //接口相关文件
|-components //自定义组件
|-config //配置文件
|-hooks //组合函数文件
|-node_modules //依赖
|-pages //业务页面
|-server //封装的http请求
|-static //静态资源
|-store //全局内存
|-unpackage //运行包忽略
|-.gitignore //git配置文件
|-App.vue //应用根组件
|-index.html //网页入口模板-不需要任何操作
|-main.js //入口文件
|-manifest.json //应用配置文件
|-package.json //项目依赖清单
|-package-lock.json //依赖版本锁文件
|-pages.json //页面路由配置
|-tsconfig.json //TypeScript 配置
|-uni.promisify.adaptor.js //uni-app 适配器(vue3适配uniapp)
|-uni.scss //全局样式变量
|-README.md
```
## 代码使用
- request请求方式，在api目录下创建 ***.ts文件，并引入http方法，可用的http请求方法有 post、get、delete、put
```javascript
import { http } from 'uview-pro';
export const 接口名称= (data: any) => http.get('接口地址', data)
export const 接口名称= (data: any) => http.post('接口地址', data)
export const 接口名称= (data: any) => http.delete('接口地址', data)
export const 接口名称= (data: any) => http.put('接口地址', data)
```
- request请求中去除默认的loading和toast
```javascript
import { http } from 'uview-pro';
export const 接口名称= (data: any) => http.get('接口地址', data, {meta: { toast: false, loading: false }})
```
- webscoke使用
```javascript
import { watch } from 'vue';
import { useWebSocket } from '@/hooks/useWebSocket'
const userStore = useUserStore()
const { reconnect, initWS, isConnected, send, onMessage, close, lastMessage } = useWebSocket()
initWS() //初始化webscoket并开启
close() //关闭webscoket
lastMessage //心跳数据
watch(lastMessage, (newVal) => {
	 if (newVal) {
	   console.log('消息更新了:', newVal)
	   // 追加到列表中
	   // messages.value.push(newVal)
	 }
})
```
- 使用Pinia + 持久化@rdeam/pinia-plugin-uni-persist-next插件，实现自动store持久化存储
```javascript
import { useUserStore } from '@/store';
import { storeToRefs } from 'pinia'
const userStore = useUserStore()
// 使用 storeToRefs 保持响应式
const { token, isLoggedIn } = storeToRefs(userStore)
userStore.setToken('your_jwt_token_here')
```
 核心配置选项详解
| 选项 | 类型 | 默认值 | 说明 |
| --------  | --------  | --------| --------       |
| enabled   | boolean   | false   | 是否开启持久化   |
| async     | boolean| true | 是否使用异步写入（默认异步，性能更好）   |
| strategies| PersistStrategy[]| [{ key: store.$id }]| 存储策略数组   |
| beforeRestore| (ctx) => void| undefined | 恢复数据前的钩子函数   |
| afterRestore| (ctx) => void| undefined | 恢复数据后的钩子函数   |

 strategies 中每个策略的配置
| 选项 | 类型 |  说明 |
| --------  |  --------| --------       |
| key| string   | 本地存储的 key 名称   |
| paths| string[]| 需要持久化的顶层字段列表   
| async| boolean   | 覆盖全局的 async 设置 |

- z-paging分页组件基本使用(vue3) 更多可查看官网[z-paging](https://z-paging.zxlee.cn/)
```html
<template>
    <z-paging ref="paging" v-model="dataList" @query="queryList">
		<view class="item" v-for="(item,index) in dataList">
			<view class="item-title">{{item.title}}</view>
		</view>
	</z-paging>
</template>
```
```javascript
    import { ref } from 'vue';
    const paging = ref(null)
    const dataList = ref([])
    
    const queryList = (pageNo, pageSize) => {
        // 这里的pageNo和pageSize会自动计算好，直接传给服务器即可
        // 这里的请求只是演示，请替换成自己的项目的网络请求，并在网络请求回调中通过paging.value.complete(请求回来的数组)将请求结果传给z-paging
        request.queryList({ pageNo,pageSize }).then(res => {
        	// 请勿在网络请求回调中给dataList赋值！！只需要调用complete就可以了
            paging.value.complete(res.data.list);
        }).catch(res => {
        	// 如果请求失败写paging.value.complete(false)，会自动展示错误页面
        	// 注意，每次都需要在catch中写这句话很麻烦，z-paging提供了方案可以全局统一处理
        	// 在底层的网络请求抛出异常时，写uni.$emit('z-paging-error-emit');即可
        	paging.value.complete(false);
        })
    }
```
- day.js日期格式格式化 简单用法  更多可查看官网[day.js](https://dayjs.fenxianglu.cn/)
```javascript
dayjs().format();                                     // 2020-09-08T13:42:32+08:00
dayjs().format('YYYY-MM-DD');                         // 2020-09-08
dayjs().format('YYYY-MM-DD HH:mm:ss');                // 2020-09-08 13:47:12
dayjs(1318781876406).format('YYYY-MM-DD HH:mm:ss');   // 2011-10-17 00:17:56
```
- uni-app 路由管理基本使用 [uni-app 路由管理](https://mengxi-studio.github.io/uni-router/)
```json
// 如何添加路由，按照uniapp正常添加页面，只需要按照创建路由器功能增加需要用的属性
// 因为引入了@meng-xi/vite-plugin组件会自动生成 router.config.ts路由配置文件（不推荐修改）如需修改可直接在pages.json文件修改对应路由
"pages": [
	{
		"path": "pages/index/index",
		"name": "home", //路由名称
		"meta": { "isTab": true, "title": '首页', "requireAuth": true }
		"style": {
			"navigationBarTitleText": "uni-app"
		}
	},
]
```
```html
 <!-- 页面中使用 -->
<template>
	<button @click="goToRouter">跳转路由页</button>
</template>
```
```javascript
	import { useRouter } from '@meng-xi/uni-router'
	const router = useRouter()
	function goToRouter() {
		 router.push({ name: 'pagesRouterRouter' })
	}
// 注：在pages.json增加路由后需要重新运行项目才会自动生成路由配置文件
```
也可以直接用RouterLink组件
```html
<!-- 路径字符串 -->
<RouterLink to="pages/about/about">关于</RouterLink>

<!-- 路径对象（需用 :to 绑定） -->
<RouterLink :to="{ path: 'pages/about/about', query: { id: '1' } }">详情</RouterLink>

<!-- 命名路由（推荐） -->
<RouterLink :to="{ name: 'about', query: { id: '1' } }">详情</RouterLink>
```
 - 增加正则表达式库
```javascript
import { isMobile, isEmail, maskPhone } from '@/utils/regex'
// 表单校验示例
const phone = ref('13812345678')
const isValid = isMobile(phone.value)   // true
// 脱敏显示
const masked = maskPhone(phone.value)   // 138\*\*\*\*5678
```
- 微信小程序检测更新
```javascript
// 在app.vue中使用
	import { onLaunch, onShow, onHide, onThemeChange } from '@dcloudio/uni-app';
	import { useWebSocket } from '@/hooks/useWebSocket'
	import { checkUpdate, silentUpdate } from '@/utils/updateManager/update-mp-weixin'

	const { initWS } = useWebSocket()
	onLaunch(() => {
		console.log('App Launch');
		// 标准提示更新（非强制）
		checkUpdate()
		
		// 如果需要强制更新，可以传参：
		// checkUpdate({ force: true, title: '强制更新', content: '修复重要问题' })
		
		// 带回调监听更新状态（例如埋点）
		// checkUpdate({}, (status) => {
		//   if (status.type === 'check' && status.hasUpdate) {
		//     // 上报：有新版本
		//   } else if (status.type === 'ready') {
		//     // 上报：下载完成
		//   }
		// })
	});
	onShow(() => {
		console.log('App Show');
		// 从后台切回前台时再次检查（覆盖热启动场景）
		checkUpdate()
		
		// 如果希望某些版本使用静默更新，可以调用：
		// silentUpdate()
	});
	onHide(() => {
		console.log('App Hide');
	});
	onThemeChange(res => {
		console.log('[App.vue] system theme changed', res);
	});
```
## 组件使用
- 如何在项目中使用components中的组件，在components组件命名方式com-xxx，组件目录是com-xxx/com-xxx，不一定是com开头随意，在uniapp中asycom是默认开启的在引用组件时可简化引入流程
```html
<template>
	<com-xxx></com-xxx>
</template>
```
- com-list组件如何使用
```html
<!--  父组件中使用 -->
<template>
	<com-list :method="anyapi"></com-list>
</template>
```
```javascript
import { anyapi } from '@/api/anyapi'
	// 子组件中所需参数
 // showAvatar 骨架屏是否展示头像
 // showTitle 骨架屏是否显示大标题
 // refresherEnabled 是否开启下拉刷新
 // method 请求数据所用的方法
 // text 缺省页显示的文本

```