Empty

基础反馈

基于 Bootstrap 5 的空状态组件，用于展示无数据、无搜索结果等空白场景的占位内容，通过 Empty 组合插图、标题、描述与操作按钮，EmptyImage 提供图片占位（支持 Lorem Picsum 等任意图片地址）、加载失败自动回退纯色背景、八种背景色变体以及多种形状与尺寸

Component Demo

Basic usage and examples of the Empty component

基础示例

图片

暂无数据

暂无数据，请稍后刷新重试

Empty 自上而下组合 `image`、`title`、`description` 与操作区，未提供 `image` 时通常只展示纯色占位块与说明文字

图片占位

图片占位

图片占位地址可以使用 Lorem Picsum 等任意图片服务

传入 `src` 渲染真实图片，图片按 cover 方式裁剪填充整个占位区域

纯色背景

primarysecondarysuccessdangerwarninginfolightdark

未传入 `src` 时渲染 `bg` 对应的 `bg-*-subtle` 纯色背景，`label` 显示占位说明文字，可直接替代外部图片服务

图片加载失败回退

加载失败回退

图片地址不可用时自动回退为纯色背景占位，避免出现空白区域

形状

`shape` 渲染 `circle`/`rounded`/`square` 三种圆角，默认为 `rounded`

尺寸

图片

小尺寸

小型空状态，适合紧凑容器

图片

默认尺寸

默认空状态

图片

大尺寸

大型空状态，适合整页占位

`size` 调整内边距与标题字号，`EmptyImage` 的 `width`/`height` 独立控制插图尺寸

自定义插图

image 插槽支持任意 React 节点，如动画图标、自定义 SVG 或彩色徽标

交互示例

苹果
香蕉
樱桃
榴莲
芒果

API Documentation

Complete API reference for the Empty component

Props

Empty

属性名	类型	默认值	描述
`as`	`ElementType`	`'div'`	渲染的根元素类型
`description`	`ReactNode`	-	次要描述文本，渲染在标题之后
`image`	`ReactNode`	-	插图区域内容，通常为 EmptyImage，也可传入任意 React 节点，渲染在标题之前
`size`	`EmptySize`	`'md'`	整体尺寸，`sm`/`md`/`lg` 调整内边距与标题字号
`title`	`ReactNode`	-	标题文本，渲染在插图之后

EmptyImage

属性名	类型	默认值	描述
`alt`	`string`	`''`	图片替代文本
`as`	`ElementType`	`'span'`	渲染的根元素类型
`bg`	`EmptyBg`	`'secondary'`	占位背景色变体，未传图片或加载失败时渲染 `bg-*-subtle` 纯色背景
`height`	`number \| string`	`160`	占位高度，数字按像素处理，也可传入任意 CSS 长度
`label`	`string`	`'图片'`	纯色占位上显示的说明文字
`shape`	`EmptyImageShape`	`'rounded'`	占位形状，`circle` 圆形、`rounded` 圆角方形、`square` 方形
`src`	`string`	-	图片地址（如 Lorem Picsum），加载失败时自动回退为纯色占位
`width`	`number \| string`	`240`	占位宽度，数字按像素处理，也可传入任意 CSS 长度

Common Props

属性名	类型	默认值	描述
`children`	`ReactNode`	-	子内容：Empty 中作为操作区渲染在描述之后，EmptyImage 中作为纯色占位的回退内容（优先于 `label`）
`className`	`string`	-	自定义类名
`...rest`	`HTMLAttributes`	-	透传原生元素属性（如 `style`、`aria-label` 等）

Type Definitions

EmptyBg

占位背景色变体类型

export type EmptyBg =
  'danger' | 'dark' | 'info' | 'light' | 'primary' | 'secondary' | 'success' | 'warning';

EmptyImageProps

图片占位组件属性接口

export interface EmptyImageProps extends HTMLAttributes<HTMLElement> {
  alt?: string;
  as?: ElementType;
  bg?: EmptyBg;
  children?: ReactNode;
  className?: string;
  height?: number | string;
  label?: string;
  shape?: EmptyImageShape;
  src?: string;
  width?: number | string;
}

EmptyImageShape

占位形状类型

export type EmptyImageShape = 'circle' | 'rounded' | 'square';

EmptyProps

空状态组件属性接口

export interface EmptyProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  description?: ReactNode;
  image?: ReactNode;
  size?: EmptySize;
  title?: ReactNode;
}

EmptySize

空状态尺寸类型

export type EmptySize = 'lg' | 'md' | 'sm';