更新记录

1.0.0（2026-04-09）

• 初始版本
• 支持基本的空状态展示
• 支持自定义图片、图标、标题、描述、操作按钮
• 支持自定义样式（字体大小、颜色、图片大小）
• 支持倒计时功能

平台兼容性

uni-app(3.7.3)

其他

empty-state-pro 空状态插件

一个功能强大、高度可定制的空状态组件，支持自定义图片、图标、标题、描述、操作按钮，以及倒计时功能，适用于各种空状态场景。

功能特性

• ✅ 支持自定义图片
• ✅ 支持自定义图标（emoji或图标字体）
• ✅ 支持自定义标题和描述
• ✅ 支持操作按钮
• ✅ 支持自定义样式（字体大小、颜色、图片大小）
• ✅ 支持倒计时功能
• ✅ 响应式设计
• ✅ 支持 Vue 3 组合式 API
• ✅ 支持 uni-app 多端框架
• ✅ 轻量级实现
• ✅ 无依赖

安装

方法一：直接复制

将 empty-state-pro.vue 文件复制到您的项目的 components 目录中。

方法二：通过 npm 安装（如果发布到 npm）

npm install empty-state-pro
# 或
yarn add empty-state-pro

使用示例

基本使用

<template>
  <EmptyState />
</template>

<script setup>
import EmptyState from '@/components/empty-state-pro/empty-state-pro.vue';
</script>

自定义内容

<template>
  <EmptyState 
    icon="📧" 
    title="暂无邮件" 
    description="您的邮箱是空的，快来查看新邮件吧！"
    actionText="去查看"
    @action="handleAction"
  />
</template>

<script setup>
import EmptyState from '@/components/empty-state-pro/empty-state-pro.vue';

const handleAction = () => {
  // 处理点击事件
  console.log('点击了操作按钮');
};
</script>

自定义样式

<template>
  <EmptyState 
    icon="🎨" 
    title="自定义样式示例" 
    description="这是一个自定义字体大小、颜色和图片大小的示例"
    actionText="查看详情"
    :style="{
      fontSize: { title: '40rpx', description: '32rpx', button: '30rpx' },
      fontColor: { title: '#ff6b6b', description: '#6c5ce7', button: '#ffffff' },
      imageSize: { width: '250rpx' }
    }"
    @action="handleAction"
  />
</template>

带倒计时功能

<template>
  <EmptyState 
    icon="⏰" 
    title="返回首页"
    description="10秒后可点击按钮返回首页"
    actionText="返回首页"
    :countdown="{
      enabled: true,
      seconds: 10
    }"
    @action="handleBack"
  />
</template>

<script setup>
import EmptyState from '@/components/empty-state-pro/empty-state-pro.vue';

const handleBack = () => {
  // 处理返回首页
  uni.navigateTo({ url: '/pages/index/index' });
};
</script>

使用自定义图片

<template>
  <EmptyState 
    image="/static/empty.png" 
    title="暂无数据" 
    description="这里什么都没有"
    actionText="刷新"
    @action="handleRefresh"
  />
</template>

配置选项

Props

Style 配置

{
  fontSize: {
    title: '30rpx',     // 标题字体大小
    description: '26rpx', // 描述字体大小
    button: '28rpx'      // 按钮字体大小
  },
  fontColor: {
    title: '#666',       // 标题颜色
    description: '#999',  // 描述颜色
    button: 'white'      // 按钮颜色
  },
  imageSize: {
    width: '200rpx'      // 图片宽度（高度会自动保持比例）
  }
}

Countdown 配置

{
  enabled: false,  // 是否启用倒计时
  seconds: 5,      // 倒计时秒数
  text: '重新获取' // 倒计时文本（目前未使用，保留用于未来扩展）
}

事件

使用场景

1. 列表为空

<template>
  <view v-if="list.length === 0">
    <EmptyState 
      icon="📋" 
      title="暂无数据"
      description="这里还没有任何内容"
      actionText="刷新"
      @action="refreshList"
    />
  </view>
  <view v-else>
    <!-- 列表内容 -->
  </view>
</template>

2. 搜索结果为空

<template>
  <view v-if="searchResults.length === 0">
    <EmptyState 
      icon="🔍" 
      title="未找到相关内容"
      description="尝试使用其他关键词搜索"
      actionText="返回"
      @action="goBack"
    />
  </view>
  <view v-else>
    <!-- 搜索结果 -->
  </view>
</template>

3. 网络错误

<template>
  <view v-if="networkError">
    <EmptyState 
      icon="🌐" 
      title="网络错误"
      description="请检查网络连接后重试"
      actionText="重新加载"
      @action="reload"
    />
  </view>
  <view v-else>
    <!-- 正常内容 -->
  </view>
</template>

4. 权限不足

<template>
  <view v-if="!hasPermission">
    <EmptyState 
      icon="🔒" 
      title="权限不足"
      description="您没有权限访问此内容"
      actionText="返回"
      @action="goBack"
    />
  </view>
  <view v-else>
    <!-- 有权限的内容 -->
  </view>
</template>

常见问题

Q: 如何自定义按钮的背景颜色？

A: 可以通过 buttonClass 属性添加自定义类名，或者在 style 对象中设置按钮样式。

<template>
  <EmptyState 
    actionText="确定"
    buttonClass="custom-button"
  />
</template>

<style>
.custom-button {
  background-color: #1890ff !important;
}
</style>

Q: 如何修改图标的大小？

A: 可以通过 iconClass 属性添加自定义类名来修改图标大小。

<template>
  <EmptyState 
    icon="📦"
    iconClass="large-icon"
  />
</template>

<style>
.large-icon {
  font-size: 150rpx !important;
}
</style>

Q: 倒计时功能如何工作？

A: 当启用倒计时功能时，组件加载后会自动开始倒计时，倒计时期间按钮会显示倒计时信息并被禁用，倒计时结束后按钮恢复正常状态。

性能优化

1. 按需加载：只在需要显示空状态时才渲染组件
2. 图片优化：使用合适大小的图片，避免过大的图片影响加载速度
3. 避免过度使用：只在真正需要显示空状态时使用，不要在正常内容中使用

浏览器兼容性

框架兼容性

• ✅ Vue 3.2+
• ✅ uni-app
• ✅ 微信小程序
• ✅ 支付宝小程序
• ✅ 百度小程序
• ✅ 字节跳动小程序

贡献指南

1. Fork 本仓库
2. 创建 feature 分支
3. 提交代码
4. 运行测试
5. 提交 Pull Request

版本历史

v1.0.0

• 初始版本
• 支持基本的空状态展示
• 支持自定义图片、图标、标题、描述、操作按钮
• 支持自定义样式
• 支持倒计时功能

许可证

MIT

联系方式

如果您有任何问题或建议，欢迎提交 Issue 或 Pull Request。