# CSV插件

**Repository Path**: li52qq/csv-plugin

## Basic Information

- **Project Name**: CSV插件
- **Description**: 本地自用的 CSV 表格编辑器插件：支持数据预览、编辑、筛选功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-05
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CSV Table Editor（PyCharm 插件）

在 PyCharm 中以**表格形式**查看、编辑、搜索、筛选 `.csv` 文件的本地分发插件。

- 自研 RFC 4180 解析器：支持引号转义、多行字段、分隔符自动识别（`, ; \t |`）
- 所有编辑走 IntelliJ `WriteCommandAction` / `Document`，撤销栈、Ctrl+S 保存、编码与换行符由平台接管
- 解析全部在后台线程完成，100MB 内大文件滚动流畅

---

## 一、安装

### 1. 从 zip 安装（推荐）

```powershell
# 本机需 JDK 17+ 与 Gradle 8.10+（首次构建会自动下载 IntelliJ Platform 依赖）
gradle buildPlugin          # 产物：build/distributions/csv-table-editor-<版本>.zip
gradle runIde               # 启动沙箱 PyCharm 实测（Community）
```

PyCharm 中：`Settings → Plugins → ⚙ → Install Plugin from Disk` → 选择 zip → 重启。

### 2. 打开 CSV 文件

- 双击任意 `.csv` 文件即以表格视图打开（首屏优先显示表格编辑器）
- 右上角编辑器切换栏可随时在「表格」与默认文本视图之间切换
- 若内置 CSV 插件的表格编辑器抢占首屏，可在插件列表临时停用它，或手动切换到本插件

---

## 二、查看

| 功能 | 说明 |
|---|---|
| 分隔符自动识别 | 打开文件时扫描前 30 行引号外分隔符出现次数，自动判定 `,` `;` `Tab` `\|`，状态栏显示识别结果 |
| 表头检测 | 首行 ≥2 列且全非空非纯数字时判定为表头行；否则按无表头数据展示 |
| 行号列 | 表格左侧固定行号列（只读），随筛选/排序动态变化 |
| 列宽记忆 | 手动拖动列宽后自动按文件名记忆（`PropertiesComponent`），下次打开恢复 |
| 状态栏 | 显示 行数 × 列数、分隔符、表头检测结果，有未保存修改时红色提示 |
| 超大文件警告 | 文件刚生成完就打开时，状态栏会显示 ⚠ 警告（行索引建立在半成品文件上），此时重新打开或等待重解析即可 |

---

## 三、编辑

### 1. 编辑单元格

- **双击**单元格或选中后按 **F2 / 回车** 进入编辑，**Esc** 取消
- 提交后立即写回内存，按 **Ctrl+S** 保存到磁盘；保存前原文件不会被修改
- 值中含分隔符 / 引号 / 换行时自动按 RFC 4180 加引号转义
- 每次单元格修改都是一个独立撤销步骤（Ctrl+Z / Ctrl+Shift+Z）

### 2. 右键菜单（表格任意位置）

| 菜单项 | 作用 | 快捷键 |
|---|---|---|
| 批量修改所选单元格 | 将选中的多个单元格统一修改为同一值（输入框留空 = 清空） | — |
| 清空所选单元格 | 清除选中单元格的内容 | `Delete` |
| 删除行 | 删除选中的一行或多行（含确认对话框） | `Ctrl+Delete` |
| 添加行（末尾） | 在表格末尾追加空行，输入框填入逗号分隔的初始值即可同时填充 | — |
| 添加列（末尾） | 在表格末尾追加一列（输入新列名） | — |

> 右键菜单按当前选择动态启用：未选中任何单元格时「批量修改 / 清空」置灰；多行选择时「删除行」一次性删除全部选中行。

### 3. 撤销 / 恢复

| 操作 | 快捷键 | 说明 |
|---|---|---|
| 撤销 | `Ctrl+Z` | 单元格修改 / 删除行 / 清空 / 批量修改 / 添加行列 均可撤销 |
| 恢复 | `Ctrl+Shift+Z` | 重做被撤销的操作 |

- 撤销栈上限 100 步，超出后最早的记录被丢弃
- 撤销只影响表格视图；**Ctrl+S 之前磁盘文件始终未被改动**
- 平台文本视图的 Ctrl+Z 与表格撤销栈相互独立

---

## 四、搜索（Ctrl+F）

| 操作 | 快捷键 |
|---|---|
| 打开搜索栏（表格聚焦即可，无需点搜索框） | `Ctrl+F` |
| 下一个匹配 | `Enter` / `F3` |
| 上一个匹配 | `Shift+Enter` / `Shift+F3` |
| 关闭搜索 | `Esc` 或搜索栏 ✕ 按钮 |

特性：

- **不区分大小写**的包含匹配，按当前可见行序逐行逐列扫描
- 输入防抖 300ms 后**后台线程**执行，大文件不卡界面；单次搜索匹配数有上限，超过时计数栏提示"已截断"
- 命中单元格**高亮**（非选中态覆盖底色，选中态保留选择色）
- 当前命中自动滚动到可见区域并选中；计数栏显示 `第 N / M 个`
- 选中单个单元格后按 Ctrl+F，会**用该单元格内容预填**搜索框
- 筛选 / 排序 / 数据行数变化后，若搜索栏打开则自动重新搜索

---

## 五、筛选与排序

点击**列头**触发（同一列头两个交互区域）：

| 区域 | 行为 |
|---|---|
| 最右侧**排序箭头区** | 循环排序：升序 → 降序 → 取消排序 |
| 其余区域 | 弹出**筛选弹窗**：后台统计该列值分布 → 勾选要保留的值，或输入"包含文本"模糊筛选 |

- 多列筛选可叠加；已筛选的列头显示筛选标记，排序中的列头显示 ▲ / ▼ 图标
- 筛选 / 排序只改变**视图**（行号列同步变化），不改动数据本身，也不计入撤销栈
- 行结构发生变化（删除行 / 添加行列 / 撤销）后，筛选与排序状态自动清除，避免行号映射失效
- 状态栏实时显示当前可见行数

---

## 六、保存与数据安全

| 行为 | 说明 |
|---|---|
| 保存 | `Ctrl+S`（表格聚焦时生效），异步写盘，完成前状态栏有提示 |
| 未保存提示 | 有修改未保存时状态栏红色显示；关闭文件前平台会弹确认 |
| 写回方式 | 按行偏移精确替换 `Document` 内容，不重排未修改部分，保留原文件的编码与换行符 |
| 大文件限制 | 数据源为平台 `Document`，默认 >20MB 受平台限制；当前为全量后台解析后一次换入 |

---

## 七、常见问题（FAQ）

**Q：双击 CSV 打开的还是文本视图？**
右上角编辑器切换栏选「CSV 表格」；或临时停用内置 CSV 插件的表格编辑器。

**Q：修改后磁盘文件没变？**
表格编辑只在内存中生效，按 `Ctrl+S` 保存后写盘。

**Q：筛选/排序后行号对不上原文件？**
行号列显示的是**筛选/排序后的视图行号**；清除筛选/排序（再次点击列头排序区循环到取消，或发生行结构变化时自动清除）即恢复。

**Q：Ctrl+Z 撤销了编辑还能恢复吗？**
可以，`Ctrl+Shift+Z` 恢复（100 步以内）。

**Q：文件刚生成完就打开，行数不对？**
状态栏会显示 ⚠ 警告（索引建立在半成品文件上）；生成完成后再打开一次，或触发一次编辑让其重新解析。

---

## 八、架构与实现（对应规划第 2~5 步）

| 步骤 | 实现 |
|---|---|
| 2 编辑器注册 | `CsvTableEditorProvider`（accept `.csv`，PLACE_BEFORE_DEFAULT_EDITOR，保留文本视图切换；不注册 FileType，避免与内置 CSV 支持冲突） |
| 3 表格展示 | `CsvModel` + `CsvTablePanel`：RFC 4180 解析、分隔符识别、表头检测、行号列、列宽记忆、选择复制 |
| 4 编辑写回 | 双击/回车编辑，Esc 取消；提交后 `WriteCommandAction` 按行偏移替换 Document（delta 平移后续行防串位）；含分隔符/引号/换行的值自动加引号转义 |
| 5 性能 | 解析全部在后台线程（ReadAction）+ EDT 快照换入；Document 变更 300ms 防抖重解析；编辑时内存快照同步修正偏移 |
| 增强 | `CsvDataSource` 数据源抽象（`FileSource` / `DocumentSource`）：删除行、添加行列、批量修改、独立撤销栈、全文搜索、筛选排序 |

---

## 九、已知限制 / 后续

- 规划第 5 步的"流式行索引 + 按需解析（LRU）"尚未完全落地（当前 100MB 内文件后台解析后一次换入，滚动流畅）。
- 撤销栈为插件内部实现（上限 100 步），与平台文本视图撤销独立。
- 若 PyCharm 内置 CSV 插件的表格编辑器抢占首屏，可在插件列表临时停用它，或用右上角编辑器切换选择本插件。