For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/client-framework/lifecycle.md.

生命周期与错误处理

生命周期用于描述应用、视图和组件从创建到销毁的状态变化。本文介绍三层生命周期、组件副作用与资源清理,以及不同错误来源的处理边界。

管理资源时,先判断资源属于哪个层级、是否依赖首次渲染,以及隐藏或销毁时应该暂停还是彻底释放。

三层生命周期

层级来源适合管理
AppdefineApp()全局初始化、前后台订阅、应用级埋点和兜底
Page / Widget默认导出函数组件视图可见性和视图资源
组件React Hooks;也可以在组件内订阅 Framework 的 View 生命周期依赖组件参数的请求、订阅、局部状态和可复用逻辑

每个 View 实例只挂载一次,但显示与隐藏可以发生多次;应用进入后台也不等于 View 已经销毁。因此,暂停工作和释放资源需要分开处理。

按资源归属选择生命周期

资源或任务建议启动位置暂停或刷新最终清理
应用级监听、全局连接onLaunch()onBackground() 暂停,onForeground() 恢复App onDestroy()
View 首次挂载后的初始化useMounted()返回视图后需要刷新时,补充 useShow()useDestroy()
仅可见时运行的轮询或媒体任务useShow()useHide() 暂停destroy 时彻底释放
依赖组件参数的请求或订阅useEffect()依赖变化时由 Effect 重新执行Effect cleanup
组件内部临时计时器创建计时器的 Effect 或事件处理由业务状态决定是否暂停Effect cleanup 或 useDestroy()

同一资源只选择一个主要所有者。例如,组件已经在 Effect 中创建并清理订阅时,不要再通过 useDestroy() 重复释放。需要跨显示周期复用的资源,应区分“隐藏时暂停”和“销毁时释放”。

上图包含两条事件轴:

  1. useCreated、useMounted 和 useDestroy 订阅 View 实例从创建、挂载到销毁的阶段;
  2. useShow / useHide 订阅宿主可见性事件,可以往返多次;

应用的 foreground / background 是第三个维度,描述应用前后台或设备锁定状态变化,与 View 可见性相交但不等价。

注意

不要从图中推导 useMounted 与首次 useShow 回调的严格先后关系。业务代码应分别按“首次渲染后”和“每次可见时”的语义组织任务。

App 生命周期

钩子触发语义典型职责
onLaunch()应用启动初始化应用级状态、注册全局监听
onPageOpened({ viewId })Page 打开页面统计、关联 viewId 排障
onForeground()应用进入前台恢复全局订阅、刷新时效数据
onBackground()应用进入后台暂停轮询、保存状态
onDestroy()应用销毁释放应用级资源
onError(error)App 其他生命周期回调抛错记录、上报和隔离

Framework 会把 App 生命周期中的同步异常规范化为 Error 后交给 onError。如果 onError 自身再次抛错,Framework 只记录错误,避免递归。

onAgentEvent(name, payload) 是运行在 App runtime 的应用级业务事件,不是生命周期。它可以重复触发,适合集中处理 Agent 驱动的跳转或刷新;回调同步抛错时同样进入 App onError。Page 函数组件使用 useAgentEvent(name, callback) 通过 getApp().eventChannel 订阅按业务事件名隔离的内部事件,组件清理时自动取消;Hook 回调错误同样交给 App onError。

View 生命周期 Hooks

useCreated()、useMounted()、useShow() 等 Hook 不是 React 组件自身的挂载或卸载生命周期。它们让函数组件订阅当前 Page / Widget 的 View 生命周期,因此多个组件可能收到同一次 View 事件。

Hook对应事件关键特性
useCreated(callback)View created事件已发生时,晚注册会立即补触发一次
useMounted(callback)View mounted事件已发生时,晚注册会立即补触发一次
useShow() / useHide()View show / hide按当前 viewId 注册宿主监听
useForeground() / useBackground()应用前后台在组件内恢复或暂停工作
useDestroy()View destroy在组件内注册 View 销毁清理
useError()生命周期 Hook 错误接收规范化后的 Error
import { useError, useHide, useMounted, useShow, useState } from '@doubao-dev/framework';

function LiveStatus() {
  const [active, setActive] = useState(false);

  useMounted(() => console.log('view mounted'));
  useShow(() => setActive(true));
  useHide(() => setActive(false));
  useError(error => console.error('lifecycle hook error', error));

  return <text>{active ? '运行中' : '已暂停'}</text>;
}

这些 View 生命周期 Hooks 还有两项特殊行为:

  • Framework 会记录 created 和 mounted 是否已经发生;组件晚注册 useCreated 或 useMounted 时,会立即补触发一次;
  • Framework 会暂存 useError 注册前发生的生命周期 Hook 错误,并在监听器注册后交付;

注意

该错误交付机制不是通用 React Error Boundary。

Effect 与资源清理

useEffect 用于让组件与请求、订阅、计时器等外部系统保持同步。依赖变化后,React 运行时会先执行上一次 cleanup,再执行新的 Effect;组件卸载时还会执行最后一次 cleanup。

useEffect、useMounted 和布局回调解决的问题不同:

需求使用方式不代表
根据 props 或 state 建立、更新和清理副作用useEffect原生节点已经可见或完成绘制
View 首次挂载后执行一次任务useMounted某个具体节点已经完成布局
读取节点布局变化组件文档声明的 onLayout / onLayoutChangeView 生命周期发生变化

注意

不要依赖“副作用在同一渲染调用栈中完成”的假设,也不要在组件函数中执行请求、订阅或写操作。

Framework 公开 useEffect,但没有公开 useLayoutEffect。需要布局结果时,使用对应组件公开的布局事件;不要用 useEffect 或 useMounted 推断布局和绘制时机。

例如,需要在容器尺寸变化后执行逻辑时,监听组件公开的布局事件:

function MeasuredCard() {
  return (
    <view onLayoutChange={handleLayoutChange}>
      <text>内容</text>
    </view>
  );
}

线程职责和事件更新链路见视图渲染与交互。

错误处理

注意

图中的三条错误路径不能互相替代。业务异步错误需要显式捕获,生命周期错误处理器不是所有 Promise rejection 的全局接收器。

  1. App 生命周期回调抛错时,Framework 调用 App 的 onError;
  2. 组件内注册的 View 生命周期 Hook 回调抛错时,Framework 规范化错误并交给 useError;
  3. 业务异步请求、事件处理和 Promise 链应自行使用 try/catch 或 .catch(),不能假设它们一定进入生命周期错误链路;
import { useEffect, useState } from '@doubao-dev/framework';

function OrderState({ orderId }: { orderId: string }) {
  const [status, setStatus] = useState('loading');
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    let disposed = false;

    async function load() {
      try {
        setError(null);
        // 业务请求函数,示例省略具体实现
        const result = await fetchOrder(orderId);
        if (!disposed) setStatus(result.status);
      } catch (cause) {
        if (!disposed) {
          setError(cause instanceof Error ? cause.message : String(cause));
          setStatus('error');
        }
      }
    }

    void load();
    return () => {
      disposed = true;
    };
  }, [orderId]);

  if (status === 'loading') return <text>加载中</text>;
  if (status === 'error') return <text>{error ?? '加载失败'}</text>;
  return <text>{status}</text>;
}

常见问题

现象检查项处理方式
请求重复请求是否写在组件函数或可重复触发的 useShow() 回调中将一次性请求放入 useMounted() 回调或依赖明确的 Effect
应用进入后台后任务仍在运行是否处理 background 生命周期在 background 暂停,在 foreground 恢复
返回页面后数据过期是否只在 useMounted() 回调中加载在 useShow() 回调中按需刷新
异步错误未被生命周期错误处理器捕获是否来自异步任务或 Promise 链在业务代码中显式捕获并上报
组件卸载后仍更新状态Effect 是否缺少 cleanup取消任务或忽略过期结果