xlsx

Xlsx 技能

使用 Python 和 openpyxl 处理 Excel .xlsx 工作簿：创建包含公式和图表的多工作表样式化工作簿，检查或导出已有文件，编辑单元格和结构，以及与 CSV 相互转换。所有辅助脚本都是 argparse 命令行工具，会输出 JSON，并使用显式 UTF-8 输入/输出。

适用场景

• 创建 .xlsx 报告：多个工作表、数字格式、样式、合并单元格、冻结窗格、自动筛选、条件格式、图表、数据验证下拉列表、原生 Excel 表格、定义名称、超链接、单元格批注、工作表保护。
• 读取工作簿：工作表清单、将数据导出为 JSON 或 CSV、列出公式与缓存值、批注、定义名称、表格。
• 编辑现有文件：设置单元格、追加行、插入/删除行列（通过 xlsx_restructure.py 感知引用）、复制/重命名工作表、表格、名称、批注、保护。
• 通过 LibreOffice 无界面重新计算公式（xlsx_recalc.py）。
• 支持类型推断和非 UTF-8 编码的 CSV 互操作。
• 不适用于旧版 .xls 二进制格式（请先使用 LibreOffice 转换：soffice --headless --convert-to xlsx old.xls）。

前置条件

• Python 3.10+ 和 openpyxl（pip install openpyxl）。无需其他第三方软件包；其余功能均使用标准库。
• 可选：用于无界面重新计算或格式转换的 LibreOffice（soffice）。

运行方法

使用此技能 scripts/ 目录中的 terminal 工具运行辅助脚本（每个脚本都支持 --help）：

python scripts/xlsx_create.py spec.json report.xlsx   # build from JSON spec
python scripts/xlsx_read.py report.xlsx --sheets      # inventory
python scripts/xlsx_read.py report.xlsx --json --sheet Data
python scripts/xlsx_read.py report.xlsx --formulas
python scripts/xlsx_edit.py report.xlsx --sheet Data --set B2=42 --recalc
python scripts/xlsx_restructure.py report.xlsx --sheet Data --insert-rows 3:2
python scripts/xlsx_recalc.py report.xlsx
python scripts/csv_to_xlsx.py data.csv out.xlsx --encoding utf-8
python scripts/xlsx_to_csv.py report.xlsx out.csv --sheet Data

使用 write_file 编写 JSON 规范，通过 read_file 或直接从标准输出检查脚本的 JSON 输出。

快速参考

任务	命令
根据规范创建工作簿	xlsx_create.py spec.json out.xlsx
工作表名称和尺寸	xlsx_read.py f.xlsx --sheets
将工作表导出为 JSON	xlsx_read.py f.xlsx --json --sheet S
将工作表导出为 CSV	xlsx_read.py f.xlsx --csv --out d.csv
列出公式和缓存值	xlsx_read.py f.xlsx --formulas
设置单元格/公式	xlsx_edit.py f.xlsx --set "A1==SUM(B:B)"
追加一行	xlsx_edit.py f.xlsx --append '[1,"x",true]'
插入 2 行，不移动引用	xlsx_edit.py f.xlsx --insert-rows 3:2
插入 2 行，移动引用	xlsx_restructure.py f.xlsx --insert-rows 3:2
删除一列并移动引用	xlsx_restructure.py f.xlsx --delete-cols B
创建原生表格	xlsx_edit.py f.xlsx --add-table Sales:A1:C9
在表格中追加内容	--table-append 'Sales=["West",5]'
列出表格	xlsx_edit.py f.xlsx --list-tables
定义名称	--define-name "Rates='Data'!$B$2:$B$9" / --delete-name Rates / xlsx_read.py f.xlsx --names
超链接	`--hyperlink "A1=https://example.com
单元格批注	`--note "B2=Check this
保护工作表（参见注意事项）	--protect your-password --unlock B2:B9
通过 LibreOffice 重新计算	xlsx_recalc.py f.xlsx
复制/重命名工作表	--copy-sheet Src:New --rename-sheet Old:New
打开时强制重新计算	xlsx_edit.py f.xlsx --recalc
CSV 转为样式化 xlsx	csv_to_xlsx.py in.csv out.xlsx
xlsx 转为 CSV	xlsx_to_csv.py f.xlsx out.csv --encoding utf-8

操作流程

1. 创建：编写 JSON 规范（架构说明见 xlsx_create.py --help 和其文档字符串）。每个工作表支持 rows（标量或带样式的单元格对象）、稀疏的 cells 覆盖项、 column_widths、row_heights、merges、freeze_panes、 autofilter、conditional_formats（cell_is 规则和色阶）、 charts（基于单元格范围的条形图／折线图／饼图）、 validations（列表下拉菜单）、tables（带样式名称的原生 Excel 表格） 和 protection。工作簿级别的 defined_names 将名称映射到引用。 单元格对象还可使用 hyperlink 和 note。 类型化值：JSON 数字／布尔值 会直接传递；日期使用 {"value": "2026-01-31", "type": "date"}。 数字格式使用 Excel 格式字符串：货币 "$#,##0.00"、 百分比 "0.0%"、日期 "yyyy-mm-dd"。
2. 公式：在规范中使用 "formula": "SUM(B2:B9)" 设置，或在编辑器中使用 --set "C1==SUM(A:A)"。写入公式时，添加 "full_calc_on_load": true（规范）或 --recalc（编辑器）；这会设置工作簿的 fullCalcOnLoad 标志，以便 Excel／LibreOffice 在打开时重新计算所有内容。 openpyxl 本身永远不会计算公式。
3. 读取：使用 --sheets 查看清单（名称、尺寸、合并 范围、图表数量、表格、保护设置、定义名称），使用 --json／--csv 获取数据，使用 --formulas 配对显示每个公式字符串及其缓存结果， 使用 --notes 查看单元格批注，使用 --names 查看定义名称。缓存结果 仅在文件最近一次由实际电子表格应用保存时才存在； 由 openpyxl 新建的文件在该处会返回 null。要在无界面环境中生成结果， 运行 xlsx_recalc.py file.xlsx（使用 LibreOffice；若缺少 soffice，则打印 {"recalculated": false, ...} 并以退出码 0 结束），然后使用 --data-only 重新加载。
4. 编辑：xlsx_edit.py 会先应用重命名／复制，再进行 行／列结构更改，最后执行 --set／--append。除非指定 --out，否则会原位编辑 文件——如需保留原文件，请先复制。
5. 重构结构：对于包含公式、 合并单元格、表格或筛选器的工作表，执行插入／删除操作时，请改用 xlsx_restructure.py，而非 xlsx_edit.py。 它会重写所有工作表上的公式引用 （绝对 $ 引用、范围、跨工作表引用），移动合并单元格、 自动筛选、冻结窗格、数据验证和条件格式 范围、表格引用、定义名称以及行／列尺寸，然后打印一份包含 not_shifted 列表的 JSON 报告。 规则和限制见：references/restructuring.md。
6. CSV 互操作：csv_to_xlsx.py 会按单元格推断 int／float／bool／ISO 日期类型， 并设置标题行样式；xlsx_to_csv.py 会写入 ISO 日期，空单元格则写为空字符串。两者默认使用 UTF-8， 并接受 --encoding（例如，用于添加适合 Excel 的 BOM 的 utf-8-sig， 以及用于旧版 Windows 导出的 cp1252）。

转换为 PDF

LibreOffice 可在无界面环境中完成转换（也适用于单个工作表的 CSV 导出）：

soffice --headless --convert-to pdf report.xlsx --outdir out/
soffice --headless --convert-to csv report.xlsx --outdir out/  # 1st sheet only

CSV 中只会包含第一个工作表；要导出其他工作表，请使用 xlsx_to_csv.py --sheet NAME。如果缺少 soffice，请安装 LibreOffice，或将文件交给用户，暂不转换。

注意事项

• openpyxl 不会计算。 只有通过 load_workbook(path, data_only=True) 才能获取公式结果，而且仅当文件此前由 Excel/LibreOffice 保存过时才行。否则结果为 None。
• xlsx_edit.py 的插入/删除不会移动引用（这是 openpyxl 的原始行为）。请改用 xlsx_restructure.py，它会移动引用；但即使如此，也无法移动图表锚点、图像或条件格式 RULE 公式。请查看其 JSON 报告中的 not_shifted 列表和 references/restructuring.md。
• 工作表保护并非安全措施。 --protect 会设置标准的 xlsx 工作表保护哈希：它只会向行为规范的应用提示“不要编辑此内容”，仅此而已。任何人都可以通过编辑压缩包中的 XML，或在 LibreOffice 中取消勾选来移除保护。切勿依赖它来保证机密性或完整性；它不会加密任何内容。
• 使用 data_only=True 加载后再保存会悄悄丢弃所有公式（缓存值会替代公式）。除非这正是你的目的，否则切勿保存以这种方式加载的工作簿。
• 加载时会移除图表/图像：openpyxl 无法往返保留图表，因此编辑含图表的工作簿并保存会导致图表丢失。请在编辑后重新添加图表，或避免重新保存含图表的文件。
• CSV 区域设置陷阱：始终传入显式编码（脚本已处理），并记住欧洲 CSV 通常使用 ; 作为分隔符、使用逗号作为小数点——请使用 --delimiter ';'，并预期像 "12,5" 这样的内容仍会作为字符串保留。
• 日期属于 datetime：Excel 将日期存储为序列号；openpyxl 会返回 datetime/date 对象。此处的转储会输出 ISO 字符串。
• 工作表名称最多 31 个字符，且不能包含 [ ] : * ? / \。

验证

• 创建后：运行 xlsx_read.py out.xlsx --sheets，确认工作表名称、维度、合并区域和图表数量符合预期。
• 使用 --json 转储数据，并与源值进行比较。
• 编辑后：重新转储修改过的区域；如果写入了公式，请确认 --formulas 会列出这些公式，且已应用 --recalc。
• 运行 xlsx_restructure.py 后：阅读其 JSON 报告，然后重新运行 --formulas 和 --sheets，确认引用和区域已按预期调整。
• 如需进行完整的视觉检查，请在 LibreOffice 中打开： soffice --headless --convert-to pdf out.xlsx，并检查生成的 PDF。