微信小程序 + Taro + React Hooks 生命周期踩坑实录
使用 Taro + React Hooks 开发微信小程序时,最容易让人误判的一类问题,是页面已经重新显示,业务逻辑却没有重新执行。
例如,订单列表通过 navigateTo 打开详情页,修改订单后 navigateBack 返回列表,页面仍然显示旧数据;从首页切换到其他 Tab 再回来,原先启动的轮询没有按预期暂停;页面初次渲染时就查询节点尺寸,结果却为空。
这些问题不能简单归结为 useEffect 用错了。真正需要区分的是:React 组件的挂载与卸载,不等于微信小程序页面的显示与隐藏。 Taro 同时接入了这两套生命周期,页面导航、TabBar 复用和小程序渲染层又会影响实际执行时机。
本文以 Taro 4.x、React 函数组件为参考,只讨论小程序页面机制与 Taro Hooks 组合使用时需要特别处理的问题。示例是可复用的实现思路,不是未经提供的真实项目测试记录;接口地址均为占位地址,实际项目需要替换并配置合法请求域名。
页面生命周期与组件生命周期
微信小程序有页面栈。使用 navigateTo 打开新页面,会保留当前页面;使用 navigateBack 返回时,之前的页面重新显示,而不是重新加载。Taro 在 React 页面中提供了对应的 Hooks:
| Hook | 对应时机 | 更适合处理的事情 |
|---|---|---|
useLoad | 页面 onLoad | 首次加载时接收页面参数 |
useReady | 页面 onReady | 首次渲染完成后访问小程序渲染层节点 |
useDidShow | 页面 onShow | 每次页面显示时刷新或恢复业务任务 |
useDidHide | 页面 onHide | 页面隐藏时暂停仅对可见页面有用的任务 |
useUnload | 页面 onUnload | 页面卸载时执行页面级清理 |
useEffect | React 组件副作用 | 管理与组件挂载、依赖变化和卸载绑定的资源 |
例如,从列表页打开详情页,再返回列表页,常见流程是:
列表页:onLoad → onShow → onReady
navigateTo 详情页:列表页 onHide,详情页加载并显示
navigateBack:详情页 onUnload,列表页再次 onShow
这里是典型页面导航的示意,不能把它当作 React useEffect 和所有小程序生命周期之间的严格执行顺序。关键在于:列表页可以一直保留在页面栈中。
返回列表页,没有重新请求数据
订单列表初始化时,使用空依赖的 useEffect 请求数据:
useEffect(() => {
void loadOrders()
}, [])
这种写法适用于组件创建后的初始化,但从详情页返回时,列表页通常只是触发 onShow,并不会重新挂载。所以用户在详情页修改了订单,返回后看到的可能仍是原来的列表。
如果业务要求每次列表页重新显示时都刷新,应该使用 Taro 的 useDidShow:
文件位置: src/pages/orders/index.tsx
import { useState } from 'react'
import { View, Text } from '@tarojs/components'
import Taro, { useDidShow } from '@tarojs/taro'
type Order = {
id: string
name: string
}
export default function OrderList() {
const [orders, setOrders] = useState<Order[]>([])
useDidShow(() => {
const loadOrders = async () => {
try {
const res = await Taro.request<Order[]>({
url: 'https://api.example.com/orders'
})
setOrders(res.data)
} catch (error) {
console.error('加载订单失败', error)
}
}
void loadOrders()
})
return (
<View>
{orders.map((item) => (
<Text key={item.id}>{item.name}</Text>
))}
</View>
)
}
这样首次进入和从其他页面返回时,都会走页面显示逻辑。但 useDidShow 不仅在 navigateBack 时触发,Tab 切换、小程序回到前台也可能触发它。若接口有明显成本,可以让详情页在修改成功后设置数据失效标记,列表页显示时仅在标记存在的情况下刷新。
不要同时在 useEffect([]) 和 useDidShow 中无条件调用同一个接口,否则首次进入页面时很容易重复请求。问题在这里不是 React 的通用依赖管理,而是组件挂载与小程序页面显示两个时机重叠。
页面隐藏了,轮询却没有停止
微信小程序通过 navigateTo 跳转时,原页面一般还在页面栈里。即使页面看不见,原组件也不一定卸载。
如果只通过 useEffect 的返回函数清理轮询,清理通常要等组件卸载才发生;用户打开了另一个页面,并不一定能停止轮询。
对于“只在当前页面可见时轮询”的需求,应该按小程序的显示与隐藏时机管理任务:
文件位置: src/pages/monitor/index.tsx
import { useEffect, useRef } from 'react'
import { View } from '@tarojs/components'
import { useDidShow, useDidHide } from '@tarojs/taro'
export default function MonitorPage() {
const timerRef = useRef<ReturnType<typeof setInterval> | null>(null)
const stopPolling = () => {
if (timerRef.current !== null) {
clearInterval(timerRef.current)
timerRef.current = null
}
}
const startPolling = () => {
stopPolling()
timerRef.current = setInterval(() => {
console.log('执行页面可见期间的轮询')
}, 5000)
}
useDidShow(() => {
startPolling()
})
useDidHide(() => {
stopPolling()
})
useEffect(() => {
return () => stopPolling()
}, [])
return <View>监控页面</View>
}
useDidHide 负责页面隐藏,useEffect 的清理函数则处理组件真正卸载的情况。startPolling 先清理旧定时器,避免重复创建。
如果轮询中会发网络请求,停止定时器只会阻止后续轮询,不能自动取消已发出的请求;取消或丢弃旧请求结果需要由请求层另行处理。
TabBar 页面切回来,没有重新初始化
TabBar 页面和普通 navigateTo 页面不完全一样。switchTab 是切换到 TabBar 页面,TabBar 页面可能复用已有实例。不能简单地认为切换一次 Tab,就会重新触发页面 onLoad 或重新挂载 React 组件。
例如首页需要在用户切回 Tab 时刷新消息数量,仅把逻辑写在 useLoad 中并不符合需求:
useLoad(() => {
void refreshUnreadCount()
})
这里应该根据业务意图,决定是否在 useDidShow 重新读取:
import { useDidShow } from '@tarojs/taro'
export default function Home() {
useDidShow(() => {
void refreshUnreadCount()
})
return null
}
上面的 refreshUnreadCount 代表项目已有的请求函数,不是可直接运行的完整页面。它说明的是Tab 重新可见时的触发位置,实际请求、错误处理和状态更新应接入项目业务代码。
如果只有某次修改操作才需要刷新,不必每次切回 Tab 都发请求。可以通过共享状态记录“消息数据需要刷新”,再在 useDidShow 消费这个标记。
另一个需要区分的细节:navigateTo 不能直接跳转到 TabBar 页面;应使用 switchTab。将普通页面跳转和 Tab 切换混在一起排查,容易误判生命周期表现。
用 useReady 测量节点,但小程序渲染层还没有目标内容
微信小程序的渲染层与逻辑层并不是普通浏览器 DOM 的同一套访问模型。Taro 的 useReady 对应页面首次渲染完成,适合在这个时机开始使用 createSelectorQuery 等节点查询 API。
但 useReady 不会等待页面后续的接口请求。假如列表在接口返回后才渲染,只在 useReady 查询高度,测到的可能是初始空列表。
如果节点尺寸依赖动态数据,应等数据更新后,再在 Taro 视图更新时机查询:
文件位置: src/pages/catalog/index.tsx
import { useEffect, useState } from 'react'
import { View, Text } from '@tarojs/components'
import Taro from '@tarojs/taro'
export default function Catalog() {
const [items, setItems] = useState<string[]>([])
useEffect(() => {
// 示例数据;实际项目可在接口返回后更新 items
setItems(['商品 A', '商品 B', '商品 C'])
}, [])
useEffect(() => {
if (items.length === 0) return
Taro.nextTick(() => {
Taro.createSelectorQuery()
.select('#catalog-list')
.boundingClientRect((rect) => {
if (rect) {
console.log('列表高度:', rect.height)
}
})
.exec()
})
}, [items])
return (
<View id='catalog-list'>
{items.map((item) => (
<Text key={item}>{item}</Text>
))}
</View>
)
}
Taro.nextTick 帮助把查询放到相关视图更新之后,但它不保证网络图片、字体和动画均已完成。如果尺寸依赖图片加载,还要结合图片加载完成事件再次测量。
这个问题的重点不是 React 依赖数组,而是小程序渲染层节点查询的时机与动态内容更新并不一致。
页面反复显示,Taro 事件监听被重复注册
跨页面刷新可以使用 Taro 的事件系统。如果在 useDidShow 中每次都注册事件,但没有在页面隐藏时移除,返回页面后监听器可能越来越多:
useDidShow(() => {
Taro.eventCenter.on('refreshOrder', () => {
console.log('刷新订单')
})
})
在小程序中,页面隐藏并不代表组件销毁,也不代表事件中心自动清理这个监听。
如果监听只在页面可见期间有意义,可以成对注册和移除:
import { useCallback } from 'react'
import Taro, {
useDidShow,
useDidHide,
useUnload
} from '@tarojs/taro'
export default function OrderPage() {
const handleRefresh = useCallback(() => {
console.log('收到订单刷新通知')
}, [])
const removeListener = () => {
Taro.eventCenter.off('refreshOrder', handleRefresh)
}
useDidShow(() => {
removeListener()
Taro.eventCenter.on('refreshOrder', handleRefresh)
})
useDidHide(() => {
removeListener()
})
useUnload(() => {
removeListener()
})
return null
}
这里的 useUnload 是页面卸载时的兜底清理。移除监听时传入同一个 handleRefresh,避免误删其他页面对同名事件的监听。
如果业务要求页面隐藏时仍能接收消息,就不要在 useDidHide 移除,而应将监听生命周期放在真正需要接收消息的模块中。
下拉刷新触发了,刷新动画却一直不结束
微信小程序的下拉刷新是页面级能力,不是普通 React 组件的 Effect。Taro 提供 usePullDownRefresh 与之对应,但使用前需要在页面配置中启用下拉刷新。
页面配置文件: src/pages/orders/index.config.ts
export default definePageConfig({
enablePullDownRefresh: true
})
以上写法要求项目能使用 Taro 的 definePageConfig 宏,沿用现有 Taro 模板即可。保存后需要重新编译,确保页面配置已经更新。
页面代码:
import Taro, { usePullDownRefresh } from '@tarojs/taro'
export default function OrderList() {
usePullDownRefresh(() => {
const refresh = async () => {
try {
await Taro.request({
url: 'https://api.example.com/orders'
})
// 实际业务中还应更新对应页面的数据状态
} catch (error) {
console.error('下拉刷新失败', error)
} finally {
Taro.stopPullDownRefresh()
}
}
void refresh()
})
return null
}
这里把 stopPullDownRefresh() 放进 finally,确保请求成功或失败后都尝试结束下拉刷新动画。如果接口数据需要显示在页面上,还需要在请求完成后更新 React 状态;示例只展示小程序刷新流程的关键部分。