Ant Design

⌘ K

6.0.0-alpha.3

Image
图片

可预览的图片。

使用import { Image } from "antd";

反馈

components/image 提交问题待解决

文档

编辑此页

文档贡献者

Empty空状态 List列表

Ant Design

⌘ K

6.0.0-alpha.3

Image
图片

可预览的图片。

使用import { Image } from "antd";

反馈

components/image 提交问题待解决

文档

编辑此页

文档贡献者

Empty空状态 List列表

何时使用

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

代码演示

API

通用属性参考：通用属性

Image

参数	说明	类型	默认值
alt	图像描述	string	-
classNames	用于自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-
fallback	加载失败容错地址	string	-
height	图像高度	string \| number	-
placeholder	加载占位，为 `true` 时使用默认占位	ReactNode	-
preview	预览参数，为 `false` 时禁用	boolean \| PreviewType	true
src	图片地址	string	-
styles	用于自定义组件内部各语义化结构的行内 style，支持对象或函数	Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>	-
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 \| CoverConfig	-	CoverConfig v6.0 开始支持
~~destroyOnClose~~	关闭预览时销毁子元素，已移除，不再支持	boolean	false
~~forceRender~~	强制渲染预览图，已移除，不再支持	boolean	-
getContainer	指定预览挂载的节点，但依旧为全屏展示，false 为挂载在当前位置	string \| HTMLElement \| (() => HTMLElement) \| false	-
imageRender	自定义预览内容	(originalNode: React.ReactElement, info: { transform: TransformType, image: ImgInfo }) => React.ReactNode	-
mask	预览遮罩效果	boolean \| { enabled?: boolean, blur?: boolean }	true	-
~~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	预览遮罩效果	boolean \| { enabled?: boolean, blur?: boolean }	true	-
~~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;
}

CoverConfig

typescript

type CoverConfig = {
  coverNode?: React.ReactNode; // 自定义遮罩元素
  placement?: 'top' | 'bottom' | 'center'; // 设置预览遮罩显示的位置
};

Semantic DOM

root
根元素，设置相对定位和行内块布局样式
image
图片元素，设置宽度、高度和垂直对齐样式
cover
悬浮图片显示的提示元素，设置绝对定位、背景色、透明度和过渡动画样式
popup.root
预览根元素，设置固定定位、层级和背景遮罩样式
popup.mask
预览遮罩元素，设置绝对定位和半透明背景样式
popup.body
预览内容元素，设置flex布局、居中对齐和指针事件样式
popup.footer
预览页脚元素，设置绝对定位、居中布局和底部操作区域样式
popup.actions
预览操作组元素，设置flex布局、背景色、圆角和操作按钮样式

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

何时使用

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

代码演示

基本用法

单击图像可以放大显示。

容错处理

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

渐进加载

大图使用 placeholder 渐进加载。

多张图片预览

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

相册模式

从一张图片点开相册。

自定义预览图片

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

scaleStep:

受控的预览

可以使预览受控。

自定义工具栏

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

自定义预览内容

可以自定义预览内容。

Default blur

Dimmed mask

No mask

预览遮罩

遮罩效果，默认 blur。

自定义语义结构的样式和类

通过 classNames 和 styles 传入对象/函数可以自定义 Image 的语义化结构样式。

6.0.0

嵌套

嵌套在弹框当中使用

API

通用属性参考：通用属性

Image

参数	说明	类型	默认值
alt	图像描述	string	-
classNames	用于自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-
fallback	加载失败容错地址	string	-
height	图像高度	string \| number	-
placeholder	加载占位，为 `true` 时使用默认占位	ReactNode	-
preview	预览参数，为 `false` 时禁用	boolean \| PreviewType	true
src	图片地址	string	-
styles	用于自定义组件内部各语义化结构的行内 style，支持对象或函数	Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>	-
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 \| CoverConfig	-	CoverConfig v6.0 开始支持
~~destroyOnClose~~	关闭预览时销毁子元素，已移除，不再支持	boolean	false
~~forceRender~~	强制渲染预览图，已移除，不再支持	boolean	-
getContainer	指定预览挂载的节点，但依旧为全屏展示，false 为挂载在当前位置	string \| HTMLElement \| (() => HTMLElement) \| false	-
imageRender	自定义预览内容	(originalNode: React.ReactElement, info: { transform: TransformType, image: ImgInfo }) => React.ReactNode	-
mask	预览遮罩效果	boolean \| { enabled?: boolean, blur?: boolean }	true	-
~~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	预览遮罩效果	boolean \| { enabled?: boolean, blur?: boolean }	true	-
~~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;
}

CoverConfig

typescript

type CoverConfig = {
  coverNode?: React.ReactNode; // 自定义遮罩元素
  placement?: 'top' | 'bottom' | 'center'; // 设置预览遮罩显示的位置
};

Semantic DOM

root
根元素，设置相对定位和行内块布局样式
image
图片元素，设置宽度、高度和垂直对齐样式
cover
悬浮图片显示的提示元素，设置绝对定位、背景色、透明度和过渡动画样式
popup.root
预览根元素，设置固定定位、层级和背景遮罩样式
popup.mask
预览遮罩元素，设置绝对定位和半透明背景样式
popup.body
预览内容元素，设置flex布局、居中对齐和指针事件样式
popup.footer
预览页脚元素，设置绝对定位、居中布局和底部操作区域样式
popup.actions
预览操作组元素，设置flex布局、背景色、圆角和操作按钮样式

主题变量（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