# uniapp-frame

**Repository Path**: tom/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**: 0
- **Forks**: 4
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-13

## 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 设置   
## 组件使用
- 如何在项目中使用components中的组件，在components组件命名方式com-xxx，组件目录是com-xxx/com-xxx，不一定是com开头随意，在uniapp中asycom是默认开启的在引用组件时可简化引入流程
```javascript
<template>
	<com-xxx></com-xxx>
</template>
```
- com-list组件如何使用
```javascript
// 父组件中使用
<template>
	<com-list :method="anyapi"></com-list>
</template>
<script>
import { anyapi } from '@/api/anyapi'
</script>
// 子组件中所需参数
 // showAvatar 骨架屏是否展示头像
 // showTitle 骨架屏是否显示大标题
 // refresherEnabled 是否开启下拉刷新
 // method 请求数据所用的方法
 // text 缺省页显示的文本

```
- z-paging分页组件基本使用(vue3) 更多可查看官网[z-paging](https://z-paging.zxlee.cn/)
```javascript
<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>

<script setup>
    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);
        })
    }
</script>
```
- 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/)
```javascript
// 如何添加路由，按照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"
		}
	},
]
// 页面中使用
<template>
	<button @click="goToRouter">跳转路由页</button>
</template>
<script setup lang="ts">
	import { useRouter } from '@meng-xi/uni-router'
	const router = useRouter()
	function goToRouter() {
		 router.push({ name: 'pagesRouterRouter' })
	}
</script>
// 注：在pages.json增加路由后需要重新运行项目才会自动生成路由配置文件
```