Image
图片

可预览的图片。

使用import { Image } from "antd";

源码components/image

文档

编辑此页更新日志

何时使用

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

代码演示

预览

基本用法

单击图像可以放大显示。

预览

容错处理

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

预览

渐进加载

大图使用 placeholder 渐进加载。

预览

多张图片预览

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

预览

相册模式

从一张图片点开相册。

预览

自定义预览图片

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

scaleStep:

受控的预览

可以使预览受控。

预览

自定义工具栏

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

预览

自定义预览内容

可以自定义预览内容。

嵌套

嵌套在弹框当中使用

API

通用属性参考：通用属性

Image

参数	说明	类型	默认值
alt	图像描述	string	-
classNames	自定义语义化结构类名	Record<SemanticDOM, string>	-
fallback	加载失败容错地址	string	-
height	图像高度	string \| number	-
placeholder	加载占位，为 `true` 时使用默认占位	ReactNode	-
preview	预览参数，为 `false` 时禁用	boolean \| PreviewType	true
src	图片地址	string	-
styles	自定义语义化结构样式	Record<SemanticDOM, string>	-
width	图像宽度	string \| number	-
onError	加载错误回调	(event: Event) => void	-

其他属性见 <img>

PreviewType

参数	说明	类型	默认值
actionsRender	自定义工具栏渲染	(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode	-
classNames	自定义语义化结构类名	Record<SemanticDOM, string>	-
closeIcon	自定义关闭 Icon	React.ReactNode	-
cover	自定义预览遮罩	React.ReactNode	-
~~destroyOnClose~~	关闭预览时销毁子元素，已移除，不再支持	boolean	false
~~forceRender~~	强制渲染预览图，已移除，不再支持	boolean	-
getContainer	指定预览挂载的节点，但依旧为全屏展示，false 为挂载在当前位置	string \| HTMLElement \| (() => HTMLElement) \| false	-
imageRender	自定义预览内容	(originalNode: React.ReactElement, info: { transform: TransformType, image: ImgInfo }) => React.ReactNode	-
~~mask~~	缩略图遮罩，请使用 `cover` 替换	ReactNode	-
~~maskClassName~~	缩略图遮罩类名，请使用 `classNames.cover` 替换	string	-
maxScale	最大缩放倍数	number	50
minScale	最小缩放倍数	number	1
movable	是否可移动	boolean	true
open	是否显示预览	boolean	-
rootClassName	预览图的根 DOM 类名，会同时作用在图片和预览层最外侧	string	-
scaleStep	`1 + scaleStep` 为缩放放大的每步倍数	number	0.5
src	自定义预览 src	string	-
styles	自定义语义化结构样式	Record<SemanticDOM, string>	-
~~toolbarRender~~	自定义工具栏，请使用 `actionsRender` 替换	(originalNode: React.ReactElement, info: Omit<ToolbarRenderInfoType, 'current' \| 'total'>) => React.ReactNode	-
~~visible~~	是否显示，请使用 `open` 替换	boolean	-
onOpenChange	预览打开状态变化的回调	(visible: boolean) => void	-
onTransform	预览图 transform 变化的回调	{ transform: TransformType, action: TransformAction }	-
~~onVisibleChange~~	当 `visible` 发生改变时的回调，请使用 `onOpenChange` 替换	(visible: boolean, prevVisible: boolean) => void	-

PreviewGroup

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

PreviewGroupType

参数	说明	类型	默认值
actionsRender	自定义工具栏渲染	(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode	-
classNames	自定义预览类名对象	Record<SemanticDOM, string>	-
closeIcon	自定义关闭 Icon	React.ReactNode	-
countRender	自定义预览计数内容	(current: number, total: number) => React.ReactNode	-
current	当前预览图的 index	number	-
~~forceRender~~	强制渲染预览图，已移除，不再支持	boolean	-
getContainer	指定预览挂载的节点，但依旧为全屏展示，false 为挂载在当前位置	string \| HTMLElement \| (() => HTMLElement) \| false	-
imageRender	自定义预览内容	(originalNode: React.ReactElement, info: { transform: TransformType, image: ImgInfo, current: number }) => React.ReactNode	-
~~mask~~	缩略图遮罩，请使用 `cover` 替换	ReactNode	-
~~maskClassName~~	缩略图遮罩类名，请使用 `classNames.cover` 替换	string	-
minScale	最小缩放倍数	number	1
maxScale	最大放大倍数	number	50
movable	是否可移动	boolean	true
open	是否显示预览	boolean	-
~~rootClassName~~	预览图的根 DOM 类名，会同时作用在图片和预览层最外侧，请使用 `classNames.root` 替换	string	-
styles	自定义语义化结构样式	Record<SemanticDOM, string>	-
scaleStep	`1 + scaleStep` 为缩放放大的每步倍数	number	0.5
~~toolbarRender~~	自定义工具栏，请使用 `actionsRender` 替换	(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode	-
~~visible~~	是否显示，请使用 `open` 替换	boolean	-
onOpenChange	预览打开状态变化回调，额外携带当前预览图索引	(visible: boolean, info: { current: number }) => void	-
onChange	切换预览图的回调	(current: number, prevCurrent: number) => void	-
onTransform	预览图 transform 变化的回调	{ transform: TransformType, action: TransformAction }	-
~~onVisibleChange~~	当 `visible` 发生改变时的回调，请使用 `onOpenChange` 替换	(visible: boolean, prevVisible: boolean, current: number) => void	-

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;
}

Semantic DOM

预览

root
根元素
image
图片元素
cover
悬浮图片显示的提示元素
popup.root
预览根元素
popup.mask
预览遮罩元素
popup.body
预览内容元素
popup.footer
预览页脚元素
popup.actions
预览操作组元素

主题变量（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如何定制？

文档贡献者

Image图片

Image图片

何时使用

代码演示

API

Image

PreviewType

PreviewGroup

PreviewGroupType

Interface

TransformType

TransformAction

ToolbarRenderInfoType

ImgInfo

Semantic DOM

root

image

cover

popup.root

popup.mask

popup.body

popup.footer

popup.actions

主题变量（Design Token）

何时使用

代码演示

API

Image

PreviewType

PreviewGroup

PreviewGroupType

Interface

TransformType

TransformAction

ToolbarRenderInfoType

ImgInfo

Semantic DOM

root

image

cover

popup.root

popup.mask

popup.body

popup.footer

popup.actions

主题变量（Design Token）

Image
图片

Image
图片