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/api-reference.md.

框架 API 参考

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

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

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

API 范围相关概念
默认函数入口、defineApp、配置 API框架概述与应用配置
生命周期回调、生命周期 Hooks、错误处理生命周期与错误处理
View Data、View Context、组件状态数据流与状态更新
React Hooks、组件树和线程模型视图渲染与交互

快速选择

需求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

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 是对应的业务参数对象;应用可以据此决定页面跳转、数据刷新或其他响应逻辑。

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 占位符见全页开发。

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

配置 API

function defineAppConfig(config: DoubaoAppsAppConfig): DoubaoAppsAppConfig

function defineConfig<Config extends DoubaoAppsConfig>(config: Config): Config
API使用位置用途
defineAppConfigsrc/app.config.ts配置应用 metadata 和 Page / Widget / Client Tool 入口
defineConfig构建配置文件配置插件、源码编译选项和调试驱动

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

运行时与数据

应用和视图运行时

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。

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

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

Agent 业务事件

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

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

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() => voidView created;事件已发生时会补触发一次
useMounted() => voidView mounted;事件已发生时会补触发一次
useDestroy() => voidView destroy
useShow / useHide() => voidView 显示与隐藏
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 依赖登录与隐私目录约定及组件协议,接入前应同时查阅对应开放能力文档。