微信小程序 + Taro + React Hooks 生命周期踩坑实录

9 阅读8分钟

微信小程序 + 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页面卸载时执行页面级清理
useEffectReact 组件副作用管理与组件挂载、依赖变化和卸载绑定的资源

例如,从列表页打开详情页,再返回列表页,常见流程是:

列表页: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 状态;示例只展示小程序刷新流程的关键部分。

参考文档