python 的 python-docx 无法直接访问或修改 word 中嵌入的 excel 对象；需借助 win32com 自动化 word 和 excel 应用，通过“外部编辑 + 占位符替换”方式实现动态更新。
python
的 python-docx 无法直接访问或修改
word
中嵌入的
excel
对象；需借助 win32com 自动化 word 和 excel 应用，通过“外部编辑 + 占位符替换”方式实现动态更新。
在实际办公自动化场景中，常需动态生成含结构化数据的 Word 报告——例如将计算完成的 Excel 表格插入指定位置。但需明确一个关键限制：
python-docx（即 python-docx 库）完全不支持读取、解析或编辑 OLE 嵌入对象（如嵌入式 Excel 表格）
。调用 doc.tables 或 doc.inline_shapes 时，嵌入的 Excel 表格不会出现在其中，因其在 DOCX 文件结构中属于 word/embeddings/ 下的二进制 OLE 包，而非标准表格或内联图形元素。
因此，推荐采用「解耦编辑 + 自动化插入」的工作流：
独立维护 Excel 数据
：使用 openpyxl 或 pandas 编辑 .xlsx 文件（支持公式、样式、多 sheet 操作）；
Word 中预设文本占位符
（如 [excel_table]），不依赖嵌入对象；
用 win32com.client 启动真实 Word 进程
，定位占位符并以 OLE 对象形式插入已更新的 Excel 文件。
以下为完整可运行示例：
✅
使用前准备
：
Python 3.14.3
微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。
下载
立即学习
“
Python免费学习笔记（深入）
”；
安装依赖：pip install pywin32；
确保系统已安装 Microsoft Excel 和 Word（win32com 依赖 Office COM 接口）；
Word 文档中手动输入 [excel_table]（普通段落文本，勿加粗/超链接/置于文本框内）；
Excel 文件需为 .xlsx 格式，且路径不含中文或特殊字符（推荐使用 os.path.abspath() 规范路径）。
⚠️
注意事项
：
win32com 是 Windows 专属方案，macOS/Linux 不支持；跨平台需求建议改用「导出为图片/PDF 表格 + 插入 Word」或重构为纯文本表格（牺牲交互性）；
避免在循环中高频调用此函数（启动 Word 进程开销较大），建议批量处理后统一插入；
若需保留 Excel 公式或双击可编辑能力，请确保 LinkToFile=False（默认值），否则插入的是静态快照。
该方法虽绕过直接编辑嵌入对象的限制，却兼顾了开发效率（复用 openpyxl）、最终效果（原生 Excel 交互）与工程可控性，是当前最稳健的生产级实践。
import win32com.client
def insert_excel_table_into_word(doc_path: str, excel_path: str, placeholder: str = "[excel_table]"):
"""
将指定 Excel 文件作为嵌入式表格插入 Word 文档的占位符位置
:param doc_path: Word 文档绝对路径
:param excel_path: Excel 文件绝对路径（.xlsx）
:param placeholder: Word 文档正文中需被替换的纯文本标记
"""
word = win32com.client.Dispatch("Word.Application")
word.Visible = False # 可选：设为 True 调试时可见
try:
doc = word.Documents.Open(doc_path)
rng = doc.Content
# 查找占位符
found = rng.Find.Execute(FindText=placeholder)
if not found:
raise ValueError(f"未找到占位符 '{placeholder}'，请确认其存在于文档正文（非页眉/页脚/文本框）")
# 清空占位符并折叠光标至起始点
rng.Text = ""
rng.Collapse(0) # 0 = wdCollapseStart
# 插入 Excel OLE 对象（不链接、不显示为图标）
ole_obj = rng.InlineShapes.AddOLEObject(
ClassType="Excel.Sheet",
FileName=excel_path,
LinkToFile=False,
DisplayAsIcon=False
)
# 自适应宽度：匹配页面可用宽度（扣除左右页边距）
page_width = doc.PageSetup.PageWidth - (doc.PageSetup.LeftMargin + doc.PageSetup.RightMargin)
if ole_obj.Width > page_width - 10:
ole_obj.Width = page_width - 10
doc.Save()
print("✅ Excel 表格已成功插入并保存。")
finally:
doc.Close() if 'doc' in locals() else None
word.Quit()