生命周期钩子

生命周期钩子只能在组件函数体的同步执行阶段注册。

onInit()

组件实例创建后立即调用，此时响应式数据已初始化，但尚未挂载到 DOM。

类型定义

declare function onInit(callback: () => Promise<void> | void): void

详情

onInit 支持返回 Promise，当返回 Promise 时，外层的 Suspense 会等待其完成后再显示组件内容。

示例

tsx

import { ref, onInit } from 'vitarx'

function MyComponent() {
  const data = ref<string | null>(null)

  onInit(() => {
    data.value = '初始化完成'
  })

  return <div>{data}</div>
}

onBeforeMount()

组件即将挂载到 DOM 之前调用。

类型定义

declare function onBeforeMount(callback: () => void): void

示例

tsx

import { onBeforeMount } from 'vitarx'

function MyComponent() {
  onBeforeMount(() => {
    console.log('组件即将挂载')
  })
  return <div>Hello</div>
}

onMounted()

组件挂载到 DOM 之后调用，此时可以安全地访问 DOM 元素。

类型定义

declare function onMounted(callback: () => void): void

示例

tsx

import { useRef, onMounted } from 'vitarx'

function MyComponent() {
  const elRef = useRef<HTMLDivElement>()

  onMounted(() => {
    if (elRef.value) {
      console.log('元素宽度：', elRef.value.offsetWidth)
    }
  })

  return <div ref={elRef}>Hello</div>
}

onShow()

组件显示时调用，包括首次挂载和从隐藏状态恢复显示。

类型定义

declare function onShow(callback: () => void): void

示例

tsx

import { ref, onShow } from 'vitarx'

function MyComponent() {
  const timer = ref<number | null>(null)

  onShow(() => {
    timer.value = window.setInterval(() => {
      console.log('定时执行')
    }, 1000)
  })

  return <div>定时器运行中</div>
}

onHide()

组件隐藏时调用，与 onShow 配对使用。

类型定义

declare function onHide(callback: () => void): void

示例

tsx

import { ref, onShow, onHide } from 'vitarx'

function AnimatedBox() {
  const timer = ref<number | null>(null)

  onShow(() => {
    timer.value = window.setInterval(() => console.log('动画帧'), 16)
  })

  onHide(() => {
    if (timer.value !== null) {
      clearInterval(timer.value)
      timer.value = null
    }
  })

  return <div>动画盒子</div>
}

onDispose()

组件即将被销毁时调用，用于清理资源和取消订阅。

类型定义

declare function onDispose(callback: () => void): void

示例

tsx

import { ref, onMounted, onDispose } from 'vitarx'

function ChatRoom(props: { roomId: string }) {
  const messages = ref<string[]>([])

  onMounted(() => {
    console.log(`加入聊天室：#123;props.roomId}`)
  })

  onDispose(() => {
    console.log(`离开聊天室：#123;props.roomId}`)
    messages.value = []
  })

  return <div>聊天室：{props.roomId}</div>
}

onError()

捕获组件内部发生的异常，包括子组件抛出的错误。

类型定义

type ErrorHandler = (error: unknown, info: ErrorInfo) => boolean | void

declare function onError(handler: ErrorHandler): void

参数

参数	类型	说明
`error`	`unknown`	错误对象
`info`	`ErrorInfo`	错误信息，包含 `source` 来源和 `instance` 实例

返回值

返回 false 表示错误已被处理，阻止错误继续向上冒泡；不返回或返回其他值则错误会继续冒泡到父组件。

示例

tsx

import { onError, ref } from 'vitarx'

function SafeComponent() {
  const hasError = ref(false)

  onError((error, info) => {
    console.error('捕获到错误：', error)
    hasError.value = true
    return false // 阻止错误继续冒泡
  })

  if (hasError.value) {
    return <div>组件出现异常</div>
  }
  return <div>正常内容</div>
}

参考：错误处理

onViewSwitch()

监听组件根视图的切换事件，常用于实现过渡动画。

类型定义

type ViewSwitchHandler = (tx: ViewSwitchTransaction) => void

declare function onViewSwitch(handler: ViewSwitchHandler): void

参数

参数	类型	说明
`tx`	`ViewSwitchTransaction`	视图切换事务对象

ViewSwitchTransaction

属性/方法	类型	说明
`prev`	`View`	切换前的视图
`next`	`View`	切换后的视图
`cachePrev`	`boolean`	是否缓存前一个视图
`propagationStopped`	`boolean`	是否已停止冒泡
`committed`	`boolean`	是否已提交
`stopPropagation()`	`void`	停止冒泡
`commitNext()`	`void`	提交下一个视图
`commitPrev()`	`void`	提交前一个视图
`commit()`	`void`	提交切换

示例

tsx

import { onViewSwitch, ref } from 'vitarx'
import { Dynamic } from 'vitarx'

function TabContainer() {
  const currentTab = ref(Home)

  onViewSwitch((tx) => {
    console.log('视图切换：', tx.prev, '->', tx.next)
    tx.cachePrev = true
  })

  return <Dynamic is={currentTab} />
}

onViewSwitch 主要用于高级场景，如自定义过渡动画。日常开发中，推荐使用内置的 Transition 组件。

生命周期执行顺序

组件首次创建并挂载：

text

组件函数执行 → onInit → onBeforeMount → DOM 挂载 → onShow / onMounted

组件隐藏和恢复显示：

text

隐藏时：onHide
恢复时：onShow

组件销毁：

text

onHide → onDispose

INFO