# 图片 Image

- 页面: https://jiguang132.com/zh/resources/arco-design/docs/image
- 资源: Arco Design (https://jiguang132.com/zh/resources/arco-design.md)
- 全部指南: https://jiguang132.com/zh/resources/arco-design/docs.md

展示和预览图片。

## 安装

```bash
npm install @arco-design/web-react@2.66.18
```

在入口引入 `@arco-design/web-react/dist/css/arco.css`，用 `ConfigProvider` 设置语言。React 19 项目还需在入口最先引入 `@arco-design/web-react/es/_util/react-19-adapter`，否则 Message、Modal 等命令式 API 无法渲染。

## 示例

- **基础用法**：需要查看图片的时候，简单的设置 `src` 属性，就能获得一个有预览图片功能的组件。
- **显示 Caption**：通过设置 `title` 和 `description` 可以将图片的标题和描述显示在图片内部或者底部，显示的位置通过 `footerPosition` 控制。
- **额外操作**：额外操作通过 `actions` 设置，默认情况下水平排列，如果您的操作按钮比较多，我们也提供了 `simple` 模式将按钮收入一个下拉框中，但是需要注意的是在 `simple` 模式下，描述将不显示。
- **错误状态**：当加载图片失败的时候显示的内容。
- **加载状态**：默认情况下，加载效果是不显示的，可通过设置 `loader=true` 显示默认加载效果。如果默认加载效果不符合需求。还可以通过 `loaderClassName` 自行设置加载样式。
- **渐进加载**：大图可通过给 `loader` 传递一个小一些的图片，让其在原图未被加载成功时显示，以此来模拟渐进加载。
- **自定义预览控制条**：通过设置 `actionsLayout` 可以调整预览控制条中功能按钮的顺序，同时可以过滤功能按钮，只有在 actionsLayout 中的按钮才会出现。其中 `extra` 代表 `actions` 中的按钮，而且 `actions` 中的 `key` 也支持单独拿出来排序。
- **多图预览**：用 `<Image.PreviewGroup>` 包裹 `<Image>` 组件即可进行多图预览。
- **单独使用预览组件**：`Image.Preview` 可单独使用，需要配置 `src`，并控制 `visible`。
- **单独使用多图预览组件**：`Image.PreviewGroup` 可单独使用，需通过 `visible` 和 `onVisibleChange` 控制显隐。在图片的展示上分为两种场景，一是通过 `defaultCurrent` 指定第一张展示的图片；二是通过 `current` 和 `onChange` 以受控的方式控制当前显示的是第几张图片。
- **挂载节点**：可以通过 `getPopupContainer` 指定预览挂载的父级节点。
- **懒加载**：设置 `lazyload` 可以开启懒加载，当图片出现在视口才会进行加载。`lazyload` 属性基于 **[IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)** 实现

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

## API

<div class="image-demo-props">

### Image

|参数名|描述|类型|默认值|版本|
|---|---|---|---|---|
|preview|是否开启预览|boolean |`true`|-|
|simple|是否开启简洁模式|boolean |`-`|-|
|index|使用 `Image.PreviewGroup`包裹时的预览索引，一般不用指定，当多图预览顺序出现问题时，可手动指定当前 `image` 的预览顺序|number |`-`|2.23.0|
|description|描述|string |`-`|-|
|src|图片获取地址|string |`-`|-|
|title|标题|string |`-`|-|
|footerPosition|底部显示的位置|'inner' \| 'outer' |`inner`|-|
|error|error 状态下显示的内容|ReactNode |`-`|-|
|loader|加载过渡效果，为 true 显示默认加载效果|boolean \| ReactNode |`-`|-|
|actions|额外操作|ReactNode[] |`-`|-|
|className|节点类名|string \| string[] |`-`|-|
|height|图片显示高度|string \| number |`-`|-|
|lazyload|开启懒加载 [Intersection_Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)|boolean \| IntersectionObserverInit |`-`|2.47.0|
|loaderClassName|loader 的样式，将覆盖默认过渡效果|string \| string[] |`-`|-|
|onError|图片加载失败时触发|(ev: SyntheticEvent&lt;HTMLImageElement&gt;) =&gt; void |`-`|-|
|onLoad|图片加载完成时触发|(ev: SyntheticEvent&lt;HTMLImageElement&gt;) =&gt; void |`-`|-|
|previewProps|预览的配置项 （所有选项都是可选的）[ImagePreviewProps](#imagepreview)|PartialImagePreviewProps |`-`|-|
|style|节点样式|CSSProperties |`-`|-|
|width|图片显示宽度|string \| number |`-`|-|

### Image.Preview

|参数名|描述|类型|默认值|版本|
|---|---|---|---|---|
|closable|是否显示关闭按钮|boolean |`true`|2.16.0|
|defaultVisible|默认是否可见，非受控|boolean |`-`|-|
|escToExit|按 `ESC` 键关闭预览|boolean |`true`|2.24.0|
|maskClosable|点击 mask 是否触发关闭|boolean |`true`|-|
|resetTranslate|开启位置修正|boolean |`true`|2.61.0|
|visible|是否可见，受控属性|boolean |`-`|-|
|breakPoint|触发 toolbar 切换为 simple 模式的宽度|number |`316`|-|
|src|图片获取地址, 在 Image 中默认是 Image 的 src|string  **(必填)**|`-`|-|
|imgAttributes|图片属性，透传至预览弹窗中的 `img` 标签上|Omit&lt;ImgHTMLAttributes&lt;HTMLImageElement&gt;, 'src'&gt; |`-`|2.39.0|
|extra|自定义图片预览区域的额外节点|ReactNode |`-`|2.53.0|
|actions|额外操作，[ImagePreviewActionProps](#imagepreviewactionprops)|[ImagePreviewActionProps](image#imagepreviewactionprops)[] |`-`|-|
|actionsLayout|控制条的布局|string[] |`['fullScreen', 'rotateRight', 'rotateLeft', 'zoomIn', 'zoomOut', 'originalSize', 'extra']`|-|
|className|节点类名|string \| string[] |`-`|-|
|scales|在预览缩放时会使用当前数组中的缩放百分比。若不包含 `100%`，则会自动添加在最相邻的位置。|number[] |`[25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500];`|2.30.0|
|style|节点样式|CSSProperties |`-`|-|
|getPopupContainer|弹出层挂载的节点|() => HTMLElement |`() => document.body`|2.16.0|
|imageRender|自定义 IMG 元素的渲染|(originalNode: ReactElement) => ReactNode |`-`|2.58.0|
|onVisibleChange|切换可见状态触发的事件|(visible: boolean, preVisible: boolean) => void |`-`|-|

### Image.PreviewGroup

从 `v2.14.0` 开始支持

|参数名|描述|类型|默认值|版本|
|---|---|---|---|---|
|closable|是否显示关闭按钮|boolean |`true`|2.16.0|
|defaultVisible|默认是否可见，非受控|boolean |`-`|-|
|escToExit|按 `ESC` 键关闭预览|boolean |`true`|2.24.0|
|forceRender|是否渲染图片列表，用于提前加载图片|boolean |`-`|2.58.0|
|infinite|是否无限循环|boolean |`-`|-|
|maskClosable|点击 mask 是否触发关闭|boolean |`true`|-|
|resetTranslate|开启位置修正|boolean |`true`|2.61.0|
|visible|是否可见，受控属性|boolean |`-`|-|
|breakPoint|触发 toolbar 切换为 simple 模式的宽度|number |`316`|-|
|current|当前展示的图片的下标 (受控属性)|number |`-`|-|
|defaultCurrent|第一张展示的图片的下标|number |`-`|-|
|imgAttributes|图片属性，透传至预览弹窗中的 `img` 标签上|Omit&lt;ImgHTMLAttributes&lt;HTMLImageElement&gt;, 'src'&gt; |`-`|2.39.0|
|extra|自定义图片预览区域的额外节点|ReactNode |`-`|2.53.0|
|actions|额外操作，[ImagePreviewActionProps](#imagepreviewactionprops)|[ImagePreviewActionProps](image#imagepreviewactionprops)[] |`-`|-|
|actionsLayout|控制条的布局|string[] |`['fullScreen', 'rotateRight', 'rotateLeft', 'zoomIn', 'zoomOut', 'originalSize', 'extra']`|-|
|className|节点类名|string \| string[] |`-`|-|
|scales|在预览缩放时会使用当前数组中的缩放百分比。若不包含 `100%`，则会自动添加在最相邻的位置。|number[] |`[25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500];`|2.30.0|
|srcList|图片列表 （设置了本属性之后，将不再收集 Image 子组件的图片信息）|string[] |`-`|-|
|style|节点样式|CSSProperties |`-`|-|
|getPopupContainer|弹出层挂载的节点|() => HTMLElement |`() => document.body`|2.16.0|
|imageRender|自定义 IMG 元素的渲染|(originalNode: ReactElement) => ReactNode |`-`|2.58.0|
|onChange|切换图片触发的事件|(index: number) => void |`-`|-|
|onVisibleChange|切换可见状态触发的事件|(visible: boolean, preVisible: boolean) => void |`-`|-|

### ImagePreviewActionProps

`<Image.Preview>` 中类型 `ImagePreviewActionProps` 详细参数。

|参数名|描述|类型|默认值|
|---|---|---|---|
|disabled|是否禁用|boolean |`-`|
|key|唯一标识|string  **(必填)**|`-`|
|name|名称|string |`-`|
|content|内容|ReactNode  **(必填)**|`-`|
|className|节点类名|string \| string[] |`-`|
|style|节点样式|CSSProperties |`-`|
|getContainer|因为 content 只能定义内容，所以提供这个函数用于支持自定义外围元素，需要注意的是设置了 `getContainer`, 显示 `name` 的 `Tooltip` 将失效。|(actionElement: ReactNode) => ReactNode |`-`|

</div>

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt