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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/image.md.
Leaf UIReact 组件库
GitHub

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

更多用法

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 时，可以导入这些类型。

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

ImagePreviewGroupProps API

属性类型默认值说明
childrenReactNode—内容或下级项目
itemsreadonly ImagePreviewItem[]—按顺序展示的图片
openboolean—受控展示状态
defaultOpenbooleanfalse初始展示状态
onOpenChange(open: boolean) => void—展开状态变化
indexnumber—当前索引，从 0 开始
defaultIndexnumber0初始索引
onIndexChange(index: number) => void—图片切换
thumbnailsbooleantrue缩略图导航
downloadablebooleanfalse显示下载操作

ImagePreviewItem API

属性类型默认值说明
srcstring必填图片地址
thumbnailSrcstring—缩略图地址，默认使用 src
altstring''图片文字说明
widthnumber—宽度，数字按像素计算
heightnumber—高度，数字按像素计算
downloadstring | boolean—下载地址或是否允许下载
downloadNamestring—自定义下载后的文件名

ImagePreviewProps API

属性类型默认值说明
itemsreadonly ImagePreviewItem[]必填按顺序展示的图片
openboolean必填受控展示状态
indexnumber0当前索引，从 0 开始
onClose() => void必填关闭时触发
onIndexChange(index: number) => void—图片切换
thumbnailsbooleantrue缩略图导航
downloadablebooleanfalse显示下载操作

ImageProps API

属性类型默认值说明
previewbooleantrue允许放大预览
previewSrcstring—高清预览地址
fallbackReactNode—加载失败时的内容
fit'cover' | 'contain' | 'fill' | 'none' | 'scale-down''cover'图片缩放方式

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