全页(Full Page)开发
Page 用于承载需要更多空间和连续交互的界面,例如详情、表单、地图和多步骤业务流程。本章说明从入口注册、数据读取、状态处理到联动调试的完整开发方式。
注册和实现 Page
先在 src/app.config.ts 中注册入口:
再创建 src/pages/order-detail/index.tsx:
这个最小示例完成了两件事:
- 在
app.config.ts声明 Page 入口及标题; - 默认导出 Page 函数组件,并使用
useViewData<T>()读取可更新的页面输入;
页面需要滚动时显式使用 scroll-view,并为滚动容器设置可解析的高度。文本必须放在 text 中;图片应设置明确尺寸;请求和订阅不要写进 render()。这些规则足以完成常规 Page 开发,更完整的元素、事件和线程边界见视图渲染与交互。
同目录的 index.scss 可以从以下最小布局开始:
加载业务数据
Page 通常只从 View Data 取得稳定业务标识,再向业务服务读取最新数据。实现时需要区分以下状态:
业务请求放在依赖明确的 useEffect() 中,并在 cleanup 后忽略过期结果。完整骨架见开发概览。如果直接使用端侧网络能力,从 @doubao-dev/framework/api 导入 request;请求地址必须是完整 HTTPS URL,result.data 仍需按业务 schema 做运行时校验。
响应 Agent 事件
全页事件用于把 Agent 生成的业务参数投递到已经打开的页面。完整链路包括事件声明、Skill 触发规则、宿主投递和页面订阅;仅添加 Hook 不会让 Agent 自动知道事件。
声明事件与触发条件
在项目根目录创建 events.json:
events.json 的根对象包含 events 数组。每个事件使用 name 标识名称,description 描述用途,payloadSchema 描述事件参数对象的字段和必填项。
这里使用的是平台支持的 JSON Schema 子集,不支持 enum、数值上下界(minimum / maximum,即 min/max)等校验能力。不要在 schema 中添加这些约束;将可选值和取值范围写入字段 description,并在业务代码中校验。此限制同时适用于 tools.json 的 inputSchema、outputSchema 和 events.json 的 payloadSchema。
在开发者的 SKILL.md 中加入触发规则和事件占位符。事件名必须与声明、页面订阅完全一致:
task_id 是本例的业务字段,用于区分目标任务,不是 Framework 自动执行的路由字段。真实应用应使用自己的稳定业务标识;需要区分同一任务的多个页面实例时,还应在业务协议中加入实例标识并校验。
在页面中接收并更新
以下组件可以保存到 src/pages/event-demo/index.tsx,并注册在 app.config.ts.pages 中。打开时传入 taskId,例如 /pages/event-demo/index?taskId=demo-001。
Hook 在组件挂载后订阅,卸载或事件名变化时自动清理;回调使用最近一次渲染的值。它没有 options,也不按栈顶或可见性过滤事件。不要假设隐藏页面已经卸载;只允许可见页面处理的业务,应结合 useShow / useHide 维护可见状态,再在回调中检查。
可选:观察 App 接收情况
把以下回调合入已有 src/app.ts,用于定位事件是否到达应用:
Framework 会调用可选的 App 回调,再将事件分发给订阅者。无需在 App 回调中手动 emit;也不要同时在 App 和 Page 中重复执行同一业务修改。事件不缓存、不重放,页面应先完成订阅;关键业务状态需要通过正常加载流程获取。
验证事件链路
先保持目标 Page 打开,在 Web 模拟器的全页工具栏点击“事件”,选择 demo.pageDataUpdated,输入 {"task_id":"demo-001","title":"Updated title"} 并触发,确认页面文字更新。再通过对话输入:“把已打开的 demo-001 页面标题改为 Updated title。”
对话测试需要看到 Agent 事件记录、应用接收和实际页面变化。手动触发只验证投递和页面处理,不验证 Skill 是否让 Agent 正确生成事件。还应测试错误任务 ID、空标题、页面关闭以及重复投递:错误目标不应更新,重复设置标题不应产生额外业务副作用。操作入口见本地调试与预览。
从 Widget 打开 Page
Widget 适合先展示摘要,Page 适合继续完成详情或复杂操作。使用 navigateTo 保留当前视图并打开应用内 Page:
联动时建议只在 URL 中传递定位业务对象所需的稳定标识,Page 再按需读取最新详情;不要把整份可变业务对象拼进 URL。
Framework 会把页面 URL 的 query 解析为 View Data,因此示例中的 orderId 可以通过 Page 内的 useViewData<OrderPageData>() 读取。业务代码不需要直接解析底层 URL。
同一 Page 内继续跳转时,可以根据页面栈需求选择:
预览与验证 Page
在本地调试工具中选择构建后发现的 Page 入口,注入与 OrderPageData 一致的测试数据,并以全页形态打开。需要检查以下结果:
- 页面可以读取
orderId等 View Data; - 页面展示、路由和返回行为符合预期;
- 加载、空态和失败状态可以通过不同测试数据触发;
调试工具显示打开请求已发送,不代表页面已经完成渲染,最终以 Web 模拟器中的实际结果为准。开发服务启动、Page 选择、测试数据注入和展示形态设置见开发工具文档。
完成检查
- Page 已在
app.config.ts注册,首页顺序和标题符合产品设计; - 调试时使用构建工具实际发现的完整 Page URL,没有只根据文件名猜测;
- URL query 或宿主注入的数据可以通过
getViewData<T>()或useViewData<T>()读取; - 页面处理了加载中、成功、空结果和失败状态;
- Widget 打开 Page 时只传递稳定业务标识,Page 按需获取最新业务数据;
- 已在 Web 模拟器中验证页面展示、路由和返回行为;
与多任务配合
当业务在用户离开 Page 后仍需继续执行时,可以使用 createTask、updateTask 和 getTask 管理任务状态,并在任务的跳转数据中提供返回 Page 所需的路径和参数。
多任务不是 Page 的替代品:Page 承载具体交互,多任务负责展示持续任务的状态和返回入口。仅在任务确实需要跨页面持续运行时接入多任务,普通页面加载和短时请求不需要创建任务。