数据流与状态更新
豆包应用插件视图的数据分为宿主输入、运行上下文和组件状态。本文介绍这些数据的来源、读取方式、更新方向和生命周期边界。
数据来源与所有权
三类数据的使用原则如下:
- View Data 是外部输入,不直接修改;
- View Context 描述运行环境,不作为业务数据库;
- 组件状态只保存当前交互;
数据更新方向
保持单向数据流,才能判断刷新由宿主输入还是组件交互触发。
上图包含以下数据路径:
- 宿主创建或更新 View Data,
useViewData订阅变化并触发组件刷新; getViewData读取当前快照,getViewContext读取运行环境,两者本身不建立响应式订阅;- 用户操作通过本地 state 更新当前组件;
- 事件处理函数可以调用端能力或业务请求,把用户动作发送到视图之外;
注意
- 本地 state setter 不会自动写回 View Data;
- 业务请求的返回值不会自动更新 Widget;
- 外部调用是否会进一步创建或更新 View Data,由对应 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() 获取输入;输入为空或无法解析时按空对象处理。
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。
状态更新时序
组件状态遵循 React 的快照和事件批处理语义:
- 调用
useState返回的 setter 会请求一次后续渲染,不会修改当前渲染中的变量; - 同一个事件处理函数中的多次状态更新,会在事件处理结束后统一处理;
- 依赖前一次状态计算新状态时,使用函数式更新;
- 组件完成下一次渲染,不代表原生布局或绘制已经完成;
下面的示例在一次点击中连续加两次:
如果点击前 count 为 0,这次事件中的日志仍然输出 0,下一次渲染显示 2。日志说明的是 React 状态快照,不用于判断原生视图是否已经绘制。
更新状态时遵循以下原则:
- 不要在调用 setter 后立即读取同一渲染闭包中的变量并期待得到新值;
- 同一业务动作涉及多个关联字段时,优先使用
useReducer()集中表达更新规则; - 需要在 props 或 state 变化后同步请求、订阅等外部系统时,使用依赖明确的
useEffect(); - 宿主输入与本地 state 是两个更新来源;同时依赖两者的展示值,应在组件渲染时根据
useViewData()返回值和当前 state 直接计算;
异步加载
View Data 通常提供入口参数,组件再按需请求业务数据。异步加载至少处理 loading、success、empty、error 四种状态,并避免组件销毁后更新状态。
如果宿主会更新 orderId,使用 useViewData() 获取响应式输入,并让 Effect 依赖新的 orderId。