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/components/media/image.md.

image

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

扫码预览

扫码预览 image

Props

属性名类型默认值必填说明
autoSizebooleanfalse否是否在加载成功后自动调整图片尺寸为原图大小
classNamestring-否组件类名
flattenbooleantrue否是否扁平化元素,避免创建真实渲染对象以提升性能。

Android 上默认图片链路会受到 Fresco / OpenGL 纹理尺寸限制影响,
超过限制的图片可能按分辨率逐轮除 2 降采样。设置 flatten={false}
会走 Lynx 自定义解码链路,将默认限制替换为约 3379 x 3379
(厂商未修改时),能在一定程度上缓解大图被过度降采样的问题。
idstring-否元素的唯一标识
keystring | number | null-否React key 属性
mode"center" | "scaleToFill" | "aspectFit" | "aspectFill"'scaleToFill'否图片裁剪、缩放模式。
- scaleToFill:不保持宽高比缩放图片,使图片拉伸填满元素。
- aspectFit:保持宽高比缩放图片,使图片长边完整显示。
- aspectFill:保持宽高比缩放图片,使图片短边填满元素。
- center:不缩放图片,将图片居中显示。
onAppear(event: UIAppearanceEvent) => void-否元素曝光时的回调函数(进入可视区域)
onCatchTap(event: TouchEvent) => void-否点击时的回调函数(阻止事件冒泡)
onClick(event: TouchEvent) => void-否点击时的回调函数
onDisappear(event: UIAppearanceEvent) => void-否元素消失时的回调函数(离开可视区域)
onError(event: ErrorEvent) => void-否图片加载失败时触发,事件对象中包含错误信息
onLayoutChange(event: LayoutChangeEvent) => void-否布局变化时的回调函数
onLoad(event: LoadEvent) => void-否图片加载成功时触发,事件对象中包含图片宽高信息
onLongPress(event: TouchEvent) => void-否长按时的回调函数
onTouchEnd(event: TouchEvent) => void-否触摸结束时的回调函数
onTouchMove(event: TouchEvent) => void-否触摸移动时的回调函数
onTouchStart(event: TouchEvent) => void-否触摸开始时的回调函数
placeholderstring-否占位图地址,用法同 src
refRef<NodesRef>-否用于获取组件实例的 ref
srcstring-是图片资源地址,支持 http/https/base64
styleCSSProperties-否组件样式
subsamplebooleantrue否是否启用降采样。

仅建议在确认图片分辨率可控时设置 subsample={false}。
flatten={false} & subsample={false} 会关闭尺寸限制和降采样逻辑,
可能显著增加解码内存峰值,超大图片存在 OOM 风险。