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

# image

图片展示组件，支持加载本地或网络图片资源，提供多种裁剪和缩放模式。

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

## 扫码预览

![扫码预览 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%252Fimage%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>autoSize</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否在加载成功后自动调整图片尺寸为原图大小</td></tr>
<tr><td>className</td><td><code>string</code></td><td>-</td><td>否</td><td>组件类名</td></tr>
<tr><td>flatten</td><td><code>boolean</code></td><td>true</td><td>否</td><td>是否扁平化元素，避免创建真实渲染对象以提升性能。<br><br>Android 上默认图片链路会受到 Fresco / OpenGL 纹理尺寸限制影响，<br>超过限制的图片可能按分辨率逐轮除 2 降采样。设置 <code>flatten={false}</code><br>会走 Lynx 自定义解码链路，将默认限制替换为约 3379 x 3379<br>（厂商未修改时），能在一定程度上缓解大图被过度降采样的问题。</td></tr>
<tr><td>id</td><td><code>string</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>mode</td><td><code>&quot;center&quot; | &quot;scaleToFill&quot; | &quot;aspectFit&quot; | &quot;aspectFill&quot;</code></td><td>'scaleToFill'</td><td>否</td><td>图片裁剪、缩放模式。<br>- <code>scaleToFill</code>：不保持宽高比缩放图片，使图片拉伸填满元素。<br>- <code>aspectFit</code>：保持宽高比缩放图片，使图片长边完整显示。<br>- <code>aspectFill</code>：保持宽高比缩放图片，使图片短边填满元素。<br>- <code>center</code>：不缩放图片，将图片居中显示。</td></tr>
<tr><td>onAppear</td><td><code>(event: UIAppearanceEvent) =&gt; void</code></td><td>-</td><td>否</td><td>元素曝光时的回调函数（进入可视区域）</td></tr>
<tr><td>onCatchTap</td><td><code>(event: TouchEvent) =&gt; void</code></td><td>-</td><td>否</td><td>点击时的回调函数（阻止事件冒泡）</td></tr>
<tr><td>onClick</td><td><code>(event: TouchEvent) =&gt; void</code></td><td>-</td><td>否</td><td>点击时的回调函数</td></tr>
<tr><td>onDisappear</td><td><code>(event: UIAppearanceEvent) =&gt; void</code></td><td>-</td><td>否</td><td>元素消失时的回调函数（离开可视区域）</td></tr>
<tr><td>onError</td><td><code>(event: ErrorEvent) =&gt; void</code></td><td>-</td><td>否</td><td>图片加载失败时触发，事件对象中包含错误信息</td></tr>
<tr><td>onLayoutChange</td><td><code>(event: LayoutChangeEvent) =&gt; void</code></td><td>-</td><td>否</td><td>布局变化时的回调函数</td></tr>
<tr><td>onLoad</td><td><code>(event: LoadEvent) =&gt; void</code></td><td>-</td><td>否</td><td>图片加载成功时触发，事件对象中包含图片宽高信息</td></tr>
<tr><td>onLongPress</td><td><code>(event: TouchEvent) =&gt; void</code></td><td>-</td><td>否</td><td>长按时的回调函数</td></tr>
<tr><td>onTouchEnd</td><td><code>(event: TouchEvent) =&gt; void</code></td><td>-</td><td>否</td><td>触摸结束时的回调函数</td></tr>
<tr><td>onTouchMove</td><td><code>(event: TouchEvent) =&gt; void</code></td><td>-</td><td>否</td><td>触摸移动时的回调函数</td></tr>
<tr><td>onTouchStart</td><td><code>(event: TouchEvent) =&gt; void</code></td><td>-</td><td>否</td><td>触摸开始时的回调函数</td></tr>
<tr><td>placeholder</td><td><code>string</code></td><td>-</td><td>否</td><td>占位图地址，用法同 src</td></tr>
<tr><td>ref</td><td><code>Ref&lt;NodesRef&gt;</code></td><td>-</td><td>否</td><td>用于获取组件实例的 ref</td></tr>
<tr><td>src</td><td><code>string</code></td><td>-</td><td>是</td><td>图片资源地址，支持 http/https/base64</td></tr>
<tr><td>style</td><td><code>CSSProperties</code></td><td>-</td><td>否</td><td>组件样式</td></tr>
<tr><td>subsample</td><td><code>boolean</code></td><td>true</td><td>否</td><td>是否启用降采样。<br><br>仅建议在确认图片分辨率可控时设置 <code>subsample={false}</code>。<br><code>flatten={false} &amp; subsample={false}</code> 会关闭尺寸限制和降采样逻辑，<br>可能显著增加解码内存峰值，超大图片存在 OOM 风险。</td></tr>
</tbody>
</table>
