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/rendering.md.

视图渲染与交互

豆包应用插件使用 React 编程模型组织组件和状态,由 Lynx 渲染器负责生成原生 UI。本文介绍从 React 组件到原生视图的渲染过程,以及元素、事件和线程模型。

注意

  • 组件写法接近 React,但运行环境不是浏览器,也没有 HTML DOM;
  • Page 和 Widget 使用 SDK 提供的 UI 组件,不能直接使用 HTML 标签、DOM API 或浏览器事件模型;

渲染模型

开发者使用 JSX、函数组件和 Hooks 编写视图,但 JSX 中的基础标签对应渲染器元素,而不是 HTML。运行时采用双线程架构,由主线程和后台线程分工完成组件执行与原生视图渲染。

线程职责

线程主要职责对开发者的含义
主线程接收原生事件,更新渲染节点树,完成布局和绘制状态更新由运行时异步提交到这里;事件处理函数不能假设布局和绘制已同步完成
后台线程运行完整 React 运行时,执行普通事件处理、状态更新、组件生命周期和 Effect普通事件、状态和副作用通过 UI 运行时在这里执行

Framework 当前没有公开主线程脚本 API。开发者不需要选择或调度线程,只需要按职责组织代码:

  • 组件函数只负责计算并返回组件树;
  • 点击处理、状态更新和普通业务逻辑写在事件处理函数中;
  • 请求、订阅、计时器和资源清理写在事件处理函数、Effect 或 Framework 生命周期中;
  • 拖拽、轮播等连续交互优先使用 movable-view、swiper 等专用组件,业务代码只处理确实需要的结果和回调;
  • Framework 与 UI 渲染器负责在线程之间提交并绘制视图更新,不要从底层运行时包导入线程相关 API;

状态快照、函数式更新和批处理规则见数据流与状态更新。

首次渲染

首次渲染时,两条执行路径并行工作:

  • 主线程根据构建产物尽快生成首屏,完成节点创建、布局和绘制;
  • 后台线程并行运行 React,建立用于后续状态更新的节点树;

由于两条路径并行执行,组件函数必须保持纯粹,以保证首屏结果与后台线程建立的节点树一致。

对开发者而言,“保持纯粹”可以直接按下面的边界判断:

可以写不要写应该改写到
读取当前 props、state 和 View Data在组件函数中发起请求用户主动触发的请求写在事件处理函数中;随组件同步的请求写在 useEffect 中
根据当前输入计算展示文本、样式和派生数据创建订阅、计时器或全局监听useEffect、Framework 生命周期,并在相应阶段清理
调用不修改外部状态的工具函数修改组件外变量、缓存或存储事件处理函数、Effect 或业务数据层
返回由 SDK 组件组成的 JSX在渲染过程中调用 state setter事件处理函数、Effect 或 Framework 生命周期
按 Hooks 规则调用 useState、useMemo 等 Hook读取 window、document 或操作 DOM使用 Framework 公开 API、SDK 组件及其布局事件

下面的组件计算只依赖当前输入,因此可以安全地参与首次渲染:

interface PriceSummaryProps {
  price: number;
  quantity: number;
}

function PriceSummary({ price, quantity }: PriceSummaryProps) {
  const total = price * quantity;
  return <text>合计:{total}</text>;
}

如果计算需要发起请求、订阅数据或写入外部系统,它就不再属于渲染逻辑。具体生命周期选择见生命周期与错误处理。

首屏后的更新

首屏完成后,普通交互会在主线程与后台线程之间完成三个阶段:

阶段执行线程运行过程
事件进入主线程接收用户交互,将原生事件分发到后台线程
组件更新后台线程执行事件处理和状态更新,由 React 运行时协调组件并生成视图更新
视图提交主线程接收视图更新,由 UI 渲染器完成节点更新、布局和绘制

开发者不需要手动控制这三个阶段。普通交互按下面的边界编写:

可以写不要依赖或不要写推荐写法
在点击、提交等事件处理函数中更新组件状态调用 state setter 后立即读取到新状态依赖旧状态计算新状态时使用函数式更新
在事件处理函数中发起用户触发的请求或调用公开 API请求异常会自动进入生命周期错误处理使用 try/catch 或 .catch() 显式处理异步错误
根据业务结果更新加载态、错误态和展示数据state setter 返回时布局和绘制已经完成需要布局结果时使用组件公开的 onLayout 或 onLayoutChange
在拖拽结束、轮播切换或滚动到阈值时处理业务结果为了驱动连续动画,把每次坐标变化都复制到组件 state使用 movable-view、swiper、scroll-view 或 list 的专用能力

下面是普通点击交互的推荐写法:

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

function ExpandableCard() {
  const [expanded, setExpanded] = useState(false);

  function handleToggle() {
    setExpanded(value => !value);
    // 此处只提交状态更新,不执行依赖更新后布局结果的逻辑。
  }

  return (
    <view onClick={handleToggle}>
      <text>{expanded ? '收起详情' : '展开详情'}</text>
      {expanded ? <text>详情内容</text> : null}
    </view>
  );
}

一次点击会由运行时完成“接收事件—更新组件—提交视图”。业务代码只描述事件结果,不需要感知线程切换;连续交互的组件选择见按交互类型选择执行方式。

渲染元素与组件树

豆包应用插件使用 JSX 组织组件。业务代码只能直接使用当前 SDK 已支持的内置标签,或者使用自行定义、导入的自定义组件。

  • 内置标签采用小写形式,例如 <view>、<text> 和 <image>;
  • 自定义组件采用大写形式,例如 <ProductCard>;
  • 小写只是一种标签约定,不表示任意小写名称都可用。不要直接写 <div>、<span>,也不要自行创造 <card> 等未被 SDK 声明的标签;

完整的内置标签及其属性以组件文档为准。常见 Web 元素在 SDK 中应按下表替换。

Web 元素SDK 标签用途
divview通用容器
span / 文本节点text文本承载与排版
imgimage图片展示
buttonbutton可点击操作

普通文本必须放在 <text> 中,不能在 <view> 里放裸文本,也不能使用 HTML 标签。

豆包应用插件的 UI 渲染环境没有浏览器的 document 和 window。依赖 DOM 查询、HTML 注入、浏览器布局测量或直接修改节点的 Web 库不能直接用于 Page / Widget。

选择第三方库时,先确认它只依赖纯 JavaScript。涉及 UI、网络、Storage、路由或设备能力时,使用 Framework 与应用插件已公开的组件和 API。

选择容器与内容元素

这些小写标签不仅替代 HTML 标签,还决定原生布局、滚动和资源加载方式。常用组件可以按下表选择。

需求使用组件开发约束
页面根节点Framework 生成的 page尺寸由豆包宿主创建的容器决定,不把它当作浏览器 body
普通布局容器view用于布局、背景和边框,不直接承载裸文本
文本text显式设置换行、省略和必要的字体样式
图片image设置可解析的宽高,或明确使用 autoSize
有限内容滚动scroll-view设置可解析的滚动区域尺寸和滚动方向
大量重复数据list + list-item设置列表高度,并保持 key、item-key 稳定唯一

组件确定后,需要为布局、文本、背景等设置样式时,先通过 CSS 能力清单确认属性和取值是否可用。

page 是视图树根节点,但它本身不是滚动容器。全屏长内容需要显式使用 scroll-view;数据量较大、条目持续增长或需要按需渲染时,使用 list,不要用大量 view 堆在 scroll-view 中。

list 中组件代码的执行时机,与列表项实际出现在屏幕上的时机不同:

  • 列表创建时,子组件的 JavaScript 实例可以先创建,useEffect 和普通 ref 也可能已经执行;
  • 列表项接近可视区域时,运行时才按需创建或复用实际参与布局和绘制的列表项;

因此,组件已挂载不代表列表项已经出现在屏幕上。判断曝光或可见性时,使用当前公开的列表、曝光或可见性能力。

function Feed({ items }: { items: Array<{ id: string; title: string }> }) {
  return (
    <list style={{ height: '100vh' }} scrollOrientation="vertical">
      {items.map(item => (
        <list-item key={item.id} item-key={item.id}>
          <view className="feed-item">
            <text>{item.title}</text>
          </view>
        </list-item>
      ))}
    </list>
  );
}

scroll-view 和 list 会建立独立的滚动上下文。把内容移入滚动容器后,需要重新检查 position: fixed、position: sticky、z-index 和覆盖层的表现。

图片用于参与内容布局时,优先在样式中给出确定尺寸,避免资源加载完成后才改变布局:

<image
  className="cover"
  src={coverUrl}
  mode="aspectFill"
  placeholder={placeholderUrl}
  onError={handleImageError}
/>
.cover {
  width: 120px;
  height: 80px;
  flex-shrink: 0;
}

自定义组件不会自动创建布局容器

自定义组件是对组件代码的封装。例如,使用 <Card> 不会在它返回的内容外面自动增加一层 <view>。真正参与布局和交互的是自定义组件返回的 view、text 等 SDK 内置组件。

这会带来以下影响:

  • 自定义组件本身没有独立的宽高、背景、边框、内边距或点击区域;
  • 父容器进行 Flex 等布局时,实际参与布局的是自定义组件返回的 SDK 组件;
  • 写在 <Card> 上的 className、style、id、dataset 和事件只会作为 props 传给 Card,不会自动作用到它内部的 <view>;
  • 如果自定义组件返回多个并列的 SDK 组件,这些组件会分别参与父容器布局,外面不会自动形成一个整体容器;

因此,自定义组件需要明确接收 className、事件等属性,并把它们传给内部对应的 SDK 组件:

interface CardProps {
  className?: string;
  title: string;
  onOpen(): void;
}

function Card({ className, title, onOpen }: CardProps) {
  return (
    <view className={className} onClick={onOpen}>
      <text>{title}</text>
    </view>
  );
}

function Product({ onOpen }: { onOpen(): void }) {
  return <Card className="product-card" title="商品详情" onOpen={onOpen} />;
}

示例中的样式和点击事件能够生效,是因为 Card 显式把 className 和 onOpen 传给了内部 <view>。如果只是从 props 中接收但没有继续传递,界面不会获得对应样式和交互。

使用自定义组件时注意:

  • key 是 React 保留字段,不会出现在组件 props 中。业务需要该值时,使用 itemId 等普通属性显式传递;
  • 只在确认存在重复渲染瓶颈时使用 memo、PureComponent 或稳定 props 优化,不要在没有测量依据时给所有组件增加缓存;

组件组织时遵循以下原则:

  • Page / Widget 入口只负责连接 Framework;
  • 具体视图拆成普通组件;
  • 请求、订阅、上报和宿主 API 调用放在 useEffect、生命周期或事件处理函数中;

事件与交互

组件文档列出的内置标签可以直接写在 JSX 中,不需要手动导入。事件优先使用组件声明的 React 风格属性。

这里的“React 风格属性”是指使用驼峰命名并直接传入函数,例如 onClick={handleOpen}。它只是 SDK 组件的属性约定,不表示事件对象遵循浏览器 DOM 事件模型。

使用对象事件入口示例
SDK 基础组件onClick、onTouchStart 等组件属性<view onClick={handleOpen}>
SDK 扩展组件组件文档声明的业务回调<button onClick={handleSubmit} />
Widget 模板模板 Props 中声明的业务回调items: [{ onClick: handleOpen }]
未被 SDK 封装的渲染器元素对应元素文档声明的原生事件使用前查询当前元素文档

view、text、image 等基础组件使用 onClick 等 React 风格属性。需要阻止事件继续沿渲染器事件链传播时,使用组件文档声明的 onCatchTap 等属性。

不要把事件对象当作浏览器 DOM Event,也不要假设 preventDefault() 或 stopPropagation() 在普通后台线程事件中可用。

interface ActionRowProps {
  title: string;
  onOpen(): void;
}

function ActionRow({ title, onOpen }: ActionRowProps) {
  return (
    <view className="action-row" onClick={onOpen}>
      <text>{title}</text>
    </view>
  );
}

如果元素或组件的事件名、参数结构不确定,查询当前 SDK 版本生成的组件文档;不要仅根据 Web、React Native 或通用 Lynx 示例推测。

按交互类型选择执行方式

不同交互对延迟的要求不同,按下表选择执行位置。

交互建议位置原因
点击、提交、请求普通事件处理易维护,支持异步逻辑
拖拽与缩放movable-area、movable-view由专用组件维护位置、缩放和惯性
轮播切换swiper、swiper-item由专用组件维护偏移和切换状态
滚动加载scroll-view、list 的阈值事件只在需要加载业务数据时更新状态,不复制每次滚动位置
落库、网络调用普通事件处理函数、Effect 或 Framework 生命周期显式处理成功、失败和取消,不依赖视图绘制时机

例如,实现可拖拽内容时,不需要在业务组件中为每次移动维护一份坐标 state。

function DraggableCard() {
  return (
    <movable-area style={{ width: '100%', height: '240px' }}>
      <movable-view
        direction="all"
        inertia
        style={{ width: '96px', height: '64px' }}
      >
        <text>拖动卡片</text>
      </movable-view>
    </movable-area>
  );
}

只有业务确实需要读取坐标或进行上报时,才处理 onDrag 回调;不要仅为了让同一个 movable-view 移动,再把回调坐标写回组件 state。