Placeholder

基础反馈

基于 Bootstrap 5 的占位符组件，用于为组件或页面构建骨架屏加载状态，支持网格列宽度、主题背景色、lg/sm/xs 三种尺寸、glow/wave 动画以及占位按钮

Component Demo

Basic usage and examples of the Placeholder component

基础示例

占位符由 `placeholder` 类与网格列类（如 `col-6`）组合而成，用于指示内容仍在加载中；对屏幕阅读器隐藏的占位内容建议添加 `aria-hidden="true"`

卡片加载占位

卡片标题

一些用于构建卡片标题并构成卡片主体内容的快速示例文本。

将占位符应用到卡片各区域即可构建“加载卡片”，尺寸与比例和真实卡片保持一致，切换状态时需要编写少量 JavaScript 来替换内容

宽度

宽度可通过网格列类（xs 渲染 `col-*`）、宽度工具类或内联样式调整

颜色

默认使用 `currentColor` 作为背景，可通过 bg 渲染 `bg-*` 类覆盖为任意主题色

尺寸

占位符尺寸基于父元素排版样式，size 分别渲染 `placeholder-lg`/`placeholder-sm`/`placeholder-xs` 类进行调整

动画

animation 渲染 `placeholder-glow`/`placeholder-wave` 类，为占位符添加发光或波浪动画，更直观地传达“正在加载”的状态

交互示例

通过 state 控制加载状态即可在占位内容与真实内容之间切换，当前状态：加载中

API Documentation

Complete API reference for the Placeholder component

Props

Placeholder

属性名	类型	默认值	描述
`animation`	`PlaceholderAnimation`	-	占位符动画，`glow`/`wave` 分别渲染 `placeholder-glow`/`placeholder-wave` 类并替换默认的 `placeholder` 类，通常渲染为包裹多个占位符的容器元素
`as`	`ElementType`	`'span'`	渲染的元素标签，配合 animation 时可渲染为 `p`、`div` 等容器元素
`bg`	`PlaceholderBg`	-	背景色，渲染 `bg-*` 类以覆盖默认的 `currentColor` 背景
`size`	`PlaceholderSize`	-	占位符尺寸，`lg`/`sm`/`xs` 分别渲染 `placeholder-lg`/`placeholder-sm`/`placeholder-xs` 类
`xs`	`'auto' \| boolean \| number`	-	网格列宽度，数字渲染 `col-{n}` 类，`auto` 渲染 `col-auto` 类，`true` 渲染 `col` 类

PlaceholderButton

属性名	类型	默认值	描述
`animation`	`PlaceholderAnimation`	-	占位按钮动画，渲染 `placeholder-glow`/`placeholder-wave` 类并替换默认的 `placeholder` 类
`bg`	`PlaceholderBg`	-	背景色，渲染 `bg-*` 类以覆盖按钮默认背景
`size`	`PlaceholderSize`	-	占位按钮尺寸，渲染 `placeholder-lg`/`placeholder-sm`/`placeholder-xs` 类
`variant`	`ButtonVariant`	-	按钮变体，渲染 `btn-*` 类并透传给 Button 组件
`xs`	`'auto' \| boolean \| number`	-	网格列宽度，数字渲染 `col-{n}` 类，`auto` 渲染 `col-auto` 类，`true` 渲染 `col` 类

Common Props

属性名	类型	默认值	描述
`children`	`ReactNode`	-	占位符内容，可用 ` ` 等占位内容撑起与真实内容一致的高度
`className`	`string`	-	自定义类名
`...rest`	`HTMLAttributes \| ButtonHTMLAttributes`	-	透传原生元素属性（如 `onClick`、`style` 等），PlaceholderButton 透传给 Button 组件

Type Definitions

PlaceholderAnimation

占位符动画类型

export type PlaceholderAnimation = 'glow' | 'wave';

PlaceholderBg

占位符背景色类型

export type PlaceholderBg =
  | 'body-secondary'
  | 'danger'
  | 'dark'
  | 'info'
  | 'light'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning';

PlaceholderButtonProps

占位按钮组件属性接口

export interface PlaceholderButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  animation?: PlaceholderAnimation;
  bg?: PlaceholderBg;
  children?: ReactNode;
  className?: string;
  size?: PlaceholderSize;
  variant?: ButtonVariant;
  xs?: 'auto' | boolean | number;
}

PlaceholderProps

占位符组件属性接口

export interface PlaceholderProps extends HTMLAttributes<HTMLElement> {
  animation?: PlaceholderAnimation;
  as?: ElementType;
  bg?: PlaceholderBg;
  children?: ReactNode;
  className?: string;
  size?: PlaceholderSize;
  xs?: 'auto' | boolean | number;
}

PlaceholderSize

占位符尺寸类型

export type PlaceholderSize = 'lg' | 'sm' | 'xs';