> 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.

# 生命周期与错误处理

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

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

## 三层生命周期

| 层级            | 来源                                          | 适合管理                    |
| ------------- | ------------------------------------------- | ----------------------- |
| App           | `defineApp()`                               | 全局初始化、前后台订阅、应用级埋点和兜底    |
| 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()` 重复释放。需要跨显示周期复用的资源，应区分“隐藏时暂停”和“销毁时释放”。

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 50, "rankSpacing": 70, "htmlLabels": true}}}%%
flowchart TB
  S([创建视图]) --> C["Created<br/>useCreated"]
  C -->|Framework 挂载组件树| M["Mounted<br/>useMounted"]
  M -->|显示| V["Visible<br/>useShow"]
  V -->|隐藏| H["Hidden<br/>useHide"]
  H -->|再次显示| V
  V -->|销毁| D([Destroyed])
  H -->|销毁| D

  classDef entry fill:#F0F4FC,stroke:#5178C6,stroke-width:2px,color:#1F2329;
  classDef created fill:#FFFFFF,stroke:#3370FF,stroke-width:2px,color:#1F2329;
  classDef mounted fill:#FFFFFF,stroke:#7B67D6,stroke-width:2px,color:#1F2329;
  classDef visible fill:#FFFFFF,stroke:#449B67,stroke-width:2px,color:#1F2329;
  classDef hidden fill:#FFFFFF,stroke:#D99A19,stroke-width:2px,color:#1F2329;
  classDef destroyed fill:#FDE2E2,stroke:#E65353,stroke-width:2px,color:#1F2329;
  class S entry;
  class C created;
  class M mounted;
  class V visible;
  class H hidden;
  class D destroyed;
```

上图包含两条事件轴：

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`     |

```tsx
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` / `onLayoutChange` | View 生命周期发生变化 |

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

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

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

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

线程职责和事件更新链路见[视图渲染与交互](/apps-plugin/docs/client-framework/rendering.md)。

## 错误处理

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 50, "rankSpacing": 90, "htmlLabels": true}}}%%
flowchart TB
  E([发生错误]) --> S{错误来源}
  S -->|App 生命周期| A["App 生命周期<br/>进入 App.onError"]
  S -->|View 生命周期 Hook| C["组件内注册的 View Hook<br/>交给 useError 监听器"]
  S -->|Promise / 事件任务| P["异步业务任务<br/>业务代码显式捕获"]
  A --> H([记录、上报、隔离])
  C --> H
  P --> H

  classDef error fill:#FDE2E2,stroke:#E65353,stroke-width:2px,color:#1F2329;
  classDef decision fill:#FFF1CC,stroke:#D99A19,stroke-width:2px,color:#1F2329;
  classDef app fill:#FFFFFF,stroke:#3370FF,stroke-width:2px,color:#1F2329;
  classDef hook fill:#FFFFFF,stroke:#449B67,stroke-width:2px,color:#1F2329;
  classDef async fill:#FFFFFF,stroke:#E65353,stroke-width:2px,color:#1F2329;
  classDef handled fill:#DDF3E4,stroke:#449B67,stroke-width:2px,color:#1F2329;
  class E error;
  class S decision;
  class A app;
  class C hook;
  class P async;
  class H handled;
```

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

1. App 生命周期回调抛错时，Framework 调用 App 的 `onError`；
2. 组件内注册的 View 生命周期 Hook 回调抛错时，Framework 规范化错误并交给 `useError`；
3. 业务异步请求、事件处理和 Promise 链应自行使用 `try/catch` 或 `.catch()`，不能假设它们一定进入生命周期错误链路；

```tsx
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               | 取消任务或忽略过期结果                             |
