@beppla/tapas-ui 1.4.34 → 1.5.0

package/package/module/StatisticsTable/PLACEHOLDER_FEATURE.md

@@ -1,287 +0,0 @@
-# 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 检查
-