> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/image.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Image 图片

展示图片并放大浏览图片组。

## 基本用法


![绿色山谷](/leaf-ui/media/landscape-1.svg)![加载失败示例](data:image/png;base64,invalid)

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/image/basic.tsx"
import { Flex, Image } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

export function ImageBasic() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Image src={withBase('/media/landscape-1.svg')} width={240} height={160} alt="绿色山谷" />
      <Image
        src="data:image/png;base64,invalid"
        width={140}
        height={160}
        alt="加载失败示例"
        fallback={<span>暂无图片</span>}
      />
    </Flex>
  );
}
```

展开代码

## 更多用法


![风景 1](/leaf-ui/media/landscape-1.svg)![风景 2](/leaf-ui/media/landscape-2.svg)![风景 3](/leaf-ui/media/landscape-3.svg)

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/image/advanced.tsx"
import { Flex, Image, ImagePreviewGroup } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

export function ImageGallery() {
  return (
    <ImagePreviewGroup thumbnails downloadable>
      <Flex gap="md" align="center" wrap justify="center">
        {[1, 2, 3].map((index) => (
          <Image
            key={index}
            src={withBase(`/media/landscape-${index}.svg`)}
            width={180}
            height={120}
            alt={`风景 ${index}`}
          />
        ))}
      </Flex>
    </ImagePreviewGroup>
  );
}
```

展开代码

## 使用说明

支持键盘翻页、触摸滑动、缩放、缩略图和全屏。ImagePreviewGroup 自动收集子 Image，也可传入 items 与受控 open / index。纯展示的图片可设置 `preview={false}`。

## 类型

组装数据、定义回调和使用 ref 时，可以导入这些类型。

```ts
import type { ImagePreviewGroupProps, ImagePreviewItem, ImagePreviewProps, ImageProps } from '@ifhover/leaf-ui';
```

## ImagePreviewGroupProps API

| 属性              | 类型                                                     | 默认值     | 说明          |
| --------------- | ------------------------------------------------------ | ------- | ----------- |
| `children`      | `ReactNode`                                            | —       | 内容或下级项目     |
| `items`         | [`readonly ImagePreviewItem[]`](#imagepreviewitem-api) | —       | 按顺序展示的图片    |
| `open`          | `boolean`                                              | —       | 受控展示状态      |
| `defaultOpen`   | `boolean`                                              | `false` | 初始展示状态      |
| `onOpenChange`  | `(open: boolean) => void`                              | —       | 展开状态变化      |
| `index`         | `number`                                               | —       | 当前索引，从 0 开始 |
| `defaultIndex`  | `number`                                               | `0`     | 初始索引        |
| `onIndexChange` | `(index: number) => void`                              | —       | 图片切换        |
| `thumbnails`    | `boolean`                                              | `true`  | 缩略图导航       |
| `downloadable`  | `boolean`                                              | `false` | 显示下载操作      |

## ImagePreviewItem API

| 属性             | 类型                  | 默认值  | 说明             |
| -------------- | ------------------- | ---- | -------------- |
| `src`          | `string`            | 必填   | 图片地址           |
| `thumbnailSrc` | `string`            | —    | 缩略图地址，默认使用 src |
| `alt`          | `string`            | `''` | 图片文字说明         |
| `width`        | `number`            | —    | 宽度，数字按像素计算     |
| `height`       | `number`            | —    | 高度，数字按像素计算     |
| `download`     | `string \| boolean` | —    | 下载地址或是否允许下载    |
| `downloadName` | `string`            | —    | 自定义下载后的文件名     |

## ImagePreviewProps API

| 属性              | 类型                                                     | 默认值     | 说明          |
| --------------- | ------------------------------------------------------ | ------- | ----------- |
| `items`         | [`readonly ImagePreviewItem[]`](#imagepreviewitem-api) | 必填      | 按顺序展示的图片    |
| `open`          | `boolean`                                              | 必填      | 受控展示状态      |
| `index`         | `number`                                               | `0`     | 当前索引，从 0 开始 |
| `onClose`       | `() => void`                                           | 必填      | 关闭时触发       |
| `onIndexChange` | `(index: number) => void`                              | —       | 图片切换        |
| `thumbnails`    | `boolean`                                              | `true`  | 缩略图导航       |
| `downloadable`  | `boolean`                                              | `false` | 显示下载操作      |

## ImageProps API

| 属性           | 类型                                                         | 默认值       | 说明       |
| ------------ | ---------------------------------------------------------- | --------- | -------- |
| `preview`    | `boolean`                                                  | `true`    | 允许放大预览   |
| `previewSrc` | `string`                                                   | —         | 高清预览地址   |
| `fallback`   | `ReactNode`                                                | —         | 加载失败时的内容 |
| `fit`        | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | `'cover'` | 图片缩放方式   |

Image 支持 src、alt、width、height、loading、onLoad、onError 等原生图片属性。