图片 Image

可预览的图片。

安装

npm install antd-mobile@5.43.0

antd-mobile 是移动网页组件库，不是 React Native 或小程序组件。React 19 项目需在入口用 unstableSetRender 注册 createRoot，否则 Toast、Dialog 等命令式 API 无法渲染；深色模式通过 <html data-prefers-color-scheme="dark"> 切换。

示例来自 Ant Design Mobile 官方仓库（MIT），固定在 npm 5.43.0 对应的提交；示例中的 DemoBlock 等展示辅助组件由 JGuang 重写，不属于 antd-mobile 的 API。

可预览的图片。

何时使用

需要展示图片时使用。
加载大图时显示 loading 或加载失败时容错处理。

示例

Image

属性

属性	说明	类型	默认值
alt	图片描述	`string`	-
draggable	是否允许用户拖拽图片	`boolean`	`false`
fallback	加载失败的占位	`ReactNode`	默认占位
fit	图片填充模式	`'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'`	`'fill'`
height	图片高度，如果传入数字则单位为 `px`	`string \| number`	-
lazy	是否懒加载图片	`boolean`	`false`
onClick	图片点击事件	`(event: React.MouseEvent<HTMLImageElement, Event>) => void`	-
onContainerClick	容器点击事件	`(event: React.MouseEvent<HTMLDivElement, Event>) => void`	-
onError	加载失败时触发	`(event: React.SyntheticEvent<HTMLImageElement, Event>) => void`	-
onLoad	图片加载完时触发	`(event: React.SyntheticEvent<HTMLImageElement, Event>) => void`	-
placeholder	加载时的占位	`ReactNode`	默认占位
src	图片地址	`string`	-
width	图片宽度，如果传入数字则单位为 `px`	`string \| number`	-

此外，还支持以下 HTML 原生属性：crossOrigin、decoding、loading、referrerPolicy、sizes、srcSet、useMap

width height 属性其实和 CSS 变量 --width --height 并不冲突，这些组件属性其实就是基于 CSS 变量实现的，只是 CSS 变量的一种快捷设置方式。

CSS 变量

属性	说明	默认值	全局变量
--height	图片高度	`auto`	`--adm-image-height`
--width	图片宽度	`auto`	`--adm-image-width`

FAQ

如何让 Image 从 block 元素变为 inline-block 元素？

Image 默认是渲染为 block 元素的，如果你需要让它变为 inline-block 元素的话，可以在外层嵌套一层 inline-block 的容器，例如：

<div style={{ display: 'inline-block' }}>
  <Image />
</div>

`onContainerClick` 和 `onClick` 有什么区别？

onContainerClick 是容器点击事件，而 onClick 是图片点击事件。在图片加载成功之前或图片加载失败后，onClick 是不会触发的，但 onContainerClick 是可以正常触发的。

图片