excel-xlsx

name	Excel / XLSX
slug	excel-xlsx-zh
version	3
homepage	https://clawhub.ai/ivangdavila/excel-xlsx
description	创建、检查和编辑 Microsoft Excel 工作簿和 XLSX 文件，支持可靠的公式、日期、数据类型、格式化、重新计算和模板保留。适用于以下场景：(1) 任务涉及 Excel 或 `.xlsx` 文件；(2) 文件包含公式、多工作表、数据验证、合并单元格或工作簿结构；(3) 日期、数字格式或类型精度要求高；(4) 工作簿需要在往返编辑后保持格式不漂移。
changelog	初始发布
metadata	{"clawdbot":{"emoji":"📗","os":["linux","darwin","win32"]}}

适用场景

当主要处理对象是 Microsoft Excel 工作簿或电子表格文件时使用，尤其涉及公式、日期、格式、合并单元格、工作簿结构或跨平台行为时。

核心规则

1. 根据任务选择工作流，而非凭习惯

• 数据分析、重塑和类似 CSV 的任务使用 pandas。
• 涉及公式、样式、多工作表、批注、合并单元格或需要保留工作簿完整性时使用 openpyxl。
• 将 CSV 视为纯数据交换格式，而非功能完整的 Excel 替代品。
• 读取数值、保留活跃工作簿和从头构建模型是三种不同的电子表格任务。

2. 日期是带有历史遗留问题的序列号

• Excel 将日期存储为序列号，而非真正的日期对象。
• 1900 日期系统包含虚假的闰日 bug，部分工作簿使用 1904 系统。
• 时间是分数天数的数据，因此格式和转换都同样重要。
• 仅日期正确还不够，如果数字格式仍然向用户显示错误信息，那就不算完成。

3. 工作簿需要保持活跃时，将计算保留在 Excel 中

• 将公式写入单元格，而不是用 Python 硬编码派生结果。
• 使用对假设单元格的引用，而不是在公式中使用魔法数字。
• 缓存的公式值可能已过时，编辑后不要盲目信任它们。
• 交付前检查复制公式是否存在错误范围、错误工作表和静默的偏移漂移。
• 绝对引用和相对引用是逻辑的一部分，因此即使复制的公式仍然"能运行"，也可能是错误的。
• 在将新公式填充到整个区块之前，先在几个代表性单元格上进行测试。
• 交付依赖分母、命名范围和前置单元格的公式之前，务必验证它们。
• 工作簿交付时应零公式错误，不应留有已知的 #REF!、#DIV/0!、#VALUE!、#NAME? 或循环引用遗留问题让用户自行修复。
• 对于模型类工作，在批注或附近备注中记录非显而易见的硬编码、假设或源数据输入。

4. 在 Excel 破坏数据类型之前先做好保护

• 长标识符、电话号码、邮政编码和前导零值通常应以文本格式存储。
• Excel 会在超过 15 位数字时静默截断数值精度。
• 混合文本-数字列在读取和写入时都需要显式处理。
• 科学计数法、自动解析的日期和被去除的前导零是常见的数据损坏，而非外观问题。

5. 修改内容之前先保护工作簿结构

• 现有模板优先于通用样式建议。
• 合并范围中只有左上角单元格存储值。
• 隐藏行、隐藏列、命名范围和外部引用仍然可能影响公式和输出。
• 共享字符串、定义名称和工作表级别的约定即使可见单元格看起来很简单也可能很重要。
• 为新填充的单元格匹配样式，而不是悄悄引入新的视觉系统。
• 如果工作簿是模板，除非任务明确要求更改，否则应保留工作表顺序、列宽、冻结窗格、筛选器、打印设置、数据验证和视觉约定。
• 条件格式、筛选器、打印区域和数据验证通常承载业务含义，即使用户只提到了数字。
• 如果没有现有的样式指南且文件是模型，请保持可编辑输入与公式在视觉上可区分，但绝不要为了强制通用风格而覆盖已建立的模板。

6. 交付前重新计算并审查

• 如果接收者需要当前值，仅公式字符串是不够的。
• openpyxl 保留公式但不计算它们。
• 验证不存在残留的 #REF!、#DIV/0!、#VALUE!、#NAME? 或循环引用问题。
• 如果布局重要，在完成任务前渲染或视觉审查工作簿。
• 注意读取模式：以仅值模式打开工作簿然后保存可能会将公式展平为静态值。
• 如果假设或硬编码覆盖必须保留，请使其足够明显，以便下一位编辑者能够审计工作簿。

7. 根据文件大小调整工作流

• 大型工作簿可能因为无聊的原因失败：内存激增、空行填充和全工作表读取缓慢。
• 当文件大到一次性加载变得脆弱时，使用流式或分块读取。
• 大文件工作流还需要更窄的读取范围、显式的数据类型和工作表定位，以避免意外损坏。

常见陷阱

• 读取时的类型推断可能会将数字保留为文本或将 ID 转换为损坏的数值。
• 不同工具之间的列索引方式不同，因此生成的公式中偏移错误很常见。
• 单元格中的换行需要启用自动换行才能正确显示。
• 源文件移动时外部引用容易断裂。
• 旧版 Excel 工作流中的密码保护并不是真正的安全措施。
• .xlsm 可以包含宏，.xls 仍然是更受限的旧版格式。
• 大文件可能需要流式读取或更谨慎的内存处理。
• Google Sheets 和 LibreOffice 可能会以不同于 Excel 的方式重新解释日期、公式或样式。
• FILTER、XLOOKUP、SORT 或 SEQUENCE 等动态数组或较新的 Excel 函数在旧版查看器中可能会失败或降级。
• 工作簿可能看起来正常，但仍然携带着上一次重新计算的过时缓存值。
• 保存错误的工作簿视图可能会用缓存值替换公式，从而悄无声息地破坏活跃模型。
• 不检查相对引用就复制公式可能会将一个错误范围推送到整个区块。
• 隐藏工作表、命名范围、数据验证和合并区域经常包含在快速浏览中不可见的业务逻辑。
• 工作簿可能在数值上看起来正确，但因为筛选器、条件格式、打印设置或数据验证被去除而仍然不合格。
• 工作簿可能在数值上正确，但因为自动换行文本、被截断的标签或过窄的列从未被审查而仍然在视觉上失败。