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

# 框架 API 参考

本页整理 `@doubao-dev/framework` 与 `@doubao-dev/framework/config` 的核心公开 API。

网络、路由、Storage、设备、登录和支付等宿主能力从 `@doubao-dev/framework/api` 暴露，应查阅对应端能力文档。

本页用于按名称查询 API；如果需要理解 API 在运行时中的位置，先阅读对应概念文章。

| API 范围                      | 相关概念                                                         |
| --------------------------- | ------------------------------------------------------------ |
| 默认函数入口、`defineApp`、配置 API   | [框架概述与应用配置](/apps-plugin/docs/client-framework/overview.md)  |
| 生命周期回调、生命周期 Hooks、错误处理      | [生命周期与错误处理](/apps-plugin/docs/client-framework/lifecycle.md) |
| View Data、View Context、组件状态 | [数据流与状态更新](/apps-plugin/docs/client-framework/data-flow.md)  |
| React Hooks、组件树和线程模型        | [视图渲染与交互](/apps-plugin/docs/client-framework/rendering.md)   |

## 快速选择

| 需求                | API                                         |
| ----------------- | ------------------------------------------- |
| 定义应用              | `defineApp`                                 |
| 定义 Client Tool    | 默认导出 handler 函数，并在 `app.config.ts.tools` 注册 |
| 定义新 Page / Widget | 默认导出函数组件，并在 `app.config.ts` 注册              |
| 读取一次宿主输入          | `getViewData`                               |
| 响应宿主输入更新          | `useViewData`                               |
| 在组件中读取视图运行时元数据    | `useViewMeta`                               |
| 管理组件状态            | `useState` / `useReducer`                   |
| 根据组件数据同步和清理副作用    | `useEffect`                                 |
| View 首次挂载后执行一次任务  | `useMounted`                                |
| 读取节点布局变化          | 组件公开的 `onLayout` / `onLayoutChange`         |
| 处理视图可见性           | `useShow` / `useHide`                       |
| 响应 Agent 业务事件     | App `onAgentEvent` / Page `useAgentEvent`   |
| 调用路由、网络和端能力       | `@doubao-dev/framework/api` 对应 API          |

## 入口与配置

### `defineApp`

```ts
function defineApp<T extends DefineAppOptions>(options: T): App<T>
```

定义 `src/app.ts` 应用入口。

主要选项包括：

- `onLaunch`、`onPageOpened({ viewId })`；
- `onAgentEvent(name, payload)`；
- `onForeground`、`onBackground`；
- `onDestroy`、`onError(error)`；

`onAgentEvent` 接收 Agent 发给当前应用的业务事件。`name` 是事件名，`payload` 是对应的业务参数对象；应用可以据此决定页面跳转、数据刷新或其他响应逻辑。

```ts
import { defineApp } from '@doubao-dev/framework';
import { navigateTo } from '@doubao-dev/framework/api';

export default defineApp({
  onAgentEvent(name, payload) {
    if (name === 'doubaoMap.routePlanUpdated') {
      navigateTo({ url: `/pages/navigation/index?id=${String(payload.route_entity_id)}` });
    }
  }
});
```

Framework 自动向 `useAgentEvent` 订阅者分发事件，App 无需手动转发。事件声明和 Skill 占位符见[全页开发](/apps-plugin/docs/frontend-development/full-page.md#响应-agent-事件)。

事件载荷来自宿主和业务协议。处理安全或数据一致性相关操作前，应按事件名校验必要字段，不要根据缺失字段推测业务对象。

### 配置 API

```ts
function defineAppConfig(config: DoubaoAppsAppConfig): DoubaoAppsAppConfig

function defineConfig<Config extends DoubaoAppsConfig>(config: Config): Config
```

| API               | 使用位置                | 用途                                             |
| ----------------- | ------------------- | ---------------------------------------------- |
| `defineAppConfig` | `src/app.config.ts` | 配置应用 metadata 和 Page / Widget / Client Tool 入口 |
| `defineConfig`    | 构建配置文件              | 配置插件、源码编译选项和调试驱动                               |

两个 API 都返回传入对象并提供类型检查，但职责不同。

## 运行时与数据

### 应用和视图运行时

```ts
function getApp<T extends App = App>(): T
function getViewData<T extends Record<string, any>>(): T
function useViewData<T extends Record<string, any> = Record<string, any>>(): T
function getViewContext(): AIViewContext
function useViewMeta(): ViewMeta
function getWidgetInstanceId(): string | undefined
function getCurrentPages(): CurrentPage[]
```

| API                     | 使用位置               | 是否响应更新 | 返回与失败行为                                   |
| ----------------------- | ------------------ | ------ | ----------------------------------------- |
| `getApp<T>()`           | App 已初始化的应用运行环境    | 否      | 返回当前 App 实例；初始化前调用会抛错                     |
| `getViewData<T>()`      | Page / Widget 视图   | 否      | 读取当前 View Data 快照；输入解析失败时返回空对象            |
| `useViewData<T>()`      | Page / Widget 函数组件 | 是      | 视图数据更新时重新读取 View Data 并触发组件更新             |
| `getViewContext()`      | Page / Widget 视图   | 否      | 读取 viewId、消息、语言和容器信息；上下文缺失时返回空对象          |
| `useViewMeta()`         | Page / Widget 函数组件 | 是      | 读取当前视图类型，在页面展示形态变化时自动更新                   |
| `getWidgetInstanceId()` | Widget 视图          | 否      | 从 View Context 读取实例 ID；不存在时返回 `undefined` |
| `getCurrentPages()`     | 需要读取页面栈的运行环境       | 否      | 同步调用宿主能力；宿主未返回结果时得到空数组                    |

`getApp()` 只用于应用运行时内确有必要的共享方法或状态，不应作为 Page、Widget 或任意组件间传值的默认方案。跨入口数据使用 View Data、路由参数、开放能力或业务存储显式传递。

`getViewData()`、`getViewContext()` 和 `getWidgetInstanceId()` 都是快照读取，不建立订阅。需要响应宿主输入变化时使用 `useViewData()`。所有类型参数只提供编译期约束，不替代运行时数据校验。

### `useViewMeta`

`useViewMeta()` 可在 Page 和 Widget（卡片）函数组件中调用，返回当前视图的运行时元数据。`isPage` 和 `isWidget` 根据编译器生成入口时注入的固定类型标记确定，正常渲染时只有一个为 `true`；旧版编译产物或入口类型标记缺失时，两者均为 `false`。

```tsx
import { useViewMeta } from '@doubao-dev/framework';

export default function ViewTypeLabel() {
  const { isPage } = useViewMeta();
  return <text>{isPage ? '页面' : '卡片'}</text>;
}
```

## Agent 业务事件

```ts
function useAgentEvent(eventName: string, callback: AgentEventCallback): void
```

`useAgentEvent` 在 Page 函数组件中按业务事件名订阅 Agent 事件，并在组件卸载或事件名变化时自动取消当前订阅。

```tsx
import { useAgentEvent } from '@doubao-dev/framework';

function NavigationPage() {
  useAgentEvent('doubaoMap.routePlanUpdated', payload => {
    console.log('route updated', payload.route_entity_id);
  });

  return <view />;
}
```

当前签名不提供 options，也不判断 Page 是否位于页面栈顶。只要组件仍挂载，匹配的回调就会执行。Hook 通过 `getApp().eventChannel` 订阅 Framework 内部事件 `@@doubao.onAgentEvent.<eventName>`，每个业务事件独立注册和清理；回调抛出的同步错误交给 App `onError`，不会阻断其他监听器。

## View 生命周期 Hooks

这些 Hooks 在函数组件中订阅当前 Page / Widget 的 View 生命周期，不等同于 React 组件自身的挂载和卸载。

| API                               | 回调                       | 说明                        |
| --------------------------------- | ------------------------ | ------------------------- |
| `useCreated`                      | `() => void`             | View created；事件已发生时会补触发一次 |
| `useMounted`                      | `() => void`             | View mounted；事件已发生时会补触发一次 |
| `useDestroy`                      | `() => void`             | View destroy              |
| `useShow` / `useHide`             | `() => void`             | View 显示与隐藏                |
| `useForeground` / `useBackground` | `() => void`             | 应用前后台                     |
| `useError`                        | `(error: Error) => void` | 生命周期 Hook 错误              |

所有 Hooks 必须在函数组件顶层调用。`useCreated` 和 `useMounted` 在对应 View 事件已经发生后注册时会立即补触发。

## React API 重新导出

Framework 重新导出与豆包应用插件内置 React 运行时匹配的 API，应用插件代码应从 `@doubao-dev/framework` 导入。

- 状态与副作用：`useState`、`useReducer`、`useEffect`、`useSyncExternalStore`；
- 引用与缓存：`useRef`、`useMemo`、`useCallback`、`useImperativeHandle`；
- Context 与调试：`createContext`、`useContext`、`useDebugValue`；
- 组件组织：`memo`、`forwardRef`、`lazy`、`Fragment`、`Suspense`；
- 类组件与元素 API：`Component`、`PureComponent`、`createElement`、`cloneElement`、`createRef`、`isValidElement`；

Framework 没有公开 `useLayoutEffect`。根据组件数据同步外部系统时使用 `useEffect`；执行一次 View 级初始化时使用 `useMounted`；需要节点布局结果时使用对应组件公开的布局事件。

## 登录与隐私约定入口

| API                                 | 用途                                         |
| ----------------------------------- | ------------------------------------------ |
| `defineLoginPage(options)`          | 定义约定的自定义登录 Page                            |
| `definePrivacyLoginWidget(options)` | 定义登录与隐私授权 Widget                           |
| `defineLoginApi(api)`               | 定义 `onLogin` / `onRefuseLogin` 回调          |
| `definePrivacyApi(api)`             | 定义 `onAgreePrivacy` / `onRefusePrivacy` 回调 |

这些 API 依赖登录与隐私目录约定及组件协议，接入前应同时查阅对应开放能力文档。
