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/client-framework/data-flow.md.

数据流与状态更新

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

数据来源与所有权

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

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

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

数据更新方向

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

上图包含以下数据路径:

  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() 获取输入;输入为空或无法解析时按空对象处理。

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 与端侧交互,接入示例见全页开发。

组件状态

组件状态的选择原则:

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

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

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 会请求一次后续渲染,不会修改当前渲染中的变量;
  • 同一个事件处理函数中的多次状态更新,会在事件处理结束后统一处理;
  • 依赖前一次状态计算新状态时,使用函数式更新;
  • 组件完成下一次渲染,不代表原生布局或绘制已经完成;

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

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 四种状态,并避免组件销毁后更新状态。

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 继承卡片上下文显式传递或使用业务关联