夜雨聆风书接上篇，今天我们来聊一个很多Vue3开发者转向UniApp时都会感到困惑的话题：如何正确地使用Vue3 Composition API和TypeScript开发UniApp应用。附带实现思路和所有源码示例，以及常见避坑指南和开发实践。
此系列文章将带领你从移动端跨平台开发入门到精通，如果你也喜欢关注APP、小程序、公众号、H5等等应用的开发，可以持续关注后续更新，避免错过宝贵的知识分享。
你可能觉得：“Vue3我都会，UniApp不就是多平台吗？能有什么不同？”等你真正上手，就会发现：
生命周期多了
onLoad、onShow、onReady，它们和onMounted啥关系？页面传参怎么和Vue Router不一样？
localStorage和uni.setStorageSync有啥区别？Pinia还能用吗？怎么用？
别急，今天我就用一张表、一堆代码，把这些差异和坑点全部理清楚，让你写起UniApp来像写普通Vue3一样顺手。
一、开发环境搭建与基础配置
1.1 创建支持TypeScript的UniApp项目
npx degit dcloudio/uni-preset-vue#vite-ts my-ts-app
cd my-ts-app
npm install
或者在HBuilderX中新建项目时，选择“uni-app (Vue3)”，并勾选“启用TypeScript”。
1.2 tsconfig.json关键配置
{
"compilerOptions": {
"types": ["@dcloudio/types", "miniprogram-api-typings"],
"strict": true,
"moduleResolution": "node",
"resolveJsonModule": true
},
"include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"]
}
1.3 类型声明增强（shims-uni.d.ts）
declaremodule'*.vue' {
importtype { DefineComponent } from'vue'
constcomponent: DefineComponent<{}, {}, any>
exportdefaultcomponent
}
二、生命周期：Vue3 vs UniApp，一张表看懂
| 场景 | Vue3 组件生命周期 | UniApp 页面生命周期 | 说明 |
|---|---|---|---|
| 组件/页面创建 | setup() | setup() | 同时执行，此时没有DOM |
| DOM挂载 | onMounted | onReady | UniApp页面DOM完全渲染后触发 |
| 页面显示 | 无 | onShow | 每次进入页面都触发（包括返回） |
| 页面隐藏 | 无 | onHide | 页面切到后台或跳转其他页 |
| 页面卸载 | onUnmounted | onUnload | 页面被销毁 |
| 页面初次加载 | 无 | onLoad | 接收路由参数，只执行一次 |
重点：
onLoad：接收页面参数，类似Vue Router的beforeRouteEnter。onShow：类似Vue Router的onBeforeRouteUpdate，但更强大。onReady：等同于Vue3的onMounted，但onMounted在UniApp中也会执行（组件级），推荐页面逻辑放onReady或onMounted均可，但获取元素位置用onReady更稳妥。
代码示例：组合使用
<scriptsetuplang="ts">
import { onMounted, ref } from'vue'
import { onLoad, onShow, onReady, onHide, onUnload } from'@dcloudio/uni-app'
constmessage=ref('')
constid=ref('')
onLoad((options: any) => {
// 接收URL参数，只执行一次
id.value=options.id
console.log('页面加载，参数id:', id.value)
})
onShow(() => {
console.log('页面显示，每次进入都触发')
})
onReady(() => {
console.log('页面DOM渲染完成')
// 可以在这里获取元素位置
constquery=uni.createSelectorQuery().in(getCurrentInstance()!.proxy)
query.select('.box').boundingClientRect(rect=> {
console.log(rect)
}).exec()
})
onHide(() => {
console.log('页面隐藏')
})
onUnload(() => {
console.log('页面卸载，清理资源')
})
onMounted(() => {
console.log('组件挂载（Vue3生命周期）')
})
</script>
坑点：
不要在
onLoad中尝试获取DOM，此时尚未渲染。页面卸载时务必清理定时器、事件监听，否则内存泄漏。
三、页面传参与路由
3.1 URL传参（最常用）
发送页：
// 注意特殊字符要编码
constname=encodeURIComponent('张三&李四')
uni.navigateTo({
url: `/pages/detail/detail?id=123&name=${name}`
})
接收页：
import { onLoad } from'@dcloudio/uni-app'
onLoad((options: { id: string; name: string }) => {
console.log(options.id) // '123'
console.log(options.name) // '张三&李四'（已自动解码）
// 数字需要转换
constidNum=parseInt(options.id)
})
注意事项：
参数值会被自动
decodeURIComponent，无需手动解码。参数都是字符串，对象需要
JSON.stringify再编码。URL长度限制：小程序约2KB，H5和App更大。
3.2 事件总线传参（跨页面）
// 发送页
uni.$emit('updateCart', { count: 5 })
uni.navigateBack()
// 接收页（在onLoad中监听）
import { onLoad, onUnload } from'@dcloudio/uni-app'
consthandleUpdate= (data: { count: number }) => {
console.log('购物车更新', data)
}
onLoad(() => {
uni.$on('updateCart', handleUpdate)
})
onUnload(() => {
uni.$off('updateCart', handleUpdate) // 必须移除
})
3.3 与Vue Router的差异
无
$router：所有跳转使用uni.navigateTo等API。无
$route：参数通过onLoad的options获取。无嵌套路由：页面扁平化，通过
pages.json配置。
四、API Client：uni.request vs axios
在UniApp中，网络请求不能使用axios（因为依赖XMLHttpRequest），必须用uni.request或封装。
4.1 基础使用
// 原生用法
uni.request({
url: 'https://api.example.com/user',
method: 'GET',
data: { id: 1 },
success: (res) => {
console.log(res.data)
},
fail: (err) => {
console.error(err)
}
})
4.2 封装为Promise + TypeScript
// utils/request.ts
interfaceRequestOptions {
url: string
method?: 'GET'|'POST'|'PUT'|'DELETE'
data?: any
header?: any
showLoading?: boolean
}
functionrequest<T=any>(options: RequestOptions): Promise<T> {
returnnewPromise((resolve, reject) => {
if (options.showLoading) {
uni.showLoading({ title: '加载中...' })
}
uni.request({
url: options.url,
method: options.method||'GET',
data: options.data,
header: options.header,
success: (res) => {
if (res.statusCode===200) {
resolve(res.dataasT)
} else {
reject(res)
}
},
fail: reject,
complete: () => {
if (options.showLoading) {
uni.hideLoading()
}
}
})
})
}
exportdefaultrequest
4.3 类型安全的API调用
// api/user.ts
importrequestfrom'@/utils/request'
interfaceUser {
id: number
name: string
email: string
}
exportconstgetUserInfo= (id: number) => {
returnrequest<User>({
url: `/user/${id}`,
method: 'GET'
})
}
// 页面中使用
constuser=awaitgetUserInfo(123)
console.log(user.name) // TS自动推断类型
五、本地存储：uni.setStorageSync vs localStorage
| 功能 | Web (localStorage) | UniApp | 差异说明 |
|---|---|---|---|
| 同步写入 | localStorage.setItem | uni.setStorageSync | 前者只接受字符串，后者自动转换 |
| 同步读取 | localStorage.getItem | uni.getStorageSync | 后者返回已解析的对象 |
| 异步写入 | 无 | uni.setStorage | 回调方式 |
| 容量限制 | 5-10MB | 小程序10MB，App无限制 | 小程序注意不要超 |
使用示例：
// 存储对象（自动序列化）
uni.setStorageSync('user', { name: '张三', age: 18 })
// 读取对象（自动反序列化）
constuser=uni.getStorageSync('user') as { name: string; age: number } |null
// 移除
uni.removeStorageSync('user')
// 清空
uni.clearStorageSync()
注意：
小程序中单个key不能超过1MB，总容量10MB。
不要频繁同步存储大量数据，可能阻塞UI。
六、状态管理：Pinia依然是最佳选择
Pinia完美支持UniApp，且比Vuex更轻量。
6.1 安装与配置
npm install pinia// main.ts
import { createSSRApp } from'vue'
importAppfrom'./App.vue'
import { createPinia } from'pinia'
exportfunctioncreateApp() {
constapp=createSSRApp(App)
constpinia=createPinia()
app.use(pinia)
return { app }
}
6.2 定义store（stores/user.ts）
import { defineStore } from'pinia'
exportconstuseUserStore=defineStore('user', {
state: () => ({
token: ''asstring,
userInfo: nullas { name: string; avatar: string } |null
}),
getters: {
isLogin: (state) =>!!state.token
},
actions: {
login(token: string, userInfo: any) {
this.token=token
this.userInfo=userInfo
// 持久化到storage
uni.setStorageSync('userStore', { token, userInfo })
},
logout() {
this.token=''
this.userInfo=null
uni.removeStorageSync('userStore')
},
// 初始化从storage读取
init() {
constdata=uni.getStorageSync('userStore')
if (data) {
this.token=data.token
this.userInfo=data.userInfo
}
}
}
})
6.3 在页面中使用
<template>
<view>
<textv-if="userStore.isLogin">欢迎 {{ userStore.userInfo?.name }}</text>
<buttonv-else@click="handleLogin">登录</button>
</view>
</template>
<scriptsetuplang="ts">
import { useUserStore } from'@/stores/user'
constuserStore=useUserStore()
consthandleLogin= () => {
userStore.login('fake-token', { name: '张三', avatar: '' })
}
</script>
6.4 与Vue3的区别
Pinia用法完全相同，只是持久化需要自己配合
uni.setStorageSync。注意：Pinia默认存储在内存中，刷新页面会丢失，必须持久化。
七、常见错误与解决方案
❌ 错误1：在onLoad中获取DOM位置为0
原因：DOM未渲染完成。解决：移到onReady或nextTick中。
❌ 错误2：TypeScript报错“找不到模块'@dcloudio/uni-app'”
原因：类型定义未安装。解决：npm install -D @dcloudio/types，并在tsconfig.json中配置types。
❌ 错误3：Pinia数据在页面跳转后不更新
原因：页面没有重新读取store（但store是响应式的，按理应该自动更新）。可能是你在onLoad中一次性读取了store的值到本地data，导致后续store变化未同步。解决：直接使用store的响应式数据，不要复制到本地data。
❌ 错误4：uni.setStorageSync存储对象后，读取时类型丢失
原因：返回的是any类型。解决：使用类型断言或定义类型守卫。
interfaceUser { name: string }
constuser=uni.getStorageSync('user') asUser|null
❌ 错误5：事件总线监听多次触发
原因：未在onUnload中取消监听，导致页面多次进入时重复绑定。解决：成对使用uni.$on和uni.$off，并确保移除的是同一个函数引用。
❌ 错误6：URL传参时，对象参数丢失
原因：未使用JSON.stringify。解决：
constobj= { id: 1, name: '张三' }
conststr=encodeURIComponent(JSON.stringify(obj))
uni.navigateTo({ url: `/pages/detail/detail?data=${str}` })
// 接收时
onLoad((options) => {
constobj=JSON.parse(decodeURIComponent(options.data))
})
八、完整示例：一个带用户登录和商品列表的小程序
项目结构
src/
├── api/
│ └── goods.ts # 商品API
├── components/
│ └── GoodCard.vue # 商品卡片组件
├── pages/
│ ├── index/
│ │ └── index.vue # 首页（商品列表）
│ ├── login/
│ │ └── login.vue # 登录页
│ └── detail/
│ └── detail.vue # 商品详情
├── stores/
│ └── user.ts # 用户store
├── utils/
│ └── request.ts # 请求封装
├── App.vue
├── main.ts
├── pages.json
└── manifest.json
8.1 请求封装（utils/request.ts）
interfaceRequestConfig {
url: string
method?: 'GET'|'POST'|'PUT'|'DELETE'
data?: any
header?: any
showLoading?: boolean
}
exportfunctionrequest<T=any>(config: RequestConfig): Promise<T> {
returnnewPromise((resolve, reject) => {
if (config.showLoading) uni.showLoading({ title: '加载中...', mask: true })
uni.request({
url: `https://your-api.com${config.url}`,
method: config.method||'GET',
data: config.data,
header: {
'Content-Type': 'application/json',
...config.header
},
success: (res) => {
if (res.statusCode===200) {
resolve(res.dataasT)
} else {
reject(res)
}
},
fail: reject,
complete: () => {
if (config.showLoading) uni.hideLoading()
}
})
})
}
8.2 商品API（api/goods.ts）
import { request } from'@/utils/request'
exportinterfaceGoods {
id: number
name: string
price: number
image: string
}
exportconstgetGoodsList= (page: number, pageSize: number=10) => {
returnrequest<{ list: Goods[]; total: number }>({
url: '/goods/list',
method: 'GET',
data: { page, pageSize },
showLoading: true
})
}
8.3 首页（pages/index/index.vue）
<template>
<viewclass="container">
<viewclass="goods-list">
<GoodCard
v-for="item in goodsList"
:key="item.id"
:goods="item"
@click="toDetail(item.id)"
/>
</view>
<button@click="loadMore":disabled="loading">加载更多</button>
</view>
</template>
<scriptsetuplang="ts">
import { ref, onMounted } from'vue'
import { getGoodsList, typeGoods } from'@/api/goods'
importGoodCardfrom'@/components/GoodCard.vue'
constgoodsList=ref<Goods[]>([])
constpage=ref(1)
constloading=ref(false)
consthasMore=ref(true)
constloadGoods=async () => {
if (loading.value||!hasMore.value) return
loading.value=true
try {
constres=awaitgetGoodsList(page.value)
if (res.list.length) {
goodsList.value.push(...res.list)
page.value++
} else {
hasMore.value=false
}
} catch (err) {
console.error(err)
} finally {
loading.value=false
}
}
constloadMore= () =>loadGoods()
consttoDetail= (id: number) => {
uni.navigateTo({ url: `/pages/detail/detail?id=${id}` })
}
onMounted(() => {
loadGoods()
})
</script>
8.4 商品卡片组件（components/GoodCard.vue）
<template>
<viewclass="card"@click="handleClick">
<image:src="goods.image"mode="aspectFill"class="img"/>
<viewclass="info">
<textclass="name">{{ goods.name }}</text>
<textclass="price">¥{{ goods.price }}</text>
</view>
</view>
</template>
<scriptsetuplang="ts">
importtype { Goods } from'@/api/goods'
constprops=defineProps<{
goods: Goods
}>()
constemit=defineEmits<{
(e: 'click'): void
}>()
consthandleClick= () => {
emit('click')
}
</script>
8.5 用户Store（stores/user.ts）
import { defineStore } from'pinia'
exportconstuseUserStore=defineStore('user', {
state: () => ({
token: ''asstring,
nickname: ''asstring
}),
getters: {
isLogin: (state) =>!!state.token
},
actions: {
login(token: string, nickname: string) {
this.token=token
this.nickname=nickname
uni.setStorageSync('user', { token, nickname })
},
logout() {
this.token=''
this.nickname=''
uni.removeStorageSync('user')
},
init() {
constdata=uni.getStorageSync('user') as { token: string; nickname: string } |null
if (data) {
this.token=data.token
this.nickname=data.nickname
}
}
}
})
8.6 App.vue初始化
<scriptsetuplang="ts">
import { onLaunch } from'@dcloudio/uni-app'
import { useUserStore } from'@/stores/user'
onLaunch(() => {
constuserStore=useUserStore()
userStore.init()
})
</script>
8.7 pages.json配置
{
"pages": [
{"path": "pages/index/index", "style": {"navigationBarTitleText": "商城"}},
{"path": "pages/login/login", "style": {"navigationBarTitleText": "登录"}},
{"path": "pages/detail/detail", "style": {"navigationBarTitleText": "商品详情"}}
],
"globalStyle": {
"navigationBarTextStyle": "black",
"navigationBarTitleText": "我的应用",
"navigationBarBackgroundColor": "#FFFFFF"
}
}
九、总结
今天我们系统地学习了在UniApp中使用Vue3 Composition API和TypeScript的注意事项，包括：
生命周期：区分Vue3组件和UniApp页面的不同钩子。
页面传参：URL传参、事件总线、与Vue Router的差异。
API Client：封装
uni.request并提供类型安全。本地存储：
uni.setStorageSync的用法和限制。状态管理：Pinia的集成与持久化。
常见错误：典型场景的解决方案。
最后送你一句话：跨平台开发不是复制粘贴，而是理解差异，写出优雅兼容的代码。希望你能用好TypeScript这把利剑，让UniApp项目更加健壮。
如果在实际开发中遇到问题，欢迎带着你的代码来找我。
加油，未来的全栈大佬！💪如果你也对移动端跨端开发感兴趣，关注我，后续还有更多优质文章分享！
往期相关文章推荐
