@beppla/tapas-ui 1.4.32 → 1.4.33

package/package/module/StatisticsTable/PLACEHOLDER_FEATURE.md

@@ -0,0 +1,287 @@
+# StatisticsTable 占位功能说明
+
+## 概述
+
+为 StatisticsTable 组件添加了占位行和列的功能，当数据不足以撑满外层容器时，会自动添加占位行和列来填充空间。
+
+## 新增属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `enablePlaceholder` | `boolean` | `false` | 是否启用占位功能 |
+| `minRows` | `number` | `0` | 最小行数（如果实际数据行数少于此值，会添加占位行） |
+| `minColumns` | `number` | `0` | 最小列数（如果实际数据列数少于此值，会添加占位列） |
+| `placeholderRowHeight` | `number` | `rowHeight` (56) | 占位行的高度 |
+| `placeholderColumnWidth` | `number \| number[]` | `150` | 占位列的宽度（可以是数字或数组为每列单独设置） |
+
+## 工作原理
+
+### 占位行
+- 当 `enablePlaceholder={true}` 且 `rows.length < minRows` 时
+- 会在实际数据行之后添加 `(minRows - rows.length)` 个占位行
+- 占位行的 key 格式为 `_placeholder_row_0`, `_placeholder_row_1` 等
+- 每个占位行使用 `placeholderRowHeight` 高度（未设置时使用 `rowHeight`，默认 56px）
+- 占位行内容为空，保持视觉整洁
+
+### 占位列
+- 当 `enablePlaceholder={true}` 且实际数据列数 `< minColumns` 时
+- 会在实际数据列之后添加 `(minColumns - currentDataColumns)` 个占位列
+- 占位列的 key 格式为 `_placeholder_col_0`, `_placeholder_col_1` 等
+- 每个占位列使用 `placeholderColumnWidth` 宽度（默认 150px）
+- 占位列内容为空，保持视觉整洁
+
+### 灵活性
+通过 `placeholderRowHeight` 和 `placeholderColumnWidth` 参数，可以精确控制占位元素的尺寸：
+- **小尺寸占位**：适用于需要更紧凑的表格布局
+- **大尺寸占位**：适用于需要更宽松的表格布局
+- **精确控制**：可以计算容器大小并设置精确的占位尺寸来完美填充
+
+### 与统计功能的兼容性
+- 占位行和列完全兼容 Row Stats 和 Column Stats 功能
+- 占位单元格会被正确识别并跳过内容渲染
+- 统计计算不会包含占位行列的数据
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<StatisticsTable
+  rows={rows}              // 假设只有 2 行数据
+  columns={columns}        // 假设只有 2 列数据
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}            // 确保至少显示 10 行
+  minColumns={5}          // 确保至少显示 5 列
+  maxHeight={600}         // 设置容器高度
+/>
+```
+
+### 仅填充行
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}
+  maxHeight={600}
+/>
+```
+
+### 仅填充列
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minColumns={5}
+/>
+```
+
+### 自定义占位尺寸
+
+**统一设置所有占位列宽度：**
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}
+  minColumns={5}
+  placeholderRowHeight={80}      // 占位行高度 80px
+  placeholderColumnWidth={200}   // 所有占位列宽度 200px
+  maxHeight={600}
+/>
+```
+
+**为每个占位列单独设置宽度（更好地适配屏幕宽度）：**
+
+```tsx
+<StatisticsTable
+  rows={rows}              // 假设有 2 列数据
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minColumns={5}           // 需要 3 个占位列
+  placeholderColumnWidth={[180, 250, 120]} // 为每个占位列单独设置宽度
+  // 占位列 1: 180px
+  // 占位列 2: 250px
+  // 占位列 3: 120px
+/>
+```
+
+如果数组长度少于所需的占位列数量，最后一个值会被重复使用：
+
+```tsx
+placeholderColumnWidth={[200, 150]}  // minColumns=5, 需要 3 个占位列
+// 结果: [200, 150, 150] - 最后的值 (150) 被重复使用
+```
+
+### 配合统计功能
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}
+  minColumns={5}
+  placeholderRowHeight={70}
+  showRowStats={true}      // 可以同时使用行统计
+  maxHeight={600}
+/>
+```
+
+### 精确填充容器
+
+如果你知道容器的确切尺寸，可以计算需要的占位数量和尺寸：
+
+```tsx
+const containerHeight = 600;
+const headerHeight = 40;
+const columnStatsHeight = showColumnStats ? 120 : 0;
+const availableHeight = containerHeight - headerHeight - columnStatsHeight;
+
+const dataRowsCount = 3;
+const desiredTotalRows = Math.floor(availableHeight / 56);
+
+<StatisticsTable
+  rows={rows}              // 3 rows
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={desiredTotalRows}
+  placeholderRowHeight={56}
+  maxHeight={containerHeight}
+/>
+```
+
+## 使用场景
+
+1. **固定大小表格**：需要表格保持固定的视觉大小，不随数据量变化
+2. **数据加载中**：在数据还在加载但想保持布局稳定时
+3. **预留空间**：为可能增加的数据预留视觉空间
+4. **对齐要求**：多个表格需要保持相同的尺寸对齐
+
+## 实现细节
+
+### 内部实现
+
+组件内部通过 `useMemo` 生成 `displayRows` 和 `displayColumns`：
+
+```typescript
+const { displayRows, displayColumns } = useMemo(() => {
+  if (!enablePlaceholder) {
+    return { displayRows: rows, displayColumns: columns };
+  }
+
+  // 处理列：如果当前列数少于最小列数，添加占位列
+  let finalColumns = [...columns];
+  const currentDataColumns = columns.filter(col => !col.isAction).length;
+  
+  if (minColumns > 0 && currentDataColumns < minColumns) {
+    const missingColumns = minColumns - currentDataColumns;
+    const placeholderColumns = Array.from({ length: missingColumns }, (_, i) => ({
+      key: `_placeholder_col_${i}`,
+      title: '',
+      width: 150, // 使用默认宽度
+    }));
+    finalColumns = [...columns, ...placeholderColumns];
+  }
+
+  // 处理行：如果当前行数少于最小行数，添加占位行
+  let finalRows = [...rows];
+  if (minRows > 0 && rows.length < minRows) {
+    const missingRows = minRows - rows.length;
+    const placeholderRows = Array.from({ length: missingRows }, (_, i) => ({
+      key: `_placeholder_row_${i}`,
+      label: '',
+      height: rowHeight, // 使用默认行高
+    }));
+    finalRows = [...rows, ...placeholderRows];
+  }
+
+  return { displayRows: finalRows, displayColumns: finalColumns };
+}, [rows, columns, enablePlaceholder, minRows, minColumns, rowHeight]);
+```
+
+### 渲染处理
+
+在渲染时，组件会检测占位行列并跳过内容渲染：
+
+```typescript
+const isPlaceholder = row.key.startsWith('_placeholder_row_');
+const isColPlaceholder = column.key.startsWith('_placeholder_col_');
+
+// 占位单元格不渲染内容
+<View style={[styles.cell, { width: colWidth }]}>
+  {!isColPlaceholder && !isPlaceholder && renderCellContent(column, cell, row.data)}
+</View>
+```
+
+## 测试覆盖
+
+新增了以下测试用例：
+
+1. ✅ 禁用占位功能时不添加占位符
+2. ✅ 数据列少于 minColumns 时添加占位列
+3. ✅ 数据行少于 minRows 时添加占位行
+4. ✅ 同时添加占位行和列
+5. ✅ 数据满足最小要求时不添加占位符
+6. ✅ 与 Row Stats 配合使用
+7. ✅ 与 Column Stats 配合使用
+8. ✅ 使用自定义占位行高度
+9. ✅ 使用自定义占位列宽度
+10. ✅ 同时使用自定义占位行高度和列宽度
+
+## Storybook 示例
+
+### 占位功能示例
+
+添加了 6 个新的 Story 来展示占位功能：
+
+1. `WithPlaceholderRows` - 仅占位行
+2. `WithPlaceholderColumns` - 仅占位列
+3. `WithPlaceholderRowsAndColumns` - 同时占位行列
+4. `WithPlaceholderAndRowStats` - 占位行配合行统计
+5. `WithPlaceholderAndColumnStats` - 占位行配合列统计
+6. `WithCustomPlaceholderSize` - 自定义占位行列尺寸（80px行高 × 200px列宽）
+
+### 滚动阴影示例
+
+添加了 4 个新的 Story 来展示滚动阴影功能：
+
+1. `WithScrollShadow` - 展示滚动阴影效果（上下左右四个方向）
+2. `WithoutScrollShadow` - 对比：不使用滚动阴影（使用滚动条）
+3. `ScrollShadowWithRowStats` - 滚动阴影配合行统计
+4. `ScrollShadowWithColumnStats` - 滚动阴影配合列统计
+
+## 注意事项
+
+1. **性能考虑**：占位功能使用 `flex: 1`，不会增加额外的行列，性能影响极小
+2. **视觉一致性**：占位单元格没有边框，保持视觉上的整洁
+3. **数据完整性**：占位行列不会影响统计计算和数据导出
+4. **互不干扰**：占位功能与现有所有功能完全兼容（统计、分页、虚拟化等）
+
+## 更新日志
+
+- ✅ 在 `StatisticsTable.tsx` 中添加占位行列逻辑
+- ✅ 更新 `StatisticsTableProps` 接口，添加新属性
+  - `enablePlaceholder` - 启用占位功能
+  - `minRows` - 最小行数
+  - `minColumns` - 最小列数
+  - `placeholderRowHeight` - 自定义占位行高度
+  - `placeholderColumnWidth` - 自定义占位列宽度
+- ✅ 更新 README.md，添加功能说明和使用示例
+- ✅ 添加完整的测试用例（10个测试）
+- ✅ 添加 Storybook 示例（6个 Stories）
+- ✅ 添加滚动阴影 Storybook 示例（4个 Stories）
+- ✅ 所有代码通过 Linter 检查
+