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

# list

高性能列表组件，适用于渲染大量数据，支持垂直滚动和按需渲染。

<iframe src="https://developer.doubao.com/docs-preview/component-simulator/?caseId=list"
  title="组件示例 list"
  width="100%"
  height="700"
  loading="lazy"
  style="width:100%;height:700px;border:0;border-radius:16px;overflow:hidden;"
></iframe>

## 扫码预览

![扫码预览 list](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fcomponent%252Flist%252Findex)

## Props

<table>
<thead>
<tr><th width="140">属性名</th><th width="240">类型</th><th width="120">默认值</th><th width="80">必填</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>bounces</td><td><code>boolean</code></td><td>true</td><td>否</td><td>是否启用弹性效果（iOS 回弹效果）</td></tr>
<tr><td>children</td><td><code>ReactNode</code></td><td>-</td><td>否</td><td>子元素</td></tr>
<tr><td>className</td><td><code>string</code></td><td>-</td><td>否</td><td>组件类名</td></tr>
<tr><td>enableNestedScroll</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否支持嵌套滚动</td></tr>
<tr><td>enableScroll</td><td><code>boolean</code></td><td>true</td><td>否</td><td>是否允许滚动</td></tr>
<tr><td>experimentalRecycleStickyItem</td><td><code>boolean</code></td><td>-</td><td>否</td><td>是否回收吸顶元素</td></tr>
<tr><td>id</td><td><code>string</code></td><td>-</td><td>否</td><td>元素的唯一标识</td></tr>
<tr><td>initialScrollIndex</td><td><code>number</code></td><td>0</td><td>否</td><td>列表渲染后自动滚动到的节点位置</td></tr>
<tr><td>itemSnap</td><td><code>ListItemSnapAlignment</code></td><td>-</td><td>否</td><td>启用分页效果</td></tr>
<tr><td>key</td><td><code>string | number | null</code></td><td>-</td><td>否</td><td>React key 属性</td></tr>
<tr><td>layoutId</td><td><code>number</code></td><td>-1</td><td>否</td><td>数据源更新的唯一标识，会在 layoutcomplete 事件中返回</td></tr>
<tr><td>listType</td><td><code>&quot;single&quot; | &quot;flow&quot; | &quot;waterfall&quot;</code></td><td>'single'</td><td>否</td><td>列表的布局类型</td></tr>
<tr><td>lowerThresholdItemCount</td><td><code>number</code></td><td>0</td><td>否</td><td>触发滚动到底部的剩余子节点数量阈值</td></tr>
<tr><td>needLayoutCompleteInfo</td><td><code>boolean</code></td><td>false</td><td>否</td><td>layoutcomplete 事件是否包含布局信息</td></tr>
<tr><td>needVisibleItemInfo</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否在滚动事件回调参数中包含当前渲染节点的位置信息</td></tr>
<tr><td>onLayoutComplete</td><td><code>(event: ListLayoutCompleteEvent) =&gt; void</code></td><td>-</td><td>否</td><td>首屏渲染完成时触发</td></tr>
<tr><td>onScroll</td><td><code>(event: ListScrollEvent) =&gt; void</code></td><td>-</td><td>否</td><td>滚动事件</td></tr>
<tr><td>onScrollStateChange</td><td><code>(event: ListScrollStateChangeEvent) =&gt; void</code></td><td>-</td><td>否</td><td>滚动状态变化时触发</td></tr>
<tr><td>onScrollToLower</td><td><code>(event: ListScrollToLowerEvent) =&gt; void</code></td><td>-</td><td>否</td><td>滚动到底部时触发</td></tr>
<tr><td>onScrollToUpper</td><td><code>(event: ListScrollToUpperEvent) =&gt; void</code></td><td>-</td><td>否</td><td>滚动到顶部时触发</td></tr>
<tr><td>onSnap</td><td><code>(event: ListSnapEvent) =&gt; void</code></td><td>-</td><td>否</td><td>分页滚动回调</td></tr>
<tr><td>preloadBufferCount</td><td><code>number</code></td><td>0</td><td>否</td><td>列表外预加载的节点数量</td></tr>
<tr><td>ref</td><td><code>Ref&lt;NodesRef&gt;</code></td><td>-</td><td>否</td><td>用于获取组件实例的 ref</td></tr>
<tr><td>scrollBarEnable</td><td><code>boolean</code></td><td>-</td><td>否</td><td>是否显示滚动条</td></tr>
<tr><td>scrollEventThrottle</td><td><code>number</code></td><td>200</td><td>否</td><td>滚动事件的回调频率（ms）</td></tr>
<tr><td>scrollOrientation</td><td><code>&quot;horizontal&quot; | &quot;vertical&quot;</code></td><td>'vertical'</td><td>否</td><td>滚动方向和布局方向</td></tr>
<tr><td>spanCount</td><td><code>number</code></td><td>1</td><td>否</td><td>列表的列数或行数，仅当 listType 为 'flow' 或 'waterfall' 时有效</td></tr>
<tr><td>sticky</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否允许列表整体吸顶或吸底</td></tr>
<tr><td>stickyOffset</td><td><code>number</code></td><td>0</td><td>否</td><td>吸顶或吸底时的偏移距离（px）</td></tr>
<tr><td>style</td><td><code>CSSProperties</code></td><td>-</td><td>否</td><td>组件样式</td></tr>
<tr><td>upperThresholdItemCount</td><td><code>number</code></td><td>0</td><td>否</td><td>触发滚动到顶部的剩余子节点数量阈值</td></tr>
</tbody>
</table>
