视图渲染与交互
豆包应用插件使用 React 编程模型组织组件和状态,由 Lynx 渲染器负责生成原生 UI。本文介绍从 React 组件到原生视图的渲染过程,以及元素、事件和线程模型。
注意
- 组件写法接近 React,但运行环境不是浏览器,也没有 HTML DOM;
- Page 和 Widget 使用 SDK 提供的 UI 组件,不能直接使用 HTML 标签、DOM API 或浏览器事件模型;
渲染模型
开发者使用 JSX、函数组件和 Hooks 编写视图,但 JSX 中的基础标签对应渲染器元素,而不是 HTML。运行时采用双线程架构,由主线程和后台线程分工完成组件执行与原生视图渲染。
线程职责
Framework 当前没有公开主线程脚本 API。开发者不需要选择或调度线程,只需要按职责组织代码:
- 组件函数只负责计算并返回组件树;
- 点击处理、状态更新和普通业务逻辑写在事件处理函数中;
- 请求、订阅、计时器和资源清理写在事件处理函数、Effect 或 Framework 生命周期中;
- 拖拽、轮播等连续交互优先使用
movable-view、swiper等专用组件,业务代码只处理确实需要的结果和回调; - Framework 与 UI 渲染器负责在线程之间提交并绘制视图更新,不要从底层运行时包导入线程相关 API;
状态快照、函数式更新和批处理规则见数据流与状态更新。
首次渲染
首次渲染时,两条执行路径并行工作:
- 主线程根据构建产物尽快生成首屏,完成节点创建、布局和绘制;
- 后台线程并行运行 React,建立用于后续状态更新的节点树;
由于两条路径并行执行,组件函数必须保持纯粹,以保证首屏结果与后台线程建立的节点树一致。
对开发者而言,“保持纯粹”可以直接按下面的边界判断:
下面的组件计算只依赖当前输入,因此可以安全地参与首次渲染:
如果计算需要发起请求、订阅数据或写入外部系统,它就不再属于渲染逻辑。具体生命周期选择见生命周期与错误处理。
首屏后的更新
首屏完成后,普通交互会在主线程与后台线程之间完成三个阶段:
开发者不需要手动控制这三个阶段。普通交互按下面的边界编写:
下面是普通点击交互的推荐写法:
一次点击会由运行时完成“接收事件—更新组件—提交视图”。业务代码只描述事件结果,不需要感知线程切换;连续交互的组件选择见按交互类型选择执行方式。
渲染元素与组件树
豆包应用插件使用 JSX 组织组件。业务代码只能直接使用当前 SDK 已支持的内置标签,或者使用自行定义、导入的自定义组件。
- 内置标签采用小写形式,例如
<view>、<text>和<image>; - 自定义组件采用大写形式,例如
<ProductCard>; - 小写只是一种标签约定,不表示任意小写名称都可用。不要直接写
<div>、<span>,也不要自行创造<card>等未被 SDK 声明的标签;
完整的内置标签及其属性以组件文档为准。常见 Web 元素在 SDK 中应按下表替换。
普通文本必须放在 <text> 中,不能在 <view> 里放裸文本,也不能使用 HTML 标签。
豆包应用插件的 UI 渲染环境没有浏览器的 document 和 window。依赖 DOM 查询、HTML 注入、浏览器布局测量或直接修改节点的 Web 库不能直接用于 Page / Widget。
选择第三方库时,先确认它只依赖纯 JavaScript。涉及 UI、网络、Storage、路由或设备能力时,使用 Framework 与应用插件已公开的组件和 API。
选择容器与内容元素
这些小写标签不仅替代 HTML 标签,还决定原生布局、滚动和资源加载方式。常用组件可以按下表选择。
组件确定后,需要为布局、文本、背景等设置样式时,先通过 CSS 能力清单确认属性和取值是否可用。
page 是视图树根节点,但它本身不是滚动容器。全屏长内容需要显式使用 scroll-view;数据量较大、条目持续增长或需要按需渲染时,使用 list,不要用大量 view 堆在 scroll-view 中。
list 中组件代码的执行时机,与列表项实际出现在屏幕上的时机不同:
- 列表创建时,子组件的 JavaScript 实例可以先创建,
useEffect和普通ref也可能已经执行; - 列表项接近可视区域时,运行时才按需创建或复用实际参与布局和绘制的列表项;
因此,组件已挂载不代表列表项已经出现在屏幕上。判断曝光或可见性时,使用当前公开的列表、曝光或可见性能力。
scroll-view 和 list 会建立独立的滚动上下文。把内容移入滚动容器后,需要重新检查 position: fixed、position: sticky、z-index 和覆盖层的表现。
图片用于参与内容布局时,优先在样式中给出确定尺寸,避免资源加载完成后才改变布局:
自定义组件不会自动创建布局容器
自定义组件是对组件代码的封装。例如,使用 <Card> 不会在它返回的内容外面自动增加一层 <view>。真正参与布局和交互的是自定义组件返回的 view、text 等 SDK 内置组件。
这会带来以下影响:
- 自定义组件本身没有独立的宽高、背景、边框、内边距或点击区域;
- 父容器进行 Flex 等布局时,实际参与布局的是自定义组件返回的 SDK 组件;
- 写在
<Card>上的className、style、id、dataset 和事件只会作为 props 传给Card,不会自动作用到它内部的<view>; - 如果自定义组件返回多个并列的 SDK 组件,这些组件会分别参与父容器布局,外面不会自动形成一个整体容器;
因此,自定义组件需要明确接收 className、事件等属性,并把它们传给内部对应的 SDK 组件:
示例中的样式和点击事件能够生效,是因为 Card 显式把 className 和 onOpen 传给了内部 <view>。如果只是从 props 中接收但没有继续传递,界面不会获得对应样式和交互。
使用自定义组件时注意:
key是 React 保留字段,不会出现在组件 props 中。业务需要该值时,使用itemId等普通属性显式传递;- 只在确认存在重复渲染瓶颈时使用
memo、PureComponent或稳定 props 优化,不要在没有测量依据时给所有组件增加缓存;
组件组织时遵循以下原则:
- Page / Widget 入口只负责连接 Framework;
- 具体视图拆成普通组件;
- 请求、订阅、上报和宿主 API 调用放在
useEffect、生命周期或事件处理函数中;
事件与交互
组件文档列出的内置标签可以直接写在 JSX 中,不需要手动导入。事件优先使用组件声明的 React 风格属性。
这里的“React 风格属性”是指使用驼峰命名并直接传入函数,例如 onClick={handleOpen}。它只是 SDK 组件的属性约定,不表示事件对象遵循浏览器 DOM 事件模型。
view、text、image 等基础组件使用 onClick 等 React 风格属性。需要阻止事件继续沿渲染器事件链传播时,使用组件文档声明的 onCatchTap 等属性。
不要把事件对象当作浏览器 DOM Event,也不要假设 preventDefault() 或 stopPropagation() 在普通后台线程事件中可用。
如果元素或组件的事件名、参数结构不确定,查询当前 SDK 版本生成的组件文档;不要仅根据 Web、React Native 或通用 Lynx 示例推测。
按交互类型选择执行方式
不同交互对延迟的要求不同,按下表选择执行位置。
例如,实现可拖拽内容时,不需要在业务组件中为每次移动维护一份坐标 state。
只有业务确实需要读取坐标或进行上报时,才处理 onDrag 回调;不要仅为了让同一个 movable-view 移动,再把回调坐标写回组件 state。