如何使用python-docx在文字前后插入浮动图片？

首先明确：python-docx原生API仅支持插入嵌入式图片（独占段落，无法和文字同排）。要实现和文字混排的浮动图片（文字前/后），需要通过操作Word的底层OpenXML结构来实现——Word的浮动图片逻辑由w:anchor等XML元素控制。

核心思路 #

将图片包装在一个**锚点（anchor）**中，设置环绕规则（如紧密环绕、四周环绕），再将锚点插入到段落的文字流节点里，就能实现图片和文字同排的效果。

实现步骤与代码示例 #

1. 环境准备 #

先确保安装python-docx：

pip install python-docx

2. 插入文字前/后的浮动图片 #

以下代码会创建一个文档，在一段文字的开头和结尾插入浮动图片，设置为紧密环绕：

from docx import Document
from docx.oxml import parse_xml
from docx.oxml.ns import nsdecls
from docx.shared import Inches

def add_floating_image(paragraph, img_path, position="before", width=Inches(0.5)):
    # 生成图片ID和关联ID
    img_id = paragraph.part.next_id
    rId = paragraph.part.relate_to(
        img_path, 
        docx.opc.constants.RELATIONSHIP_TYPE.IMAGE, 
        is_external=False
    )
    
    # 构建浮动图片的XML锚点（紧密环绕规则）
    anchor_xml = f'''<w:anchor {nsdecls('w', 'wp', 'r')}
        w:allowOverlap="1" w:behindDoc="0" w:layoutInCell="1" w:locked="0"
        w:relativeHeight="251658240" w:simplePos="0">
        <wp:simplePos w:x="0" w:y="0"/>
        <wp:positionH w:relativeFrom="column">
            <wp:posOffset>0</wp:posOffset>
        </wp:positionH>
        <wp:positionV w:relativeFrom="paragraph">
            <wp:posOffset>0</wp:posOffset>
        </wp:positionV>
        <wp:extent w:cx="{int(width*914400)}" w:cy="{int(width*914400)}"/>
        <wp:wrapTight>
            <wp:wrapPolygon w:edited="0">
                <wp:start w:x="0" w:y="0"/>
                <wp:lineTo w:x="0" w:y="21600"/>
                <wp:lineTo w:x="21600" w:y="21600"/>
                <wp:lineTo w:x="21600" w:y="0"/>
                <wp:lineTo w:x="0" w:y="0"/>
            </wp:wrapPolygon>
        </wp:wrapTight>
        <wp:docPr id="{img_id}" name="Picture {img_id}"/>
        <wp:cNvGraphicFramePr>
            <a:graphicFrameLocks xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" noChangeAspect="1"/>
        </wp:cNvGraphicFramePr>
        <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
            <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
                <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
                    <pic:nvPicPr>
                        <pic:cNvPr id="{img_id}" name="Picture {img_id}"/>
                        <pic:cNvPicPr/>
                    </pic:nvPicPr>
                    <pic:blipFill>
                        <a:blip r:embed="{rId}"/>
                        <a:stretch>
                            <a:fillRect/>
                        </a:stretch>
                    </pic:blipFill>
                    <pic:spPr>
                        <a:xfrm>
                            <a:off x="0" y="0"/>
                            <a:ext cx="{int(width*914400)}" cy="{int(width*914400)}"/>
                        </a:xfrm>
                        <a:prstGeom prst="rect">
                            <a:avLst/>
                        </a:prstGeom>
                    </pic:spPr>
                </pic:pic>
            </a:graphicData>
        </a:graphic>
    </w:anchor>'''
    
    # 解析XML并生成锚点元素
    anchor = parse_xml(anchor_xml)
    
    # 创建承载锚点的文本节点
    run = paragraph.add_run()
    run._r.append(anchor)
    
    # 根据位置调整节点顺序：before则移到段落最前
    if position == "before":
        paragraph._p.insert(0, run._r)

# 测试代码
doc = Document()
p = doc.add_paragraph("这是一段包含浮动图片的文字，开头和结尾都有图片。")

# 在文字前插入图片（支持png/ico等格式）
add_floating_image(p, "front_icon.png", position="before", width=Inches(0.4))
# 在文字后插入图片
add_floating_image(p, "end_icon.png", position="after", width=Inches(0.4))

doc.save("floating_images.docx")

3. 关键参数调整 #

• 图片格式：png、ico均支持（部分Word版本对ico兼容性略差，建议优先用png），只要python-docx能读取的图片格式都适用。
• 环绕方式：将XML中的<wp:wrapTight>替换为<wp:wrapSquare>（四周环绕）、<wp:wrapTopAndBottom>（上下环绕）等，可切换不同的文字环绕规则。
• 位置偏移：修改<wp:positionH>和<wp:positionV>中的posOffset值，可调整图片相对于段落/列的偏移量，实现精准定位。

注意事项 #

• 这种方法依赖Word的底层XML结构，需要对OpenXML有基础认知；如果需要更复杂的排版，可能需要进一步调整XML参数。
• python-docx官方暂无原生的浮动图片API，该方案属于社区常用的 workaround。

内容的提问来源于stack exchange，提问作者Oussama GT