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

# 视图渲染与交互

豆包应用插件使用 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；

状态快照、函数式更新和批处理规则见[数据流与状态更新](/apps-plugin/docs/client-framework/data-flow.md)。

### 首次渲染

首次渲染时，两条执行路径并行工作：

- 主线程根据构建产物尽快生成首屏，完成节点创建、布局和绘制；
- 后台线程并行运行 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 组件及其布局事件            |

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

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

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

如果计算需要发起请求、订阅数据或写入外部系统，它就不再属于渲染逻辑。具体生命周期选择见[生命周期与错误处理](/apps-plugin/docs/client-framework/lifecycle.md)。

### 首屏后的更新

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

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

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

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

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

```tsx
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 标签   | 用途      |
| ------------- | -------- | ------- |
| `div`         | `view`   | 通用容器    |
| `span` / 文本节点 | `text`   | 文本承载与排版 |
| `img`         | `image`  | 图片展示    |
| `button`      | `button` | 可点击操作   |

普通文本必须放在 `<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 能力清单](/apps-plugin/docs/client-framework/css-capabilities.md)确认属性和取值是否可用。

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

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

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

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

```tsx
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` 和覆盖层的表现。

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

```tsx
<image
  className="cover"
  src={coverUrl}
  mode="aspectFill"
  placeholder={placeholderUrl}
  onError={handleImageError}
/>
```

```scss
.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 组件：

```tsx
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()` 在普通后台线程事件中可用。

```tsx
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。

```tsx
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。
