liubinfighter_csv-lite/docs/STICKY_HEADERS.md

固定行列功能 (Sticky Headers & Columns)

概述

新增的固定行列功能允许用户通过简单的Pin/Unpin按钮来固定表格的特定行和列，在滚动大型CSV文件时保持重要的标题行和关键列始终可见。

使用方法

固定列

1. 将鼠标悬停在列标题（A, B, C...）上
2. 点击出现的📍图标来固定该列
3. 固定后图标变为📌，列将在水平滚动时保持可见
4. 再次点击📌图标可取消固定

固定行

1. 将鼠标悬停在行号（0, 1, 2...）上
2. 点击出现的📍图标来固定该行
3. 固定后图标变为📌，行将在垂直滚动时保持可见
4. 再次点击📌图标可取消固定

技术实现

核心技术

• CSS Position Sticky: 使用原生CSS sticky定位实现流畅的固定效果
• 动态类管理: 通过JavaScript动态添加/移除.csv-sticky-row和.csv-sticky-col类
• 事件驱动: 基于用户点击事件的响应式Pin/Unpin机制

架构特点

• 保持原有结构: 不破坏现有的单一表格结构，完全兼容现有功能
• 性能优化: 使用CSS sticky而非JavaScript滚动监听，性能更佳
• 灵活配置: 支持任意数量的行列同时固定

样式层次

.csv-sticky-row {
  position: sticky !important;
  top: 0;
  z-index: 20;
}

.csv-sticky-col {
  position: sticky !important;
  left: 0; 
  z-index: 15;
}

.csv-sticky-row.csv-sticky-col {
  z-index: 25; /* 交叉区域最高优先级 */
}

优势对比

vs 四象限方案

• ✅ 兼容性好: 保持原有表格结构，所有现有功能无缝兼容
• ✅ 实现简单: 无需复杂的四象限布局和滚动同步
• ✅ 性能更好: 利用浏览器原生sticky性能优化
• ✅ 维护容易: 代码结构清晰，易于调试和扩展

vs 复杂UI面板

• ✅ 用户体验: 直观的Pin/Unpin按钮，所见即所得
• ✅ 学习成本低: 无需额外的配置界面，点击即用
• ✅ 空间节约: 不占用额外的UI空间

文件变更

新增功能

• src/view.ts: 添加sticky状态管理和切换逻辑
• src/view/table-render.ts: 在表头添加Pin/Unpin按钮
• styles.css: 添加sticky样式和按钮样式

测试覆盖

• test/sticky-functionality.test.ts: 核心逻辑单元测试

使用场景

数据分析

• 固定表头行查看列含义
• 固定ID列追踪特定记录
• 固定日期列对比时间序列

大表格导航

• 1000+行数据滚动时保持标题可见
• 多列对比时固定关键基准列
• 分组数据查看时固定分组标识列

兼容性

• ✅ 所有现有CSV编辑功能
• ✅ 搜索和筛选功能
• ✅ 拖拽排序功能
• ✅ 列宽调整功能
• ✅ 右键菜单功能