HeroUI Image 组件完全指南

HeroUI（原 NextUI）的 Image 组件是一个功能丰富的图片展示组件，支持模糊效果、缩放动画、加载骨架屏和图片降级显示等特性。本文详细介绍该组件的安装、使用方法及 API 参考。

安装

使用 CLI 安装（推荐）

bash

npx heroui-cli@latest add image

注意：如果已全局安装 @heroui/react，可跳过此步骤。

使用包管理器安装

bash

# pnpm
pnpm add @heroui/image

# npm
npm install @heroui/image

# yarn
yarn add @heroui/image

# bun
bun add @heroui/image

导入

单独导入

tsx

import { Image } from "@heroui/image";

全局导入

tsx

import { Image } from "@heroui/react";

基础用法

tsx

import { Image } from "@heroui/react";

export default function App() {
  return (
    <Image
      alt="HeroUI hero Image"
      src="https://heroui.com/images/hero-card-complete.jpeg"
      width={300}
    />
  );
}

模糊效果（Blurred）

使用 isBlurred 属性可以复制图片并对其进行模糊处理，创建出背景模糊效果：

tsx

import { Image } from "@heroui/react";

export default function App() {
  return (
    <Image
      isBlurred
      alt="HeroUI Album Cover"
      className="m-5"
      src="https://heroui.com/images/album-cover.png"
      width={240}
    />
  );
}

缩放效果（Zoomed）

使用 isZoomed 属性可以在鼠标悬停时对图片进行缩放：

tsx

import { Image } from "@heroui/react";

export default function App() {
  return (
    <Image
      isZoomed
      alt="HeroUI Fruit Image"
      src="https://heroui.com/images/fruit-1.jpeg"
      width={240}
    />
  );
}

加载动画

Image 组件内置了骨架屏动画来指示图片加载状态，以及加载完成后的透明度动画效果。

提示：可以使用 https://app.requestly.io/delay 来模拟慢速网络环境测试加载效果。

图片降级显示（Fallback）

使用 fallbackSrc 属性可以在以下情况显示降级图片：

提供了 fallbackSrc 属性
src 中的图片正在加载
src 中的图片加载失败
src 中的图片不存在

tsx

import { Image } from "@heroui/react";

export default function App() {
  return (
    <Image
      fallbackSrc="https://via.placeholder.com/300x200"
      alt="HeroUI Image with fallback"
      src="https://heroui.com/images/non-existent-image.jpg"
      width={300}
    />
  );
}

与 Next.js Image 配合使用

Next.js 提供了优化的 Image 组件，可以与 HeroUI 的 Image 组件一起使用：

tsx

import { Image } from "@heroui/react";
import NextImage from "next/image";

export default function App() {
  return (
    <Image
      as={NextImage}
      src="https://heroui.com/images/hero-card-complete.jpeg"
      alt="Next.js Image"
      width={300}
      height={200}
    />
  );
}

注意：HeroUI 的 Image 组件是客户端组件，使用 useState 等 Hook 来处理加载状态和动画。如果不需要这些功能，可以直接使用 Next.js 的 Image 组件。

Slots（样式插槽）

Image 组件提供了以下样式插槽用于自定义：

插槽名称	说明
`img`	图片元素插槽
`wrapper`	图片包装器，处理对齐、位置和外观
`zoomedWrapper`	缩放图片的包装器插槽，防止图片内容溢出父容器
`blurredImg`	模糊复制图片的包装器插槽

API 参考

Image Props

属性	类型	默认值	说明
`src`	`string`	-	图片地址
`srcSet`	`string`	-	响应式图片地址集合
`sizes`	`string`	-	图片尺寸描述
`alt`	`string`	-	图片替代文本
`width`	`number`	-	图片宽度
`height`	`number`	-	图片高度
`radius`	`none \| sm \| md \| lg \| full`	`"lg"`	圆角大小
`shadow`	`none \| sm \| md \| lg`	`"none"`	阴影效果
`loading`	`eager \| lazy`	-	图片加载方式
`fallbackSrc`	`string`	-	降级图片地址
`isBlurred`	`boolean`	`false`	是否启用模糊效果
`isZoomed`	`boolean`	`false`	是否启用悬停缩放
`removeWrapper`	`boolean`	`false`	是否移除包装器
`disableSkeleton`	`boolean`	`false`	是否禁用骨架屏动画
`classNames`	`Partial<Record<"img" \| "wrapper" \| "zoomedWrapper" \| "blurredImg", string>>`	-	各插槽的自定义类名

Image Events

事件	类型	说明
`onLoad`	`ReactEventHandler<HTMLImageElement>`	图片加载完成时触发
`onError`	`() => void`	图片加载失败时触发

字节笔记本