框架 API 参考
本页整理 @doubao-dev/framework 与 @doubao-dev/framework/config 的核心公开 API。
网络、路由、Storage、设备、登录和支付等宿主能力从 @doubao-dev/framework/api 暴露,应查阅对应端能力文档。
本页用于按名称查询 API;如果需要理解 API 在运行时中的位置,先阅读对应概念文章。
快速选择
入口与配置
defineApp
定义 src/app.ts 应用入口。
主要选项包括:
onLaunch、onPageOpened({ viewId });onAgentEvent(name, payload);onForeground、onBackground;onDestroy、onError(error);
onAgentEvent 接收 Agent 发给当前应用的业务事件。name 是事件名,payload 是对应的业务参数对象;应用可以据此决定页面跳转、数据刷新或其他响应逻辑。
Framework 自动向 useAgentEvent 订阅者分发事件,App 无需手动转发。事件声明和 Skill 占位符见全页开发。
事件载荷来自宿主和业务协议。处理安全或数据一致性相关操作前,应按事件名校验必要字段,不要根据缺失字段推测业务对象。
配置 API
两个 API 都返回传入对象并提供类型检查,但职责不同。
运行时与数据
应用和视图运行时
getApp() 只用于应用运行时内确有必要的共享方法或状态,不应作为 Page、Widget 或任意组件间传值的默认方案。跨入口数据使用 View Data、路由参数、开放能力或业务存储显式传递。
getViewData()、getViewContext() 和 getWidgetInstanceId() 都是快照读取,不建立订阅。需要响应宿主输入变化时使用 useViewData()。所有类型参数只提供编译期约束,不替代运行时数据校验。
useViewMeta
useViewMeta() 可在 Page 和 Widget(卡片)函数组件中调用,返回当前视图的运行时元数据。isPage 和 isWidget 根据编译器生成入口时注入的固定类型标记确定,正常渲染时只有一个为 true;旧版编译产物或入口类型标记缺失时,两者均为 false。
Agent 业务事件
useAgentEvent 在 Page 函数组件中按业务事件名订阅 Agent 事件,并在组件卸载或事件名变化时自动取消当前订阅。
当前签名不提供 options,也不判断 Page 是否位于页面栈顶。只要组件仍挂载,匹配的回调就会执行。Hook 通过 getApp().eventChannel 订阅 Framework 内部事件 @@doubao.onAgentEvent.<eventName>,每个业务事件独立注册和清理;回调抛出的同步错误交给 App onError,不会阻断其他监听器。
View 生命周期 Hooks
这些 Hooks 在函数组件中订阅当前 Page / Widget 的 View 生命周期,不等同于 React 组件自身的挂载和卸载。
所有 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 依赖登录与隐私目录约定及组件协议,接入前应同时查阅对应开放能力文档。