#3132·layui

[empty] 新增 Empty 空状态组件

Author: sunxiaobin89Created Aug 11, 2026Updated Sep 14, 2026

背景

管理后台「列表、表格、树」等数据为空时的高频展示需求。目前 layui 2.x → 3.0 均未提供通用空状态组件(tree、table 内部各自实现了独立的空态样式),缺少统一方案。空状态作为后台管理场景的通用能力,主流 UI 组件库普遍内置支持。

目标

  • 新增通用 empty 空状态组件,纯 CSS 实现,零 JS、零依赖、零交互
  • 遵循 3.0 命名空间(lay- 前缀)与 CSS Variables 令牌体系,与 badge / timeline / panel 等纯 CSS 组件同级
  • 内置默认图标(lay-icon-file),支持自定义图标与自定义内容

范围

  • 新增src/css/modules/empty.csstests/visual/empty.html(可视化示例,随仓库提交)
  • 修改src/css/index.css(新增一行 @import './modules/empty.css';
  • 无需:JS 模块、src/index.js / index.umd.js / initializer.js、docs、tests/unit

设计

HTML 结构

xml
<div class="lay-empty">
  <div class="lay-empty-icon"></div>
  <p class="lay-empty-text">暂无数据</p>
</div>

<div class="lay-empty">
  <div class="lay-empty-icon"><i class="lay-icon lay-icon-folder-open"></i></div>
  <p class="lay-empty-text">暂无文件夹</p>
  <p class="lay-empty-description">当前分类下还没有内容</p>
  <div class="lay-empty-action">
    <button class="lay-btn lay-btn-primary">新建文件夹</button>
  </div>
</div>

结构分层:lay-empty(根)→ lay-empty-icon(图标,可空则显示默认)/ lay-empty-text(主文案)/ lay-empty-description(可选说明)/ lay-empty-action(可选操作区)。

CSS 要点

  • 全量走 CSS 变量令牌:--lay-gray-500/600/700--lay-spacing-*;组件级可调变量 --lay-empty-icon-size
  • 内置图标通过 .lay-empty-icon:empty::before 注入字体图标(content: '\e621'),容器为空时自动显示默认图标,放入自定义内容后自动隐藏,实现「内置 + 可自定义」
  • 无状态类、无尺寸变体,保持最小

文件清单

操作 文件
新增 src/css/modules/empty.css
新增 tests/visual/empty.html
修改 src/css/index.css

讨论点

  1. 默认图标是否采用 lay-icon-file?是否需为「空列表 / 空目录」等场景提供图标变体?
  2. 内置图标采用「CSS :empty::before」实现,要求 .lay-empty-icon 为空标签(紧凑写法)。是否认可,或希望更简单的内置方式?
  3. 是否将本组件纳入 3.0.0 里程碑,作为「增加全新组件」规划线的首个落地?
  4. 后续是否与 table / form 空态集成,统一空数据展示?

后续可扩展

  • table / form 数据为空时自动渲染 Empty
  • 插画式默认图、淡入动效、尺寸变体

非目标

  • 不做 JS 模块 / Component class(无状态无交互)
  • 不内置图片 / 插画资产
  • 不做「一键重载」内置逻辑(操作区由用户自由填充)