格式修复工具¶

本页面介绍如何使用Symphra Excel的格式修复工具来确保.xlsx文件的兼容性和正确性。

概述¶

format_fix模块是一个专门用于修复Excel文件格式的工具，通过在.xlsx压缩包层面工作，对XML结构进行精确修复，确保文件在各种应用程序中的兼容性。

主要功能¶

1. 锚点标签修复 (prefix_drawing_anchors)¶

为绘图部分的xdr命名空间进行规范化： - 统一根标签wsDr为xdr:wsDr - 确保存在xmlns:xdr命名空间属性 - 为锚点标签添加xdr:前缀 - 为其他xdr元素补全前缀

2. 关系路径规范化 (normalize_sheet_rel_targets)¶

规范化worksheet关系文件中的Drawing Target路径： - 将绝对路径转换为相对路径 - 统一drawings/...为../drawings/... - 确保兼容性

3. 图片路径规范化 (normalize_drawing_rel_targets)¶

规范化drawing关系文件中的Image Target路径： - 规范化图片资源路径为相对路径 - 统一media/...为../media/... - 避免路径错误

4. editAs属性修复¶

为oneCellAnchor添加editAs="oneCell"属性： - 确保图片正确锚定到单元格 - 解决vue-office/excel等预览工具中图片位置漂移的问题

基本用法¶

简单修复¶

最常用的方式，修复文件后覆盖原文件：

from symphra_excel.utils.format_fix import fix_xlsx

# 修复文件并覆盖原文件
fix_xlsx("output.xlsx")

指定输出路径¶

修复后保存为新文件：

from symphra_excel.utils.format_fix import fix_xlsx

# 修复并保存为新文件
fix_xlsx("input.xlsx", "output_fixed.xlsx")

自定义配置¶

使用FormatFixConfig自定义修复规则：

from symphra_excel.utils.format_fix import fix_xlsx, FormatFixConfig

# 创建配置
config = FormatFixConfig(
    prefix_drawing_anchors=True,        # 启用锚点修复
    normalize_sheet_rel_targets=True,   # 启用工作表关系修复
    normalize_drawing_rel_targets=True, # 启用图片关系修复
    ensure_xml_decl=True,               # 确保XML声明
)

# 应用修复
fix_xlsx("input.xlsx", "output.xlsx", config=config)

完整示例¶

示例1: 标准图片处理流程¶

from symphra_excel import Workbook
from symphra_excel.images.image_processor import CellImageOptions
from symphra_excel.utils.format_fix import fix_xlsx

# 创建工作簿并插入图片
wb = Workbook()
sheet = wb.create_worksheet("报告")

# 插入图片
options = CellImageOptions(
    anchor_type="oneCell",
    margin=8
)
sheet.insert_image_in_cell("logo.png", "A1", options=options)

# 保存文件
wb.save("report.xlsx")

# 修复格式（重要！）
fix_xlsx("report.xlsx")

示例2: 批量修复多个文件¶

from symphra_excel.utils.format_fix import fix_xlsx
import os

file_list = [
    "report1.xlsx",
    "report2.xlsx",
    "report3.xlsx"
]

for filename in file_list:
    if os.path.exists(filename):
        print(f"修复文件: {filename}")
        report = fix_xlsx(filename)
        print(f"  - 应用的规则: {report.rules_applied}")
        print(f"  - 修改的条目: {len(report.changed_entries)}")

示例3: 只修复特定问题¶

如果只需要修复特定问题，可以禁用其他规则：

from symphra_excel.utils.format_fix import fix_xlsx, FormatFixConfig

# 只修复锚点标签，不修改路径
config = FormatFixConfig(
    prefix_drawing_anchors=True,
    normalize_sheet_rel_targets=False,
    normalize_drawing_rel_targets=False,
)

fix_xlsx("input.xlsx", "output.xlsx", config=config)

修复报告 (FixReport)¶

fix_xlsx()函数返回一个FixReport对象，包含详细的修复信息：

from symphra_excel.utils.format_fix import fix_xlsx

report = fix_xlsx("input.xlsx", "output.xlsx")

print(f"输入文件: {report.input_path}")
print(f"输出文件: {report.output_path}")
print(f"就地修复: {report.in_place}")
print(f"应用的规则: {report.rules_applied}")
print(f"修改的条目数: {len(report.changed_entries)}")
print(f"修改的条目: {report.changed_entries}")
print("\n详细日志:")
for log in report.logs:
    print(f"  {log}")

配置详解¶

FormatFixConfig 参数¶

参数	类型	默认值	说明
`prefix_drawing_anchors`	bool	True	为锚点标签添加xdr前缀
`normalize_sheet_rel_targets`	bool	True	规范化worksheet关系Target路径
`normalize_drawing_rel_targets`	bool	True	规范化drawing关系Target路径
`normalize_workbook_rel_targets`	bool	True	规范化workbook关系Target路径
`ensure_xml_decl`	bool	True	确保XML声明头
`reorder_wsdr_xmlns`	bool	True	规范xdr:wsDr命名空间属性顺序
`reorder_relationship_attrs`	bool	True	统一Relationship属性顺序

最佳实践¶

✅ 推荐做法¶

# 1. 总是调用fix_xlsx（特别是插入图片后）
from symphra_excel import Workbook
from symphra_excel.utils.format_fix import fix_xlsx

wb = Workbook()
# ... 添加内容 ...
wb.save("output.xlsx")
fix_xlsx("output.xlsx")  # 重要！

# 2. 使用自定义配置
from symphra_excel.utils.format_fix import FormatFixConfig, fix_xlsx

config = FormatFixConfig(
    prefix_drawing_anchors=True,  # 修复图片锚点
    normalize_sheet_rel_targets=True,  # 修复路径
    ensure_xml_decl=True,  # 确保XML格式
)

fix_xlsx("input.xlsx", "output.xlsx", config=config)

# 3. 检查修复报告
report = fix_xlsx("input.xlsx", "output.xlsx")
if report.changed_entries:
    print(f"修复了 {len(report.changed_entries)} 个问题")

❌ 避免的做法¶

# 1. 不调用fix_xlsx
wb = Workbook()
wb.save("output.xlsx")
# 缺少 fix_xlsx("output.xlsx")

# 2. 修复前文件被占用
wb = Workbook("output.xlsx")  # 文件已打开
fix_xlsx("output.xlsx")  # 可能失败

# 3. 忽略修复报告
fix_xlsx("input.xlsx", "output.xlsx")
# 应该检查 report.changed_entries 是否为空

常见问题¶

Q: 什么时候需要调用fix_xlsx？¶

A: 建议在以下情况后都调用： - 插入图片后 - 处理包含图片的模板后 - 从字节数据创建工作簿后 - 任何可能修改XML结构后

Q: fix_xlsx会修改原始数据吗？¶

A: 不会。format_fix工具只修改XML结构（标签、属性、路径），不触及单元格值、公式或样式。

Q: 修复后文件大小会增加吗？¶

A: 通常会增加很小（几字节到几KB），因为添加了命名空间前缀和XML声明。

Q: 修复失败怎么办？¶

A: check修复报告的日志：

report = fix_xlsx("input.xlsx", "output.xlsx")
for log in report.logs:
    print(log)  # 查看详细错误信息

工作原理¶

format_fix模块通过zipfile在.xlsx压缩包层面工作：

读取.xlsx文件（ZIP格式）
解压并解析相关XML文件
使用正则表达式精确修改XML内容
重新打包为.xlsx文件
生成详细修复报告

这确保了： - 与核心业务逻辑解耦 - 不破坏原始数据 - 提供可追踪的修改日志 - 支持可配置的修复规则