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

# 全页（Full Page）开发

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

## 注册和实现 Page

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

```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`：

```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 开发，更完整的元素、事件和线程边界见[视图渲染与交互](/apps-plugin/docs/client-framework/rendering.md)。

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

```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 后忽略过期结果。完整骨架见[开发概览](/apps-plugin/docs/frontend-development/overview.md#编写-page-和-widget-的最小规则)。如果直接使用端侧网络能力，从 `@doubao-dev/framework/api` 导入 `request`；请求地址必须是完整 HTTPS URL，`result.data` 仍需按业务 schema 做运行时校验。

## 响应 Agent 事件

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

### 声明事件与触发条件

在项目根目录创建 `events.json`：

```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` 中加入触发规则和事件占位符。事件名必须与声明、页面订阅完全一致：

```text
仅当用户明确要求修改已打开页面的标题时，发送 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`。

```tsx
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`，用于定位事件是否到达应用：

```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、空标题、页面关闭以及重复投递：错误目标不应更新，重复设置标题不应产生额外业务副作用。操作入口见[本地调试与预览](/apps-plugin/docs/development-tools/local-debugging.md)。

## 从 Widget 打开 Page

Widget 适合先展示摘要，Page 适合继续完成详情或复杂操作。使用 `navigateTo` 保留当前视图并打开应用内 Page：

```tsx
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。

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 48, "rankSpacing": 36, "htmlLabels": true}}}%%
flowchart TB
  WIDGET["Widget<br/>展示摘要"] -->|"用户点击详情"| ROUTER["navigateTo<br/>传递稳定业务标识"]
  ROUTER --> PAGE["Page<br/>读取标识并完成后续交互"]

  classDef tool fill:#FFF4E5,stroke:#D97706,color:#7C2D12;
  classDef view fill:#EEF4FF,stroke:#4C6FFF,color:#172B4D;
  class WIDGET,ROUTER,PAGE view;
```

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

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

## 预览与验证 Page

在本地调试工具中选择构建后发现的 Page 入口，注入与 `OrderPageData` 一致的测试数据，并以全页形态打开。需要检查以下结果：

- 页面可以读取 `orderId` 等 View Data；
- 页面展示、路由和返回行为符合预期；
- 加载、空态和失败状态可以通过不同测试数据触发；

调试工具显示打开请求已发送，不代表页面已经完成渲染，最终以 Web 模拟器中的实际结果为准。开发服务启动、Page 选择、测试数据注入和展示形态设置见[开发工具文档](/apps-plugin/docs/development-tools/index.md)。

## 完成检查

- Page 已在 `app.config.ts` 注册，首页顺序和标题符合产品设计；
- 调试时使用构建工具实际发现的完整 Page URL，没有只根据文件名猜测；
- URL query 或宿主注入的数据可以通过 `getViewData<T>()` 或 `useViewData<T>()` 读取；
- 页面处理了加载中、成功、空结果和失败状态；
- Widget 打开 Page 时只传递稳定业务标识，Page 按需获取最新业务数据；
- 已在 Web 模拟器中验证页面展示、路由和返回行为；

## 与多任务配合

当业务在用户离开 Page 后仍需继续执行时，可以使用 `createTask`、`updateTask` 和 `getTask` 管理任务状态，并在任务的跳转数据中提供返回 Page 所需的路径和参数。

多任务不是 Page 的替代品：Page 承载具体交互，多任务负责展示持续任务的状态和返回入口。仅在任务确实需要跨页面持续运行时接入多任务，普通页面加载和短时请求不需要创建任务。
