后端【免费下载链接】python-docxCreate and modify Word documents with Python项目地址https://gitcode.com/gh_mirrors/py/python-docx点击查看免费下载导读在 python-docx 中图片、图表等图形对象以“形状shape”的形式存在于文档的绘图层drawing layer其中随文字流排布的称为内联形状inline shape。本文以官方 API 文档 docs/api/shape.rst 为主线深入讲解InlineShapes集合与InlineShape对象的用法如何遍历、索引访问文档中的所有内联形状如何读取与修改每个形状的显示尺寸以及如何识别形状类型图片、链接图片、图表、SmartArt。读完本文你将能够用几行代码完成对 Word 文档内联图片的枚举、查重、缩放等常见需求。一、先理解概念什么是内联形状Word 文档在概念上分为两个层文本层text layer与绘图层drawing layer。文本层中的对象按从左到右、从上到下的顺序流动排版排满一页后自动换页绘图层中的图形对象即“形状”则被放置在任意位置这类形状也被称为“浮动形状floating shape”。一张图片既可能出现在文本层也可能出现在绘图层。出现在文本层时它被称为内联形状inline shape更具体地说是内联图片inline picture。内联形状被当作一个“大字符”字符字形character glyph处理行高会被拉高以容纳该形状形状会像文字一样换行宽度放不下的行会被折到下一行在其前面插入文本会把它向右“推”走。通常图片会单独占一个段落但这并非强制——它所在的段落前后完全可以有文字。相关概念背景可参考 docs/user/shapes.rst。从 XML 结构看内联形状表现为w:rrun下的w:drawing子元素其中承载一个wp:inline元素DrawingML 内联对象容器。wp:inline内部依次包含表示显示尺寸的wp:extent、非可视属性wp:docPr以及承载具体图形对象如pic:pic图片的a:graphic/a:graphicData可参考 docs/dev/analysis/features/shapes/shapes-inline.rst 中的最小 XML 与完整标本 XML。二、InlineShapes文档内联形状的集合对象InlineShapes位于docx.shape模块是当前文档中全部InlineShape实例组成的序列Sequence支持len()、迭代和索引访问三种标准操作。官方 API 文档将其成员排除add_picture后完整导出即当前公开能力为序列访问实现见 src/docx/shape.py。2.1 获取集合InlineShapes集合通过Document.inline_shapes属性获得这是最常用的入口from docx import Document document Document(having-images.docx) inline_shapes document.inline_shapes其实现位于 src/docx/document.py实际委托给文档部件StoryPart的inline_shapes属性。2.2 三种访问方式# 1. 数量 count len(inline_shapes) # 2. 迭代 for shape in inline_shapes: print(shape.type, shape.width, shape.height) # 3. 索引访问 first_shape inline_shapes[0]底层机制InlineShapes在构造时接收文档的CT_Body元素并通过 XPath 表达式//w:p/w:r/w:drawing/wp:inline定位全部内联形状见 src/docx/shape.py。也就是说集合遍历的是文档正文中所有段落 run 内的wp:inline元素每个元素被包装为一个InlineShape代理对象。索引越界时会抛出带明确信息的IndexError例如inline shape index [3] out of range。2.3 集合行为的测试证据单元测试 tests/test_shape.py 覆盖了上述行为len(inline_shapes)返回集合内形状数量迭代产生的每个元素都是InlineShape实例inline_shapes[idx]支持负索引与正索引越界抛出IndexError。Behave 特性文件 features/shp-inline-shape-access.feature 也验证了“长度为 5、可迭代、可按索引访问”的完整场景其步骤实现见 features/steps/shape.py。三、InlineShape 对象尺寸读取与修改InlineShape是对单个wp:inline元素的代理对象见 src/docx/shape.py公开三个成员height、type、width这正是 API 文档autoclass指令中列出的全部成员。3.1 width 与 heightLength 类型的显示尺寸width和height返回该内联形状的显示尺寸display width / display height单位是EMUEnglish Metric Units英文公制单位返回值是Length的实例 inline_shape.height 914400 inline_shape.height.inches 1.0这正是官方 API 文档给出的示例914400 EMU 恰好等于 1 英寸。Length继承自int所以它可以像普通整数一样参与算术比较如inline_shape.width 1778000同时它自带一套只读的单位换算属性见下表实现于 src/docx/shared.py属性含义换算系数EMU 数量返回类型emu英文公制单位1intinches英寸914,400 / inchfloatcm厘米360,000 / cmfloatmm毫米36,000 / mmfloatpt磅point12,700 / ptfloattwips缇二十分之一磅635 / twipintLength还提供了配套的便捷构造函数Inches(0.5)、Cm(12)、Mm(240.5)、Pt(...)、Twips(...)、Emu(457200)等见 src/docx/shared.py赋值时可以直接使用它们from docx.shared import Inches, Cm, Emu inline_shape.width Inches(1.75) inline_shape.height Cm(3)3.2 修改尺寸的底层机制两处同时写入width和height都是可读写的read/write属性。有意思的是源码显示赋值时并非只改一处height的 setter 同时更新wp:inline/wp:extent的cy属性和pic:spPr/a:xfrm/a:ext的cy属性见 src/docx/shape.pywidth同理更新两处cx。原因在开发分析文档 docs/dev/analysis/features/shapes/shapes-inline-size.rst 中有说明内联形状的位置完全由与其同行的文本决定但尺寸可以显式指定。对于图片这类形状容器wp:extent的尺寸决定显示大小而pic元素内的尺寸记录图片的原始大小两者共同维护才能保证 Word 中显示的缩放比例正确。特性文件 features/shp-inline-shape-size.feature 与步骤实现 features/steps/shape.py 验证了“查询已知尺寸”和“修改为Inches(1) × Inches(0.5)后两处属性同步更新”的行为单元测试 tests/test_shape.py 则直接断言修改后整个wp:inline的 XML 中两处extent均变为新值。四、type 属性识别内联形状的类型InlineShape.type是只读属性返回docx.enum.shape.WD_INLINE_SHAPE枚举的一个成员用于区分内联形状的种类 inline_shape.type WD_INLINE_SHAPE.PICTURE4.1 支持的枚举成员WD_INLINE_SHAPE即WD_INLINE_SHAPE_TYPE见 src/docx/enum/shape.py对应 Word VBA 的WdInlineShapeType枚举本仓库定义如下枚举成员数值含义WD_INLINE_SHAPE.PICTURE3嵌入式图片WD_INLINE_SHAPE.LINKED_PICTURE4链接式图片WD_INLINE_SHAPE.CHART12图表WD_INLINE_SHAPE.SMART_ART15SmartArt 图形WD_INLINE_SHAPE.NOT_IMPLEMENTED-6暂未实现的形状类型4.2 type 的判定逻辑源码中的判定依据是graphicData元素的uri命名空间见 src/docx/shape.pyuri为pic命名空间http://schemas.openxmlformats.org/drawingml/2006/picture时检查pic:blipFill/a:blip元素——存在r:link属性引用外部图片则判为LINKED_PICTURE否则判为PICTURE存在r:embed表示图片部件已嵌入文档uri为c命名空间chart时判为CHARTuri为dgm命名空间diagram时判为SMART_ART其余未知 URI 一律返回NOT_IMPLEMENTED。三个命名空间常量定义于 src/docx/oxml/ns.py。值得注意的边界情况当a:blip同时带r:embed和r:link既嵌入又链接虽不常见时源码优先返回LINKED_PICTURE该行为同样被单元测试覆盖见 tests/test_shape.py并在 features/shp-inline-shape-access.feature 的场景大纲中列为显式用例。4.3 典型应用按类型筛选图片from docx.enum.shape import WD_INLINE_SHAPE embedded [ s for s in document.inline_shapes if s.type WD_INLINE_SHAPE.PICTURE ] print(f文档中共有 {len(embedded)} 张嵌入图片)五、如何产生内联形状add_picture 入口理解集合与单个形状之后再看形状从何而来。python-docx 当前主要支持的是内联图片浮动图片暂未开放添加。两个常用入口5.1 Document.add_picture文档末尾追加document.add_picture(python-icon.png, widthInches(1.0))该方法在文档末尾新建一个独立段落并在其中添加含图片的 run见 src/docx/document.py。尺寸规则width、height都不给 → 以图片原始尺寸显示只给其一 → 以该值计算缩放系数等比缩放另一维保持宽高比原始尺寸依据图片文件中的dpi 值计算文件未声明 dpi 时按默认 72 dpi 处理这在 JPEG 等格式中很常见。5.2 Run.add_picture在指定位置插入paragraph document.add_paragraph(图片前方文字) run paragraph.add_run() run.add_picture(python-powered.png, heightCm(2.0)) paragraph.add_run(图片后方文字)Run.add_picture把内联图片插入到该 run 末尾从而支持“文字 图片 文字”的混合排版见 src/docx/text/run.py。其底层调用链为StoryPart.new_pic_inline()负责将图片加入文档部件、计算缩放后的cx/cy、生成全局唯一的形状 id最终由CT_Inline.new_pic_inline()组装wp:inline元素见 src/docx/parts/story.py 与 src/docx/oxml/shape.py。形状 id 通过扫描文档中全部id属性取最大值加 1 得到保证文档内唯一见 src/docx/parts/story.py。add_picture会返回InlineShape对象因此可以链式调整尺寸shape document.add_picture(mountain.bmp) shape.width Inches(3.5) shape.height Inches(2.0)六、完整实战统计并统一缩放文档内所有图片将上述 API 组合起来可以实现一个常见的批处理任务——枚举文档全部内联图片并统一宽度from docx import Document from docx.enum.shape import WD_INLINE_SHAPE from docx.shared import Inches document Document(report.docx) for shape in document.inline_shapes: if shape.type ! WD_INLINE_SHAPE.PICTURE: continue # 读取当前尺寸EMU 整数可直接比较 print(f原尺寸{shape.width} x {shape.height} EMU) print(f即 {shape.width.inches:.2f} x {shape.height.inches:.2f} 英寸) # 统一缩放到 4 英寸宽高度按同比例由 Word 依据 spPr 中的原始尺寸换算 shape.width Inches(4) document.save(report-resized.docx)注意width/height读取到的 EMU 是显示尺寸修改只影响显示大小不会改变图片部件本身的像素数据因此该操作可以放心重复执行。七、小结与延伸阅读本文围绕官方 API 文档 docs/api/shape.rst 展开InlineShapes集合支持len()、迭代、索引访问InlineShape提供可读写的width/heightLength类型内置 EMU 与英寸、厘米、毫米、磅、缇的换算以及只读的typeWD_INLINE_SHAPE枚举可区分嵌入图片、链接图片、图表与 SmartArt。结合源码可以看到尺寸修改会同步更新wp:extent与pic:spPr两处 XML 属性类型判定则基于graphicData的命名空间 URI。如需继续深入可参考集合与单形状的单元测试tests/test_shape.pyBehave 行为驱动用例features/shp-inline-shape-access.feature、features/shp-inline-shape-size.feature 及其步骤实现 features/steps/shape.pyLength类的完整定义与全部单位构造函数src/docx/shared.pywp:inline的 XML 结构、最小 XML 与 XSD schema 定义docs/dev/analysis/features/shapes/shapes-inline.rst、docs/dev/analysis/features/shapes/shapes-inline-size.rst图片内联容器pic:pic的 XML 细节docs/dev/analysis/features/shapes/picture.rst文本层/绘图层概念docs/user/shapes.rst赞分享后端【免费下载链接】python-docxCreate and modify Word documents with Python项目地址https://gitcode.com/gh_mirrors/py/python-docx点击查看免费下载相关推荐Ant Design Avatar 头像尺寸与形状全解析三种尺寸、两种形状的源码级实战指南Ant Design Avatar 头像尺寸与形状全解析三种尺寸、两种形状的源码级实战指南 本篇以 Ant Design 组件库中 Avatar头像组件的前端UI组件设计系统YOLOv6 训练尺寸模式详解正方形训练、矩形训练与固定尺寸输入的原理与实操YOLOv6 训练尺寸模式详解正方形训练、矩形训练与固定尺寸输入的原理与实操 YOLOv6 通过 img size 、 rect 、 specific sha人工智能深度学习计算机视觉预训练模型量化Invoke-AtomicRedTeam跨平台指南在Windows、Linux和macOS上的部署与使用终极教程Invoke AtomicRedTeam跨平台指南在Windows、Linux和macOS上的部署与使用终极教程 Invoke AtomicRedTea网络安全上一篇【亲测免费】 HAPI FHIR 快速入门指南下一篇Task构建工具现代开发工作流的终极自动化指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考