@tplc/business/components/EMPTY_STATE_README.md

# 🎉 Empty 状态功能已完成

## 概述

已成功创建了独立的 `lcb-empty` 组件，并为 `lcb-product`、`lcb-list` 和 `lcb-wrapper-list` 组件添加了完整的空状态支持功能。用户现在可以通过 `emptyProps` 配置项自定义空状态的所有视觉元素。

![Empty State Example](/static/empty.png)

## ✨ 主要特性

- ✅ **独立组件**：抽离为 `lcb-empty` 独立组件，可在多处复用
- ✅ 自定义空状态图片及尺寸
- ✅ 自定义空状态文字及样式（颜色、大小、粗细）
- ✅ 自定义图片与文字的间距
- ✅ 独立的 `emptyProps` 配置项
- ✅ 完整的 TypeScript 类型支持
- ✅ 响应式设计，自动适配不同屏幕
- ✅ 支持 `lcb-product`、`lcb-list`、`lcb-wrapper-list` 等多个组件

## 🚀 快速开始

```vue
<template>
  <lcb-product
    :items="productList"
    :emptyProps="{
      image: '/static/empty.png',
      text: '还没有点亮记录',
    }"
  />
</template>
```

## 📦 配置项

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `image` | `string` | `''` | 空状态图片地址 |
| `text` | `string` | `'还没有点亮记录'` | 空状态文字 |
| `imageWidth` | `number` | `400` | 图片宽度（rpx） |
| `imageHeight` | `number` | `400` | 图片高度（rpx） |
| `textColor` | `string` | `'#999999'` | 文字颜色 |
| `textSize` | `number` | `28` | 文字大小（rpx） |
| `textWeight` | `string \| number` | `'normal'` | 文字粗细 |
| `gap` | `number` | `24` | 图片与文字间距（rpx） |

## 📖 完整示例

### 基础用法

```vue
<lcb-product
  :items="[]"
  :emptyProps="{
    image: '/static/empty.png',
    text: '还没有点亮记录',
  }"
/>
```

### 自定义样式

```vue
<lcb-product
  :items="[]"
  :emptyProps="{
    image: '/static/empty.png',
    text: '暂无数据',
    imageWidth: 500,
    imageHeight: 500,
    textColor: '#666666',
    textSize: 32,
    textWeight: 'bold',
    gap: 32,
  }"
/>
```

### 在 lcb-list 中使用

```vue
<lcb-list
  pageFilterType="product-filter"
  :emptyProps="{
    image: '/static/empty.png',
    text: '还没有点亮记录',
  }"
/>
```

### 在 lcb-wrapper-list 中使用

```vue
<lcb-wrapper-list
  :dataSource="dataSource"
  :emptyProps="{
    image: '/static/empty.png',
    text: '暂无数据',
  }"
>
  <template #default="{ data }">
    <view>{{ data }}</view>
  </template>
</lcb-wrapper-list>
```

### 直接使用 lcb-empty 组件

```vue
<lcb-empty
  image="/static/empty.png"
  text="还没有点亮记录"
  :imageWidth="500"
  :imageHeight="500"
/>
```

## 📂 项目结构

```
packages/
├── business/
│   └── components/
│       ├── lcb-empty/                   # 🆕 新增组件
│       │   ├── lcb-empty.vue            # 📄 新增
│       │   ├── types.ts                 # 📄 新增
│       │   └── README.md                # 📄 新增
│       ├── lcb-product/
│       │   ├── lcb-product.vue          # ✅ 已修改
│       │   ├── types.ts                 # ✅ 已修改
│       │   ├── EMPTY_USAGE.md           # 📄 新增
│       │   ├── EMPTY_IMPLEMENTATION.md  # 📄 新增
│       │   └── EMPTY_QUICK_REF.md       # 📄 新增
│       ├── lcb-list/
│       │   ├── lcb-list.vue             # ✅ 已修改
│       │   └── types.ts                 # ✅ 已修改
│       ├── lcb-wrapper-list/
│       │   ├── lcb-wrapper-list.vue     # ✅ 已修改
│       │   └── types.ts                 # ✅ 已修改
│       └── CHANGELOG_EMPTY.md           # 📄 新增
└── engine/
    └── src/
        ├── static/
        │   └── empty.png                # 🖼️ 新增
        └── pages/
            └── lcb-product/
                └── empty-demo.vue       # 📄 新增
```

## 🔍 技术细节

### 类型定义

```typescript
export interface LcbEmptyProps {
  /** 空状态图片地址 */
  image?: string
  /** 空状态文字 */
  text?: string
  /** 图片宽度（rpx） */
  imageWidth?: number
  /** 图片高度（rpx） */
  imageHeight?: number
  /** 文字颜色 */
  textColor?: string
  /** 文字大小（rpx） */
  textSize?: number
  /** 文字粗细 */
  textWeight?: 'normal' | 'bold' | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
  /** 图片与文字的间距（rpx） */
  gap?: number
  /** 最小高度（rpx） */
  minHeight?: number
  /** 内边距配置 */
  paddingTop?: number
  paddingRight?: number
  paddingBottom?: number
  paddingLeft?: number
}
```

### 显示逻辑

空状态在以下条件同时满足时显示：
- 数据加载完成（`loading === false`）
- 数据列表为空（`renderList.length === 0`）

### 样式实现

- 使用 Flexbox 垂直居中布局
- 图片使用 `aspectFit` 模式保持比例
- 所有尺寸使用 `rpx` 单位，响应式适配
- 继承父组件的内边距设置

## 📚 文档清单

1. **[EMPTY_USAGE.md](./lcb-product/EMPTY_USAGE.md)** - 详细使用文档
   - 配置项说明
   - 使用示例
   - 注意事项

2. **[EMPTY_IMPLEMENTATION.md](./lcb-product/EMPTY_IMPLEMENTATION.md)** - 实现说明
   - 修改的文件列表
   - 技术实现细节
   - 功能特点

3. **[EMPTY_QUICK_REF.md](./lcb-product/EMPTY_QUICK_REF.md)** - 快速参考
   - 配置项速查表
   - 常用配置示例

4. **[CHANGELOG_EMPTY.md](./CHANGELOG_EMPTY.md)** - 更新日志
   - 新增功能说明
   - 兼容性说明

5. **[empty-demo.vue](../engine/src/pages/lcb-product/empty-demo.vue)** - 示例页面
   - 多种配置场景展示
   - 实际效果预览

## ✅ 测试检查

- [x] TypeScript 类型检查通过
- [x] 无 Linter 错误
- [x] 默认配置正常工作
- [x] 自定义配置生效
- [x] 向下兼容性保持
- [x] 文档完整

## 🎯 适用场景

- 商品列表为空时的提示
- 搜索无结果时的展示
- 筛选条件过滤后无数据的提示
- 用户收藏、点亮等记录为空的展示
- 任何需要空状态提示的列表场景

## 💡 最佳实践

1. **图片选择**：使用清晰、友好的插图，尺寸建议 300-600rpx
2. **文字描述**：简洁明了，告知用户当前状态
3. **颜色搭配**：文字颜色建议使用中性灰色（#999999）
4. **间距设置**：图片与文字间距建议 20-40rpx
5. **响应式**：使用 rpx 单位确保在不同设备上显示一致

## 🔗 相关组件

- `lcb-empty` - 空状态组件（独立组件）
- `lcb-product` - 商品列表组件（使用 lcb-empty）
- `lcb-list` - 通用列表组件（使用 lcb-empty）
- `lcb-wrapper-list` - 包装列表组件（使用 lcb-empty）
- `lcb-block` - 容器组件

## 📞 支持

如有问题或建议，请查阅相关文档或联系开发团队。

---

**开发时间**: 2026-01-19  
**版本**: v1.0.0  
**状态**: ✅ 已完成