图片 Image - Ant Design

何时使用

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

代码演示

预览

单击图像可以放大显示。

预览

加载失败显示图像占位符。

预览

大图使用 placeholder 渐进加载。

预览

预览

多张图片预览

点击左右切换按钮可以预览多张图片。

预览

从一张图片点开相册。

预览

自定义预览图片

可以设置不同的预览图片。

scaleStep:

受控的预览

可以使预览受控。

预览

预览

自定义工具栏

可以自定义工具栏并添加下载原图或翻转旋转后图片的按钮。

预览

自定义预览内容

可以自定义预览内容。

示例

自定义预览文本

自定义预览文本。

嵌套在弹框当中使用

预览

预览

预览

多图预览时顶部进度自定义

多图预览时顶部展示进度, 支持自定义

预览

预览

自定义组件 Token

自定义组件 Token。

test

预览

在渲染函数中获取图片信息

在渲染函数中获取图片的信息。

API

通用属性参考：通用属性

Image

参数	说明	类型	默认值	版本
alt	图像描述	string	-	4.6.0
fallback	加载失败容错地址	string	-	4.6.0
height	图像高度	string \| number	-	4.6.0
placeholder	加载占位，为 `true` 时使用默认占位	ReactNode	-	4.6.0
preview	预览参数，为 `false` 时禁用	boolean \| PreviewType	true	4.6.0 PreviewType:4.7.0
src	图片地址	string	-	4.6.0
width	图像宽度	string \| number	-	4.6.0
onError	加载错误回调	(event: Event) => void	-	4.12.0

其他属性见 <img>

PreviewType

参数	说明	类型	默认值	版本
visible	是否显示	boolean	-	-
src	自定义预览 src	string	-	4.10.0
getContainer	指定预览挂载的节点，但依旧为全屏展示，false 为挂载在当前位置	string \| HTMLElement \| (() => HTMLElement) \| false	-	4.8.0
movable	是否可移动	boolean	true	5.8.0
mask	缩略图遮罩	ReactNode	-	4.9.0
maskClassName	缩略图遮罩类名	string	-	4.11.0
rootClassName	预览图的根 DOM 类名	string	-	5.4.0
scaleStep	`1 + scaleStep` 为缩放放大的每步倍数	number	0.5	-
minScale	最小缩放倍数	number	1	5.7.0
maxScale	最大放大倍数	number	50	5.7.0
closeIcon	自定义关闭 Icon	React.ReactNode	-	5.7.0
forceRender	强制渲染预览图	boolean	-	-
toolbarRender	自定义工具栏	(originalNode: React.ReactElement, info: Omit<ToolbarRenderInfoType, 'current' \| 'total'>) => React.ReactNode	-	5.7.0, `info.image`: 5.18.0
imageRender	自定义预览内容	(originalNode: React.ReactElement, info: { transform: TransformType, image: ImgInfo }) => React.ReactNode	-	5.7.0, image: 5.18.0
destroyOnClose	关闭预览时销毁子元素	boolean	false
onTransform	预览图 transform 变化的回调	{ transform: TransformType, action: TransformAction }	-	5.7.0
onVisibleChange	当 `visible` 发生改变时的回调	(visible: boolean, prevVisible: boolean) => void	-	-

PreviewGroup

参数	说明	类型	默认值	版本
preview	预览参数，为 `false` 时禁用	boolean \| PreviewGroupType	true	4.6.0 PreviewGroupType:4.7.0
items	预览数组	string[] \| { src: string, crossOrigin: string, ... }[]	-	5.7.0
fallback	加载失败容错地址	string	-	5.7.0

PreviewGroupType

参数	说明	类型	默认值	版本
visible	是否显示	boolean	-	-
getContainer	指定预览挂载的节点，但依旧为全屏展示，false 为挂载在当前位置	string \| HTMLElement \| (() => HTMLElement) \| false	-	4.8.0
movable	是否可移动	boolean	true	5.8.0
current	当前预览图的 index	number	-	4.12.0
mask	缩略图遮罩	ReactNode	-	4.9.0
maskClassName	缩略图遮罩类名	string	-	4.11.0
rootClassName	预览图的根 DOM 类名	string	-	5.4.0
scaleStep	`1 + scaleStep` 为缩放放大的每步倍数	number	0.5	-
minScale	最小缩放倍数	number	1	5.7.0
maxScale	最大放大倍数	number	50	5.7.0
closeIcon	自定义关闭 Icon	React.ReactNode	-	5.7.0
forceRender	强制渲染预览图	boolean	-	-
countRender	自定义预览计数内容	(current: number, total: number) => React.ReactNode	-	4.20.0
toolbarRender	自定义工具栏	(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode	-	5.7.0, `info.image`: 5.18.0
imageRender	自定义预览内容	(originalNode: React.ReactElement, info: { transform: TransformType, image: ImgInfo, current: number }) => React.ReactNode	-	5.7.0, image: 5.18.0
onTransform	预览图 transform 变化的回调	{ transform: TransformType, action: TransformAction }	-	5.7.0
onChange	切换预览图的回调	(current: number, prevCurrent: number) => void	-	5.3.0
onVisibleChange	当 `visible` 发生改变时的回调	(visible: boolean, prevVisible: boolean, current: number) => void	-	current 参数 5.3.0

Interface

TransformType

{
  x: number;
  y: number;
  rotate: number;
  scale: number;
  flipX: boolean;
  flipY: boolean;
}

TransformAction

type TransformAction =
  | 'flipY'
  | 'flipX'
  | 'rotateLeft'
  | 'rotateRight'
  | 'zoomIn'
  | 'zoomOut'
  | 'close'
  | 'prev'
  | 'next'
  | 'wheel'
  | 'doubleClick'
  | 'move'
  | 'dragRebound'
  | 'reset';

ToolbarRenderInfoType

{
  icons: {
    flipYIcon: React.ReactNode;
    flipXIcon: React.ReactNode;
    rotateLeftIcon: React.ReactNode;
    rotateRightIcon: React.ReactNode;
    zoomOutIcon: React.ReactNode;
    zoomInIcon: React.ReactNode;
  };
  actions: {
    onActive?: (index: number) => void; // 5.21.0 之后支持
    onFlipY: () => void;
    onFlipX: () => void;
    onRotateLeft: () => void;
    onRotateRight: () => void;
    onZoomOut: () => void;
    onZoomIn: () => void;
    onReset: () => void; // 5.17.3 之后支持
    onClose: () => void;
  };
  transform: TransformType,
  current: number;
  total: number;
  image: ImgInfo
}

ImgInfo

{
  url: string;
  alt: string;
  width: string | number;
  height: string | number;
}

主题变量（Design Token）

组件 Token如何定制？

Token 名称	描述	类型	默认值
previewOperationColor	预览操作图标颜色	string	rgba(255, 255, 255, 0.65)
previewOperationColorDisabled	预览操作图标禁用颜色	string	rgba(255, 255, 255, 0.25)
previewOperationHoverColor	预览操作图标悬浮颜色	string	rgba(255, 255, 255, 0.85)
previewOperationSize	预览操作图标大小	number	18
zIndexPopup	预览浮层 z-index	number	1080

全局 Token如何定制？