Arco Design Image 图片组件完全指南：展示、懒加载与多图预览实战

• UI组件
• 前端
• 设计系统

Arco Design（@arco-design/web-react）的 Image 组件用于展示和预览图片，是数据展示场景中最常用的基础组件之一。本文以仓库内 Image 组件文档 为主体，结合 组件源码、演示示例 与 测试用例，系统讲解 Image 的属性体系、预览交互、多图预览、懒加载与自定义控制条等能力。读完本文，你将能独立完成单图/多图预览、渐进加载、懒加载以及个性化预览工具栏的完整落地。

一、组件定位与基础用法

Image 归属于 Arco Design 的"数据展示"组件分类（见 README.zh-CN.md 头部说明）。它的核心职责是展示图片并提供开箱即用的预览能力：只要设置src属性，点击图片即可触发预览弹层。

从源码看，Image 组件实际是一个复合组件（index.tsx），由三个子组件构成：

1.1 最简用法

参考 基础用法演示，只需设置src即可获得一个自带预览功能的图片组件：

import { Image } from '@arco-design/web-react'; function App() { return ( <Image width={200} src="//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp" alt="lamp" /> ); } export default App;

1.2 尺寸与原生属性透传

width/height可传string | number，会被直接应用到图片的宽高，同时透传到根容器与img标签上（image.tsx）。Image 的属性类型继承了Omit<ImgHTMLAttributes<HTMLImageElement>, 'className'>（interface.ts），因此原生img属性（如alt、title、onMouseEnter等）都可以直接透传。测试用例也验证了title、onLoad、onMouseEnter等原生属性的透传行为（index.test.tsx）。

二、图片信息区（Caption）与 Footer

通过title和description可以将图片的标题与描述展示在图片内部或底部，展示位置由footerPosition控制，默认值为inner（覆盖在图片上）。

参考 显示 Caption 演示：

import { Image, Space } from '@arco-design/web-react'; function App() { const src = '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp'; const title = 'A user’s avatar'; const description = 'Present by Arco Design'; return ( <Space size={60} align="start"> {/* 默认 inner：标题描述覆盖在图片内部 */} <Image width={200} src={src} title={title} description={description} alt="lamp" /> {/* outer：信息区渲染在图片底部 */} <Image width={200} src={src} title={title} description={description} footerPosition="outer" alt="lamp" /> </Space> ); }

源码机制：Footer 的显隐由 useShowFooter.ts 判定——只要title/description/actions任一存在就渲染 Footer；image-footer.tsx 负责将 caption（标题+描述）与操作按钮区组装为arco-image-footer。同时 image.tsx 会根据footerPosition追加-with-footer-inner或-with-footer-outer类名以控制布局样式。注意：Footer 仅在图片加载完成后渲染（isLoaded && showFooter）。

补充：开启simple简洁模式后，description描述将不再显示，详情见后文"额外操作"章节。

三、加载状态、错误状态与渐进加载

3.1 加载状态（loader）

默认情况下加载效果是不显示的，可通过loader={true}显示默认加载动画（旋转图标 + Loading 文字）。若默认效果不满足需求，可通过loaderClassName覆盖加载区域样式，或直接传一个 ReactNode 作为加载过渡内容。

参考 加载状态演示：

import React from 'react'; import { Image, Button, Space } from '@arco-design/web-react'; function App() { const [timestamp, setTimestamp] = React.useState(''); return ( <div> <Button type="primary" onClick={() => setTimestamp(Date.now())} style={{ marginBottom: 20 }}> reload </Button> <Space size={20}> {/* loader=true 显示默认加载效果 */} <Image width={200} height={200} src={`//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp?timestamp=${timestamp}`} loader={true} alt="lamp1" /> {/* loaderClassName 自定义加载样式（渐变扫光动画） */} <Image width={200} height={200} src={`//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp?timestamp=${timestamp}`} loaderClassName="image-demo-loader-animate" alt="lamp2" style={{ marginLeft: 67 }} /> </Space> </div> ); }

配套的扫光动画 CSS：

.image-demo-loader-animate { background: linear-gradient( -60deg, var(--color-fill-2) 25%, var(--color-neutral-3) 40%, var(--color-fill-3) 55% ); background-size: 400% 100%; animation: image-demo-loader-circle 1.5s cubic-bezier(0.34, 0.69, 0.1, 1) infinite; } @keyframes image-demo-loader-circle { 0% { background-position: 100% 50%; } 100% { background-position: 0 50%; } }

3.2 渐进加载（Progressive Loading）

大图场景可以通过给loader传一张小尺寸模糊图，在原图加载完成前先展示，从而模拟渐进加载体验。参考 渐进加载演示：

import React from 'react'; import { Image, Button } from '@arco-design/web-react'; function App() { const [timestamp, setTimestamp] = React.useState(''); return ( <div> <Button type="primary" onClick={() => setTimestamp(Date.now())} style={{ marginBottom: 20 }}> reload </Button> <Image width={200} src={`//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp?timestamp=${timestamp}`} loader={ <img width={200} src="//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp" style={{ filter: 'blur(5px)' }} /> } alt="lamp" /> </div> ); }

3.3 错误状态（error）

当图片加载失败时，默认显示一个关闭图标 +alt文本（默认错误节点见 image.tsx，alt在错误态展示的增强来自 2.3.1 版本）。可通过error属性传入自定义错误内容，也可通过onError监听失败事件。参考 错误状态演示：

import { Image, Space } from '@arco-design/web-react'; function App() { return ( <Space size={20}> <Image width={400} height={300} src="some-error.png" alt="some-error" /> {/* 长 alt 文本会在错误状态下完整展示 */} <Image width={400} height={300} src="some-error.png" alt="This is a picture of humans eating ice cream. ..." /> </Space> ); }

状态机实现：Image 的加载状态由 useImageStatus.ts 管理，完整状态包括beforeLoad（初始）、loading（加载中）、loaded（成功）、error（失败）、lazyload（视口外等待加载）。image.tsx 中img的onLoad/onError会驱动状态流转，并触发用户传入的onLoad/onError回调。测试用例通过模拟error事件断言.arco-image-error节点的出现与消失（index.test.tsx）。

四、懒加载（lazyload）

lazyload属性（v2.47.0 起）可开启懒加载：图片只有进入视口（viewport）时才真正发起请求。该属性基于IntersectionObserver API实现，类型为boolean | IntersectionObserverInit，传对象时可配置观察参数（如threshold）。

参考 懒加载演示：

import { Image, Space, Skeleton } from '@arco-design/web-react'; const imageSize = { width: 380, height: 150 }; const srcList = [ '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/volcengine-solutions-medical.png~tplv-uwbnlip3yd-png.png', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/volcengine-solutions-automotive.png~tplv-uwbnlip3yd-png.png', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/volcengine-solutions-tourism.png~tplv-uwbnlip3yd-png.png', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/volcengine-solutions-finance.png~tplv-uwbnlip3yd-png.png', ]; function App() { return ( <Space direction="vertical" size={50} className="image-demo-wrapper"> {srcList.map((src, key) => ( <Image key={key} {...imageSize} src={src} alt="lamp" lazyload={{ threshold: 0.5 }} loader={<Skeleton image={{ style: imageSize }} text={false} animation />} /> ))} </Space> ); }

源码机制：image.tsx 通过useInView（来自 components/_util/hooks/useInView.ts）监听img元素是否进入视口；懒加载开启时，src不会直接写入img标签，而是等inView为true时才动态赋值（image.tsx）。这一设计同时避免了 SSR 下开启lazyload首次渲染裂图的问题（见 变更日志 2.53.1 版本）。

五、单图预览：Image.Preview

默认情况下preview为true，点击图片即可打开预览弹层。预览弹层的所有细节配置通过previewProps（类型为Partial<ImagePreviewProps>）传入。

5.1 独立使用 Preview

Image.Preview也可以脱离 Image 单独使用：需要配置必填的src，并通过visible与onVisibleChange受控管理显隐。参考 单独使用预览组件演示：

import React from 'react'; import { Image, Button } from '@arco-design/web-react'; function App() { const [visible, setVisible] = React.useState(false); return ( <div> <Button type="primary" onClick={() => setVisible(true)}> Click me to preview image </Button> <Image.Preview src="//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp" visible={visible} onVisibleChange={setVisible} /> </div> ); }

5.2 指定挂载节点

预览弹层默认挂载到document.body，可通过getPopupContainer指定父级节点（v2.16.0 起），适合需要将预览限制在某个容器内的场景。参考 挂载节点演示：

import React from 'react'; import { Image } from '@arco-design/web-react'; const wrapperStyle = { width: '100%', height: 400, backgroundColor: 'var(--color-fill-2)', position: 'relative', overflow: 'hidden', lineHeight: '400px', textAlign: 'center', }; function App() { const ref = React.useRef(); return ( <div style={wrapperStyle} ref={ref}> <Image width={200} previewProps={{ getPopupContainer: () => ref.current, // 预览挂载到容器内部 closable: false, // 同时隐藏关闭按钮 }} src="//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp" alt="lamp" /> </div> ); }

5.3 预览交互能力一览

预览弹层内置了完整的图片操作能力（默认操作条定义见 image-preview.tsx）：

• 缩放：工具栏 + 鼠标滚轮缩放（滚轮缩放来自 2.45.2 优化）；缩放百分比按scales数组步进（默认[25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500]），若不包含100%会自动插入到最相邻位置（实现见 getScale.ts）。
• 旋转：每次旋转 90°（ROTATE_STEP = 90，image-preview.tsx），支持向左/向右。
• 全屏：按容器尺寸计算最大适配缩放比。
• 拖拽平移：按住鼠标左键拖拽移动图片；缩放与移动过程中可通过resetTranslate（v2.61.0，默认true）开启位置修正，由 getFixTranslate.ts 保证图片边缘不越出可视容器。
• 键盘快捷键（v2.55.0 起 PreviewGroup 也支持）：ESC关闭、←/→切换图片、↑/↓缩放（按键处理见 image-preview.tsx）。
• 关闭方式：点击 mask（maskClosable，默认true）、点击右上角关闭按钮（closable，默认true）、按ESC（escToExit，默认true，v2.24.0 起）。
• 窄屏适配：当预览区域宽度小于breakPoint（默认316）时，工具栏自动切换为simple紧凑模式，操作项收进下拉框。

5.4 自定义图片渲染与额外节点

v2.58.0 起，imageRender允许自定义预览中img元素的渲染（接收原始 ReactElement 返回自定义节点）；v2.39.0 起的imgAttributes可将属性透传至预览弹窗中的img标签（排除src）；v2.53.0 起的extra可在预览区域追加自定义节点。

六、多图预览：Image.PreviewGroup

Image.PreviewGroup从 v2.14.0 开始支持，用于多图预览。预览弹层内提供左右切换箭头与图片序号，切换时默认重置缩放/旋转/位移状态。

6.1 包裹式用法

用<Image.PreviewGroup>包裹一组<Image>组件即可。参考 多图预览演示：

import { Image, Space } from '@arco-design/web-react'; function App() { const srcList = [ '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/e278888093bef8910e829486fb45dd69.png~tplv-uwbnlip3yd-webp.webp', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/3ee5f13fb09879ecb5185e440cef6eb9.png~tplv-uwbnlip3yd-webp.webp', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/8361eeb82904210b4f55fab888fe8416.png~tplv-uwbnlip3yd-webp.webp', ]; return ( <div> <Space direction="vertical"> {/* infinite：首尾循环切换 */} <Image.PreviewGroup infinite> <Space> {srcList.map((src, index) => ( <Image key={index} src={src} width={200} alt={`lamp${index + 1}`} /> ))} </Space> </Image.PreviewGroup> </Space> </div> ); }

源码机制：PreviewGroup 通过 previewGroupContext.ts 向子 Image 提供注册能力。子 Image 挂载时调用registerPreviewUrl(id, src, preview)收集图片地址、registerPreviewProps(id, previewProps)收集各自的预览配置（image.tsx）；PreviewGroup 内部用loopImageIndex递归遍历子节点、按出现顺序自动分配_index（image-preview-group.tsx）。点击任意子图片时，会先setCurrentIndex(id)再打开预览（image.tsx）。

6.2 srcList 直传模式与独立使用

Image.PreviewGroup也可以单独使用：通过srcList直接传入图片地址数组（一旦设置srcList，将不再收集子 Image 组件的信息），并通过visible/onVisibleChange控制显隐。展示起始图有两种方式：

• 非受控：defaultCurrent指定第一张展示的图片下标；
• 受控：current+onChange控制当前展示下标。

参考 单独使用多图预览组件演示：

import React from 'react'; import { Image, Button } from '@arco-design/web-react'; function App() { const [visible, setVisible] = React.useState(false); const srcList = [ '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/e278888093bef8910e829486fb45dd69.png~tplv-uwbnlip3yd-webp.webp', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/3ee5f13fb09879ecb5185e440cef6eb9.png~tplv-uwbnlip3yd-webp.webp', '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/8361eeb82904210b4f55fab888fe8416.png~tplv-uwbnlip3yd-webp.webp', ]; return ( <div> <Button type="primary" onClick={() => setVisible(true)}> Click me to preview multiple image </Button> <Image.PreviewGroup srcList={srcList} visible={visible} onVisibleChange={setVisible} /> </div> ); }

6.3 预览顺序修正与预加载

• index（v2.23.0 起）：在复杂嵌套结构下，若多图预览顺序异常，可对单个Image手动指定预览序号。源码中index/_index会直接作为注册 id 使用（image.tsx）。
• forceRender（v2.58.0 起）：是否渲染图片列表用于提前加载图片。实现中会将收集到的可预览地址渲染进一个display: none的隐藏容器内触发预加载（image-preview-group.tsx）。
• infinite：是否无限循环切换，关闭后首尾箭头会自动禁用（见 image-preview-arrow.tsx）。

七、自定义预览控制条：actions 与 actionsLayout

预览弹层底部默认控制条包含：全屏、右旋、左旋、放大、缩小、原始尺寸（依次对应fullScreen/rotateRight/rotateLeft/zoomIn/zoomOut/originalSize）。通过actionsLayout可以调整顺序、过滤按钮（只有出现在actionsLayout中的按钮才会展示），其中extra占位符代表actions中传入的自定义操作按钮；actions中的key也可以单独放入actionsLayout参与排序。

参考 自定义预览控制条演示：

import { Image, Tooltip, Space } from '@arco-design/web-react'; import { IconDownload, IconInfoCircle } from '@arco-design/web-react/icon'; function App() { return ( <Image width={200} src="//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp" previewProps={{ actions: [ { key: 'download', content: <IconDownload />, name: 'Download', }, { key: 'info', content: <IconInfoCircle />, name: 'Info', getContainer: (action) => { return <Tooltip content="A user’s avatar">{action}</Tooltip>; }, }, ], // info 自定义按钮排在最前，未列出的 fullScreen/originalSize 等被过滤 actionsLayout: ['info', 'rotateRight', 'zoomIn', 'zoomOut', 'extra'], }} alt="lamp" /> ); }

排序与过滤的实现（image-preview-toolbar.tsx）：先按actionsLayout的 key 集合过滤默认按钮与自定义按钮，再按其在actionsLayout中的下标排序；如果布局中包含extra，自定义 actions 中未被显式列出的按钮会整体插入extra所在位置。

ImagePreviewActionProps 说明

自定义操作项类型ImagePreviewActionProps的字段：

完整定义见 interface.ts。

八、图片底部额外操作：actions 与 simple 模式

图片本身（非预览弹层）也支持在底部信息区添加操作按钮，通过actions（类型ReactNode[]）设置，默认水平排列。当操作按钮较多时，可开启simple简洁模式把按钮收入下拉框中——但在simple模式下，描述description将不显示。

参考 额外操作演示：

import React from 'react'; import { Image, Tooltip, Space } from '@arco-design/web-react'; import { IconEye, IconDownload, IconInfoCircle } from '@arco-design/web-react/icon'; function DemoImage(props) { const [visible, setVisible] = React.useState(false); return ( <Image src="//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp" title="A user’s avatar" description="Present by Arco Design" actions={[ <button key="1" className="image-demo-action-item" onClick={(e) => setVisible(true)}> <IconEye /> </button>, <button key="2" className="image-demo-action-item" onClick={(e) => console.log('download')}> <IconDownload /> </button>, <Tooltip key="3" content="A user’s avatar"> <button className="image-demo-action-item"> <IconInfoCircle /> </button> </Tooltip>, ]} previewProps={{ visible, onVisibleChange: (e) => setVisible(false), }} {...props} /> ); } function App() { return ( <div> <Space size={20} align="start"> <DemoImage width={300} alt="lamp1" /> {/* simple 模式：操作按钮收进下拉框 */} <DemoImage width={200} simple={true} alt="lamp2" style={{ verticalAlign: 'top' }} /> </Space> </div> ); }

源码机制：actions的渲染位于 image-footer.tsx。默认模式下按钮逐个水平排列；simple模式下通过TriggerForToolbar（基于 Trigger 组件）包装为下拉触发。测试用例验证了.arco-image-actions-item的渲染及按钮点击回调（index.test.tsx）。

九、完整 API 参数参考

以下参数表完整摘录自 Image 组件文档，与 interface.ts 类型定义一一对应。

9.1 Image

9.2 Image.Preview

9.3 Image.PreviewGroup

从 v2.14.0 开始支持。除下列专属参数外，PreviewGroup 还继承了 Preview 的全部配置项（closable、escToExit、maskClosable、resetTranslate、breakPoint、imgAttributes、extra、actions、actionsLayout、scales、getPopupContainer、imageRender等，见 README.zh-CN.md）。

十、版本演进与已知行为提示

结合 Image 组件变更日志，使用时有几点值得留意：

• 关闭按钮冒泡（2.66.15）：Image.Preview关闭按钮的 click 事件已做stopPropagation处理，避免误触父元素 click。
• 缓存加载（2.61.0 / 2.29.1）：图片命中浏览器内存缓存时曾出现一直 loading 的问题，已修复；若依赖onLoad做业务处理，可留意这一历史行为。
• previewProps 动态更新（2.48.1）：previewProps字段更新后 UI 不刷新的 bug 已修复，受控场景可放心使用。
• SSR 兼容（2.15.0 / 2.53.1）：组件支持服务端渲染；开启lazyload时首帧裂图问题已修复。
• 键盘方向键（2.55.0）：PreviewGroup 支持←/→切换图片，↑/↓缩放。
• 未传 src（2.52.1）：避免控制台 404 报错，未传src时不会渲染src属性。

结语

Arco Design 的 Image 组件从"展示图片"这一基础诉求出发，提供了完整的加载/错误/懒加载状态管理，以及可深度定制的单图与多图预览交互。日常使用中只需记住几个关键组合：src+previewProps完成单图预览定制，Image.PreviewGroup+srcList（或子 Image 收集）完成多图预览，loader+lazyload优化大图列表页体验，actionsLayout+actions重塑预览控制条。更多交互细节可继续阅读仓库中的 12 个官方演示 与 测试用例 验证具体行为。

• UI组件
• 前端
• 设计系统