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

# 数据流与状态更新

豆包应用插件视图的数据分为宿主输入、运行上下文和组件状态。本文介绍这些数据的来源、读取方式、更新方向和生命周期边界。

## 数据来源与所有权

| 类型           | 来源           | 读取方式                                    | 适合保存                       |
| ------------ | ------------ | --------------------------------------- | -------------------------- |
| View Data    | 宿主创建或更新视图时注入 | `getViewData<T>()` / `useViewData<T>()` | 页面参数、卡片展示数据、宿主更新结果         |
| View Context | 宿主运行时        | `getViewContext()`                      | viewId、pageName、语言、消息与会话信息 |
| 组件状态         | 组件自身         | `useState()` / `useReducer()`           | 选中项、展开态、输入值、加载和错误态         |

三类数据的使用原则如下：

- View Data 是外部输入，不直接修改；
- View Context 描述运行环境，不作为业务数据库；
- 组件状态只保存当前交互；

## 数据更新方向

保持单向数据流，才能判断刷新由宿主输入还是组件交互触发。

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 60, "rankSpacing": 90, "htmlLabels": true}}}%%
flowchart TB
  E["用户事件<br/>进入事件处理函数"]
  E -->|调用端能力或业务| X["对外动作<br/>宿主 API / 业务系统"]
  E -->|更新当前组件状态| S["本地状态<br/>useState / useReducer"]
  X -->|按协议创建或更新视图| H["豆包宿主<br/>创建或更新视图输入"]
  H -->|注入数据| VD["View Data<br/>业务输入数据"]
  H -->|注入环境| VC["View Context<br/>运行环境与容器信息"]
  VD --> DR["数据读取<br/>getViewData / useViewData"]
  VC --> CR["上下文读取<br/>getViewContext"]
  DR --> C["React 组件<br/>组合外部输入与本地状态"]
  CR --> C
  S --> C
  C --> R["视图刷新<br/>UI 渲染器更新原生视图"]

  classDef event fill:#FFFFFF,stroke:#D99A19,stroke-width:2px,color:#1F2329;
  classDef external fill:#FFFFFF,stroke:#E65353,stroke-width:2px,color:#1F2329;
  classDef input fill:#FFFFFF,stroke:#3370FF,stroke-width:2px,color:#1F2329;
  classDef read fill:#FFFFFF,stroke:#7B67D6,stroke-width:2px,color:#1F2329;
  classDef render fill:#FFFFFF,stroke:#449B67,stroke-width:2px,color:#1F2329;
  class E,S event;
  class X external;
  class H,VD,VC input;
  class DR,CR read;
  class C,R render;
```

上图包含以下数据路径：

1. 宿主创建或更新 View Data，`useViewData` 订阅变化并触发组件刷新；
2. `getViewData` 读取当前快照，`getViewContext` 读取运行环境，两者本身不建立响应式订阅；
3. 用户操作通过本地 state 更新当前组件；
4. 事件处理函数可以调用端能力或业务请求，把用户动作发送到视图之外；

> **注意**
>
> - 本地 state setter 不会自动写回 View Data；
> - 业务请求的返回值不会自动更新 Widget；
> - 外部调用是否会进一步创建或更新 View Data，由对应 API 和宿主协议决定；

| 方向         | 典型入口                                    | Framework 语义          |
| ---------- | --------------------------------------- | --------------------- |
| 宿主 → 视图    | View Data、View Context                  | 宿主注入输入与运行环境；视图负责读取和校验 |
| 视图内部       | `useState`、`useReducer`、派生值             | 只管理当前组件交互，不改变宿主输入     |
| 视图 → 宿主或业务 | 事件处理函数、`@doubao-dev/framework/api`、业务请求 | 显式发起动作；后续结果按对应协议处理    |

根据更新目标选择方式：

- 更新当前 Widget 的本地显示：使用组件 state；
- 更新宿主持有的指定 Widget 实例：调用 `updateWidget` 等开放能力，并提供 `widgetInstanceId`；
- 从 Widget 打开 Page：通过路由参数向目标 Page 传递输入；

Page 不会自动继承原 Widget 的实例上下文。

## 外部输入与运行上下文

### View Data

两种 View Data 读取方式的区别：

- `getViewData<T>()` 返回调用时的输入快照，适合一次性读取；
- `useViewData<T>()` 读取当前值并订阅宿主更新，数据变化时触发组件刷新；

`useViewData<T>()` 当前监听 `onGlobalPropsChanged` 和 `onDataChanged` 事件。

Framework 会统一解析宿主注入的 View Data。业务代码不应读取底层注入字段，应始终通过 `getViewData()` 或 `useViewData()` 获取输入；输入为空或无法解析时按空对象处理。

```tsx
import { useViewData } from '@doubao-dev/framework';

interface DeliveryData {
  orderId: string;
  status: 'created' | 'shipping' | 'delivered';
}

export default function DeliveryCard() {
  const data = useViewData<DeliveryData>();
  return <text>订单 {data.orderId}：{data.status}</text>;
}
```

TypeScript 泛型只约束编译期。来自外部系统的枚举、深层对象、金额等关键字段仍需运行时校验。

### View Context

`getViewContext()` 返回当前视图上下文。常用字段包括：

- 视图信息：`viewId`、`pageName`、`lang`、`appSettings`；
- 消息信息：`botId`、`msgId`、可选 `conversationId` 和 `replyFor`；
- Widget 容器信息：`extra?.width`、`extra?.height`；

上下文可能包含消息和会话标识。日志和上报应使用字段白名单，只记录定位问题所需信息，不直接序列化完整 Context。

- `getWidgetInstanceId()`：在 Widget 中取得当前卡片实例 ID。Page 需要操作原卡片时，应由 Widget 显式传递该 ID，或者通过业务数据关联；
- `getCurrentPages()`：返回页面栈。当前公开项只有 `route`，不应用作业务状态存储；

## Agent 更新页面

Agent 事件通过 `useAgentEvent` 将 payload 交给页面，业务校验目标标识和字段后更新组件状态；该操作不会自动写入 View Data 或服务端。

运行语义见[Agent 与端侧交互](/apps-plugin/docs/client-framework/agent-interaction.md)，接入示例见[全页开发](/apps-plugin/docs/frontend-development/full-page.md#响应-agent-事件)。

## 组件状态

组件状态的选择原则：

- 简单交互使用 `useState`；
- 多个字段需要一致变化时使用 `useReducer`；
- 可以从 View Data 和现有 state 计算的值优先直接派生；
- 派生计算开销较大时再使用 `useMemo`；

不要复制一份可能与输入失去同步的 state。

```tsx
import { useMemo, useState, useViewData } from '@doubao-dev/framework';

interface ProductData {
  price: number;
  stock: number;
}

function ProductCard() {
  const data = useViewData<ProductData>();
  const [quantity, setQuantity] = useState(1);
  const total = useMemo(() => data.price * quantity, [data.price, quantity]);

  return (
    <view>
      <text>数量：{quantity}</text>
      <text>合计：{total}</text>
      <button
        text="增加"
        disabled={quantity >= data.stock}
        onClick={() => setQuantity(value => value + 1)}
      />
    </view>
  );
}
```

### 状态更新时序

组件状态遵循 React 的快照和事件批处理语义：

- 调用 `useState` 返回的 setter 会请求一次后续渲染，不会修改当前渲染中的变量；
- 同一个事件处理函数中的多次状态更新，会在事件处理结束后统一处理；
- 依赖前一次状态计算新状态时，使用函数式更新；
- 组件完成下一次渲染，不代表原生布局或绘制已经完成；

下面的示例在一次点击中连续加两次：

```tsx
import { useState } from '@doubao-dev/framework';

function Counter() {
  const [count, setCount] = useState(0);

  function addTwo() {
    setCount(value => value + 1);
    setCount(value => value + 1);
    console.log(count); // 当前点击开始时取得的状态快照
  }

  return <button text={`计数：${count}`} onClick={addTwo} />;
}
```

如果点击前 `count` 为 `0`，这次事件中的日志仍然输出 `0`，下一次渲染显示 `2`。日志说明的是 React 状态快照，不用于判断原生视图是否已经绘制。

更新状态时遵循以下原则：

- 不要在调用 setter 后立即读取同一渲染闭包中的变量并期待得到新值；
- 同一业务动作涉及多个关联字段时，优先使用 `useReducer()` 集中表达更新规则；
- 需要在 props 或 state 变化后同步请求、订阅等外部系统时，使用依赖明确的 `useEffect()`；
- 宿主输入与本地 state 是两个更新来源；同时依赖两者的展示值，应在组件渲染时根据 `useViewData()` 返回值和当前 state 直接计算；

### 异步加载

View Data 通常提供入口参数，组件再按需请求业务数据。异步加载至少处理 loading、success、empty、error 四种状态，并避免组件销毁后更新状态。

```tsx
useEffect(() => {
  let disposed = false;

  async function load() {
    try {
      setLoading(true);
      setError(null);
      // 业务请求函数，示例省略具体实现
      const result = await queryOrder(orderId);
      if (!disposed) setOrder(result);
    } catch (cause) {
      if (!disposed) setError(cause instanceof Error ? cause.message : String(cause));
    } finally {
      if (!disposed) setLoading(false);
    }
  }

  void load();
  return () => {
    disposed = true;
  };
}, [orderId]);
```

如果宿主会更新 `orderId`，使用 `useViewData()` 获取响应式输入，并让 Effect 依赖新的 `orderId`。

## 常见问题

| 现象                 | 原因                    | 处理                 |
| ------------------ | --------------------- | ------------------ |
| 宿主更新后不刷新           | 使用快照式 `getViewData()` | 改用 `useViewData()` |
| 本地状态被宿主更新覆盖        | 把外部输入完整复制成 state      | 只保存交互增量，其他值派生计算    |
| 请求重复               | 请求写在 render 或依赖不稳定    | 放入 Effect，依赖稳定标量   |
| 销毁后仍写状态            | 异步任务未清理               | cleanup 中取消或忽略过期结果 |
| Page 拿不到 Widget ID | 误以为 Page 继承卡片上下文      | 显式传递或使用业务关联        |
