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

# long-image

长图加载与展示组件，支持分段懒加载，适用于超长图片的高性能渲染。

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

## 扫码预览

![扫码预览 long-image](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fcomponent%252Flong-image%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>className</td><td><code>string</code></td><td>-</td><td>否</td><td>组件类名。</td></tr>
<tr><td>decodeOverscanScreens</td><td><code>number</code></td><td>1</td><td>否</td><td>解码窗口的预加载屏数，基于当前可视区域高度计算。</td></tr>
<tr><td>id</td><td><code>string</code></td><td>-</td><td>否</td><td>元素唯一标识。未传时内部自动生成。</td></tr>
<tr><td>maxActiveSegments</td><td><code>number</code></td><td>8</td><td>否</td><td>解码窗口允许同时激活的最大分段数。<br>用于控制单次内存峰值。</td></tr>
<tr><td>onMetricsChange</td><td><code>(metrics: LongImageMetrics) =&gt; void</code></td><td>-</td><td>否</td><td>指标回调，输出尺寸和当前激活窗口信息。</td></tr>
<tr><td>onStateChange</td><td><code>(state: LongImageState) =&gt; void</code></td><td>-</td><td>否</td><td>状态回调，输出阶段与错误信息。</td></tr>
<tr><td>placeholderColor</td><td><code>string</code></td><td>'transparent'</td><td>否</td><td>非激活分段或分段图片加载失败时的占位背景色。</td></tr>
<tr><td>reloadToken</td><td><code>number</code></td><td>0</td><td>否</td><td>手动重建分段与解码窗口的触发令牌。值变化时会重新初始化。</td></tr>
<tr><td>scrollEventThrottle</td><td><code>number</code></td><td>60</td><td>否</td><td>滚动事件回调节流时间（ms）。</td></tr>
<tr><td>segmentDisplayHeight</td><td><code>number</code></td><td>600</td><td>否</td><td>单段在展示坐标系下的目标高度（px）。<br>值越大，单次解码像素越大；值越小，分段数量越多。</td></tr>
<tr><td>src</td><td><code>string</code></td><td>-</td><td>是</td><td>图片资源地址。</td></tr>
<tr><td>style</td><td><code>CSSProperties</code></td><td>-</td><td>否</td><td>组件样式。<br>- <code>style.height</code>：建议显式指定；未指定时默认使用 <code>100vh</code>。<br>- <code>style.width</code>：未指定时默认使用 <code>100%</code>。</td></tr>
</tbody>
</table>
