Python操作Word书签：Free Spire.Doc替换与插图

脚本专家

Word 书签可以理解为文档里的命名变量：先在模板中标记位置，程序运行时按名称写入文本、表格或图片。使用 Free Spire.Doc for Python 可以把“模板 + 数据 = 文档”的流程自动化，定位比全文查找替换更精确，也支持嵌套书签。先安装：

2. pip install spire.doc.free

复制代码

一、创建书签模板

书签由 AppendBookmarkStart 和 AppendBookmarkEnd 成对定义，名称必须一致，End 位于 Start 之后。下面创建报告模板，并在待填充位置插入书签：

2. from spire.doc import *
3. from spire.doc.common import *
5. document = Document()
6. section = document.AddSection()
7. p = section.AddParagraph()
8. p.AppendText('Project Phase Report')
9. p.ApplyStyle(BuiltinStyle.Heading1)
10. p.Format.HorizontalAlignment = HorizontalAlignment.Center
11. fields = [
12.     ('Project Name: ', 'ProjectName'),
13.     ('Client: ', 'ClientName'),
14.     ('Report Date: ', 'ReportDate'),
15.     ('Project Phase: ', 'ProjectPhase'),
16. ]
17. for label, bm in fields:
18.     p = section.AddParagraph()
19.     p.AppendText(label)
20.     p.AppendBookmarkStart(bm)
21.     p.AppendText('(to be filled)')
22.     p.AppendBookmarkEnd(bm)
23. # Summary、MilestoneTable、RiskLevel、RiskDetail、Signature 同理添加
24. document.SaveToFile('template.docx', FileFormat.Docx)
25. document.Close()

复制代码

风险与建议部分可用嵌套书签：外层 RiskSection 包裹内层 RiskLevel 和 RiskDetail。内层可单独替换，外层也可整体操作。生成模板后包含 10 个书签：ProjectName、ClientName、ReportDate、ProjectPhase、Summary、MilestoneTable、RiskSection、RiskLevel、RiskDetail、Signature。

二、替换书签内容

BookmarksNavigator 是书签操作核心类。MoveToBookmark 按名称定位，ReplaceBookmarkContent 替换书签覆盖的内容。第二个参数控制是否保留原有字符格式：False 使用默认格式，True 继承书签内原文本的字体、字号、颜色等属性。

2. doc = Document()
3. doc.LoadFromFile('template.docx')
4. navigator = BookmarksNavigator(doc)
5. navigator.MoveToBookmark('ProjectName')
6. navigator.ReplaceBookmarkContent('Smart City Data Platform Phase II', False)
7. navigator.MoveToBookmark('ClientName')
8. navigator.ReplaceBookmarkContent('Orient Municipal Group', False)
9. navigator.MoveToBookmark('ReportDate')
10. navigator.ReplaceBookmarkContent('September 28, 2026', False)
11. navigator.MoveToBookmark('ProjectPhase')
12. navigator.ReplaceBookmarkContent('Phase II - Mid-term Acceptance', False)
13. navigator.MoveToBookmark('Summary')
14. navigator.ReplaceBookmarkContent(
15.     'This phase completed a comprehensive upgrade of the data collection module...', False)
16. navigator.MoveToBookmark('RiskLevel')
17. navigator.ReplaceBookmarkContent('Medium', False)
18. doc.SaveToFile('step2_text.docx', FileFormat.Docx)
19. doc.Close()

复制代码

示例摘要对应的事实数据包括：新增 320 个传感器接入点，日吞吐从 1.2 亿提升到 3.5 亿条记录，集成交通、环境、安全、水务、市政 5 个子系统，API 平均响应 87ms，可用性 99.6%，中期验收 14 项通过 13 项，剩余实时告警延迟预计 10 月 15 日达标。风险详情可写 Kafka 集群高峰消息堆积，峰值延迟 4.2 秒，超过 2 秒 SLA，扩容到 6 节点预计 10 月 10 日完成。嵌套书签内层可独立定位替换，MoveToBookmark 不关心嵌套层级。

替换为表格时，先构建 Table，再用 TextBodyPart 包装后传给 ReplaceBookmarkContent：

2. table = Table(doc, True)
3. table.ResetCells(6, 4)
4. data = [
5.     ['Milestone', 'Planned Date', 'Actual Date', 'Status'],
6.     ['Requirements', '2026-07-15', '2026-07-14', 'Completed'],
7.     ['Architecture', '2026-07-30', '2026-07-30', 'Completed'],
8.     ['Core Development', '2026-08-31', '2026-09-02', 'Completed (2-day delay)'],
9.     ['Integration Test', '2026-09-20', '—', 'In Progress (85%)'],
10.     ['Mid-term Review', '2026-09-28', '2026-09-28', 'Passed'],
11. ]
12. for i in range(6):
13.     for j in range(4):
14.         cell = table.Rows[i].Cells[j]
15.         para = cell.AddParagraph()
16.         txtRange = para.AppendText(data[i][j])
17.         if i == 0:
18.             txtRange.CharacterFormat.Bold = True
19. navigator = BookmarksNavigator(doc)
20. navigator.MoveToBookmark('MilestoneTable')
21. part = TextBodyPart(doc)
22. part.BodyItems.Add(table)
23. navigator.ReplaceBookmarkContent(part)
24. doc.SaveToFile('step3_table.docx', FileFormat.Docx)
25. doc.Close()

复制代码

Table(doc, True) 的第二个参数启用固定布局模式，列宽由 ResetCells 自动分配。TextBodyPart 用于承载表格、多段落等结构化内容。

三、在书签位置插入图片

AppendPicture 必须在段落上调用，而书签位置不一定有现成空段落。可先在临时 section 中创建带图片的段落，再用 InsertParagraph 插入书签位置，最后移除临时 section：

2. doc = Document()
3. doc.LoadFromFile('step3_table.docx')
4. bn = BookmarksNavigator(doc)
5. bn.MoveToBookmark('Signature', True, True)
6. section0 = doc.AddSection()
7. paragraph = section0.AddParagraph()
8. paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center
9. picture = paragraph.AppendPicture('signature.png')
10. picture.Width = 150.0
11. picture.Height = 150.0
12. bn.InsertParagraph(paragraph)
13. doc.Sections.Remove(section0)
14. doc.SaveToFile('step4_image.docx', FileFormat.Docx)
15. doc.Close()

复制代码

MoveToBookmark 的后两个 True 分别控制是否区分大小写、是否向前搜索。Width 和 Height 单位为磅，150 磅约等于 5.3 厘米，适合签章图片；横幅图片可按比例设置，如 Width=400.0、Height=100.0。

四、提取与列举书签内容

document.Bookmarks 是书签集合，支持按索引和按名称访问：

2. doc = Document()
3. doc.LoadFromFile('step4_image.docx')
4. for i in range(doc.Bookmarks.Count):
5.     bm = doc.Bookmarks[i]
6.     print(f'{i+1}. {bm.Name}')
7. bookmark = doc.Bookmarks['ProjectName']
8. print(bookmark.Name)

复制代码

GetBookmarkContent 返回书签内容对象，遍历 BodyItems 可取出文本。若书签包含表格，还需用 isinstance 判断 Table 类型：

2. navigator = BookmarksNavigator(doc)
3. targets = ['ProjectName', 'ClientName', 'Summary', 'RiskLevel', 'RiskDetail']
4. for name in targets:
5.     navigator.MoveToBookmark(name)
6.     content = navigator.GetBookmarkContent()
7.     text = ''
8.     for i in range(content.BodyItems.Count):
9.         item = content.BodyItems.get_Item(i)
10.         if isinstance(item, Paragraph):
11.             for j in range(item.ChildObjects.Count):
12.                 child = item.ChildObjects.get_Item(j)
13.                 if isinstance(child, TextRange):
14.                     text += child.Text
15.     display = text[:80] + '...' if len(text) > 80 else text
16.     print(f'[{name}] {display}')

复制代码

五、删除书签与书签内容

只删除书签标记、保留内容，可用 Bookmarks.Remove：

2. doc = Document()
3. doc.LoadFromFile('step4_image.docx')
4. bookmark = doc.Bookmarks['RiskSection']
5. doc.Bookmarks.Remove(bookmark)
6. doc.SaveToFile('step6a_remove_mark.docx', FileFormat.Docx)
7. doc.Close()

复制代码

删除后剩余 9 个书签，适合报告定稿时清理标记。若要同时删除书签及其内容，需要定位 BookmarkStart 和 BookmarkEnd 在段落子对象中的索引，再循环移除两者之间的元素：

2. bookmark = doc.Bookmarks['Signature']
3. para = bookmark.BookmarkStart.Owner
4. startIndex = para.ChildObjects.IndexOf(bookmark.BookmarkStart)
5. para2 = bookmark.BookmarkEnd.Owner
6. endIndex = para2.ChildObjects.IndexOf(bookmark.BookmarkEnd)
7. for i in range(startIndex + 1, endIndex):
8.     para.ChildObjects.RemoveAt(startIndex + 1)
9. doc.Bookmarks.Remove(bookmark)
10. doc.SaveToFile('step6b_remove_content.docx', FileFormat.Docx)
11. doc.Close()

复制代码

RemoveAt 后列表会前移，因此循环中始终删除 startIndex + 1 位置，而不是递增索引。删除后同样剩余 9 个书签。

六、关键类与方法

常用类包括 Document、Section、Paragraph、TextRange、Table、TextBodyPart、BookmarksNavigator、Bookmarks。常用方法包括 AppendBookmarkStart/AppendBookmarkEnd、MoveToBookmark、ReplaceBookmarkContent、GetBookmarkContent、InsertParagraph、Bookmarks.Remove。

适用场景主要是项目报告、月报、合同、通知等模板化文档。典型流程是：创建带书签模板、替换文本书签、替换表格书签、在书签位置插入图片、保存输出；定稿阶段再按需删除书签标记。嵌套书签适合一个区域内多个字段独立填充，格式保留参数适合占位文本已预设样式的模板。需要注意：Start 与 End 必须成对且同名；MoveToBookmark 按名称查找；删除元素时注意集合索引变化；图片尺寸单位为磅。

热心网友7

感谢分享，步骤写得很清楚。模板阶段用 AppendBookmarkStart 和 AppendBookmarkEnd 成对定义书签、名称保持一致，以及外层 RiskSection 包内层 RiskLevel、RiskDetail 的嵌套做法，很适合做报告类文档。替换部分里 BookmarksNavigator 的 MoveToBookmark 加 ReplaceBookmarkContent 很直观，第二个参数控制是否保留原格式这点对模板排版很重要。表格先建 Table 再用 TextBodyPart 包装传入，也让人知道书签里不只是能填文本。 不过帖子最后 Milestone 表格好像没贴完，标题提到的插图部分也还没看到。如果方便的话，想继续看图片插入书签以及嵌套书签整体替换的完整示例。

热心网友3

书签这套思路确实比全文查找替换稳得多，模板改版之后不用重写定位逻辑，这点很关键。 有几个地方想请教一下： 一是 ReplaceBookmarkContent 执行完之后，书签本身还在不在？如果还在，那同一份 document 上依次替换其余书签应该不会有冲突；但要是书签被吃掉，后面再有引用同一位置的操作就得改顺序了。之前用别的库踩过这个坑，替换完定位就失效。 二是嵌套书签那段，内层能独立定位这点很有用。不过如果先把外层 RiskSection 整体替换了，里层的 RiskLevel 和 RiskDetail 还能再进去改吗，还是必须从内到外按顺序来？感觉这个顺序问题很容易在生产里出岔子。 三是建议模板本身也脚本生成，别让人在 Word 里手工调。手工编辑最容易动的就是书签名字，改一个字符或者误删一个，运行时直接报找不到，排查起来还绕。 另外免费版好像对段落数或者表格数有上限，你这个 10 个书签的模板肯定没问题，但要是批量生成几十上百页的报告，最好先压测一下，确认不会被截断。 最后图片插入那段正文好像断了，方便的话补一下用书签占位再塞图的做法，正好跟表格替换那部分对应起来，这块应该是很多人最想看的。

热心网友3

感谢分享，这套用书签做模板填充的思路很清晰。用 AppendBookmarkStart 和 AppendBookmarkEnd 在模板里埋点，再通过 BookmarksNavigator 的 MoveToBookmark 和 ReplaceBookmarkContent 填充，确实比全文查找替换更稳，尤其适合报告类文档反复生成。 嵌套书签 RiskSection 包 RiskLevel 和 RiskDetail 这点很实用，内层能单独替换，外层也能整体处理，灵活性挺高。替换文本时第二个参数控制是否保留原格式，这个细节讲得也明白，实际做模板时很容易忽略。表格替换先用 Table 构建、再用 TextBodyPart 包装后传给 ReplaceBookmarkContent，这个步骤也很关键。 看正文里的 MilestoneTable 数据似乎还没贴完，期待后续把完整表格示例和插图部分补上，特别是书签位置插入图片的写法。整体很实用，先收藏学习了。