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/frontend-development/full-page.md.

全页(Full Page)开发

Page 用于承载需要更多空间和连续交互的界面,例如详情、表单、地图和多步骤业务流程。本章说明从入口注册、数据读取、状态处理到联动调试的完整开发方式。

注册和实现 Page

先在 src/app.config.ts 中注册入口:

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

export default defineAppConfig({
  appId: 'your-app-id',
  name: '订单服务',
  pages: ['pages/order-detail/index']
});

再创建 src/pages/order-detail/index.tsx:

import { useShow, useViewData } from '@doubao-dev/framework';
import './index.scss';

interface OrderPageData {
  orderId?: string;
  title?: string;
}

export default function OrderDetailPage() {
  const data = useViewData<OrderPageData>();

  useShow(() => {
    console.log('order detail shown');
  });

  return (
    <scroll-view scrollOrientation="vertical" enableScroll>
      <view className="order-detail">
        <text className="order-detail__title">{data.title ?? '订单详情'}</text>
        <text className="order-detail__id">订单号:{data.orderId ?? '--'}</text>
      </view>
    </scroll-view>
  );
}

这个最小示例完成了两件事:

  • 在 app.config.ts 声明 Page 入口及标题;
  • 默认导出 Page 函数组件,并使用 useViewData<T>() 读取可更新的页面输入;

页面需要滚动时显式使用 scroll-view,并为滚动容器设置可解析的高度。文本必须放在 text 中;图片应设置明确尺寸;请求和订阅不要写进 render()。这些规则足以完成常规 Page 开发,更完整的元素、事件和线程边界见视图渲染与交互。

同目录的 index.scss 可以从以下最小布局开始:

.order-detail {
  display: flex;
  flex-direction: column;
  gap: 8px;
  width: 100%;
  min-height: 100%;
  padding: 16px;
  box-sizing: border-box;
}

.order-detail__title {
  font-size: 20px;
  font-weight: 600;
  white-space: normal;
}

加载业务数据

Page 通常只从 View Data 取得稳定业务标识,再向业务服务读取最新数据。实现时需要区分以下状态:

状态进入条件页面处理
参数缺失View Data 中没有必要标识显示明确提示,不发起请求
加载中请求已开始且未结束显示加载状态,避免重复提交
成功返回合法业务数据渲染最新内容
空结果请求成功但没有目标数据显示空态,不当作异常
失败网络、状态码或数据校验失败显示失败信息并提供重试入口

业务请求放在依赖明确的 useEffect() 中,并在 cleanup 后忽略过期结果。完整骨架见开发概览。如果直接使用端侧网络能力,从 @doubao-dev/framework/api 导入 request;请求地址必须是完整 HTTPS URL,result.data 仍需按业务 schema 做运行时校验。

响应 Agent 事件

全页事件用于把 Agent 生成的业务参数投递到已经打开的页面。完整链路包括事件声明、Skill 触发规则、宿主投递和页面订阅;仅添加 Hook 不会让 Agent 自动知道事件。

声明事件与触发条件

在项目根目录创建 events.json:

{
  "events": [
    {
      "name": "demo.pageDataUpdated",
      "description": "Update the displayed title for the current page task when explicitly requested by the user.",
      "payloadSchema": {
        "type": "object",
        "properties": {
          "task_id": { "type": "string", "description": "The target page task ID" },
          "title": { "type": "string", "description": "The title explicitly requested by the user" }
        },
        "required": ["task_id", "title"]
      }
    }
  ]
}

events.json 的根对象包含 events 数组。每个事件使用 name 标识名称,description 描述用途,payloadSchema 描述事件参数对象的字段和必填项。

这里使用的是平台支持的 JSON Schema 子集,不支持 enum、数值上下界(minimum / maximum,即 min/max)等校验能力。不要在 schema 中添加这些约束;将可选值和取值范围写入字段 description,并在业务代码中校验。此限制同时适用于 tools.json 的 inputSchema、outputSchema 和 events.json 的 payloadSchema。

在开发者的 SKILL.md 中加入触发规则和事件占位符。事件名必须与声明、页面订阅完全一致:

仅当用户明确要求修改已打开页面的标题时,发送 demo.pageDataUpdated 事件。
目标任务 ID 使用当前页面上下文或用户明确提供的值,标题使用用户要求的内容。
缺少必要信息时先追问。普通问答不发送此事件,也不声称该事件会保存服务端数据。

{{event:demo.pageDataUpdated}}

task_id 是本例的业务字段,用于区分目标任务,不是 Framework 自动执行的路由字段。真实应用应使用自己的稳定业务标识;需要区分同一任务的多个页面实例时,还应在业务协议中加入实例标识并校验。

在页面中接收并更新

以下组件可以保存到 src/pages/event-demo/index.tsx,并注册在 app.config.ts.pages 中。打开时传入 taskId,例如 /pages/event-demo/index?taskId=demo-001。

import { useAgentEvent, useState, useViewData } from '@doubao-dev/framework';

export default function EventDemoPage() {
  const { taskId } = useViewData<{ taskId?: string }>();
  const [title, setTitle] = useState('Original title');

  useAgentEvent('demo.pageDataUpdated', payload => {
    // Event schemas do not enforce page ownership; validate the target before changing local state.
    if (typeof taskId !== 'string' || !taskId || payload.task_id !== taskId) return;
    if (typeof payload.title !== 'string' || !payload.title.trim()) {
      console.error('Invalid demo.pageDataUpdated title');
      return;
    }
    setTitle(payload.title);
  });

  if (!taskId) return <text>Missing taskId</text>;
  return <text>{title}</text>;
}

Hook 在组件挂载后订阅,卸载或事件名变化时自动清理;回调使用最近一次渲染的值。它没有 options,也不按栈顶或可见性过滤事件。不要假设隐藏页面已经卸载;只允许可见页面处理的业务,应结合 useShow / useHide 维护可见状态,再在回调中检查。

可选:观察 App 接收情况

把以下回调合入已有 src/app.ts,用于定位事件是否到达应用:

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

export default defineApp({
  onAgentEvent(name) {
    console.log('Agent event received', name);
  }
});

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:

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

async function openOrderDetail(orderId: string) {
  await navigateTo({
    url: `/pages/order-detail/index?orderId=${encodeURIComponent(orderId)}`
  });
}

联动时建议只在 URL 中传递定位业务对象所需的稳定标识,Page 再按需读取最新详情;不要把整份可变业务对象拼进 URL。

Framework 会把页面 URL 的 query 解析为 View Data,因此示例中的 orderId 可以通过 Page 内的 useViewData<OrderPageData>() 读取。业务代码不需要直接解析底层 URL。

同一 Page 内继续跳转时,可以根据页面栈需求选择:

API行为
navigateTo保留当前页面,打开新页面
redirectTo关闭当前页面并打开目标页面
reLaunch关闭全部页面并打开目标页面
navigateBack关闭当前页面并返回页面栈中的上一页或多级页面

预览与验证 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 承载具体交互,多任务负责展示持续任务的状态和返回入口。仅在任务确实需要跨页面持续运行时接入多任务,普通页面加载和短时请求不需要创建任务。