图片 Image - Ant Design

何时使用

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

代码演示

预览

单击图像可以放大显示。

codeblock

预览

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

codeblock

预览

大图使用 placeholder 渐进加载。

预览

预览

多张图片预览

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

codeblock

预览

从一张图片点开相册。

codeblock

预览

自定义预览图片

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

codeblock

scaleStep:

受控的预览

可以使预览受控。

codeblock

预览

预览

自定义工具栏

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

codeblock

预览

自定义预览内容

可以自定义预览内容。

codeblock

嵌套在弹框当中使用

codeblock

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
destroyOnHidden	关闭预览时销毁子元素	boolean	false	5.25.0
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 类名，不做推荐了，v6 会移到根组件上	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

typescript

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

TransformAction

typescript

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

ToolbarRenderInfoType

typescript

{
  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

typescript

{
  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如何定制？