使用样式

本页使用上一页中开发的概念,无需介绍。如果不熟悉某个术语,请参阅上一页 了解样式 一个定义。

访问样式

使用访问样式 Document.styles 属性:

>>> document = Document()
>>> styles = document.styles
>>> styles
<docx.styles.styles.Styles object at 0x10a7c4f50>

这个 Styles 对象按名称提供对已定义样式的字典样式访问:

>>> styles['Normal']
<docx.styles.style._ParagraphStyle object at <0x10a7c4f6b>

备注

内置样式使用其英文名称(例如“Heading 1”)存储在WordprocessingML文件中,即使使用Word本地化版本的用户会在UI中看到母语名称,例如“Kop 1”。因为 python-docx 在WordprocessingML文件上操作,样式查找必须使用英文名称。此外部网站上提供的文档允许您创建本地语言名称和英语样式名称之间的映射:http://www.thedoctools.com/index.php?show=mt_create_style_name_列表

用户定义的样式,也称为 自定义样式 ,不是本地化的,访问时使用的名称与单词UI中显示的名称完全相同。

这个 Styles 对象也是iterable。通过在上使用标识属性 BaseStyle ,可以生成已定义样式的各种子集。例如,此代码将生成已定义段落样式的列表:

>>> from docx.enum.style import WD_STYLE_TYPE
>>> styles = document.styles
>>> paragraph_styles = [
...     s for s in styles if s.type == WD_STYLE_TYPE.PARAGRAPH
... ]
>>> for style in paragraph_styles:
...     print(style.name)
...
Normal
Body Text
List Bullet

应用样式

这个 ParagraphRunTable 每个对象都有一个 style 属性。将样式对象指定给此属性将应用该样式:

>>> document = Document()
>>> paragraph = document.add_paragraph()
>>> paragraph.style
<docx.styles.style._ParagraphStyle object at <0x11a7c4c50>
>>> paragraph.style.name
'Normal'
>>> paragraph.style = document.styles['Heading 1']
>>> paragraph.style.name
'Heading 1'

在这种情况下,也可以直接指定样式名 python-docx 将为您查找:

>>> paragraph.style = 'List Bullet'
>>> paragraph.style
<docx.styles.style._ParagraphStyle object at <0x10a7c4f84>
>>> paragraph.style.name
'List Bullet'

也可以在创建时使用样式对象或其名称应用样式:

>>> paragraph = document.add_paragraph(style='Body Text')
>>> paragraph.style.name
'Body Text'
>>> body_text_style = document.styles['Body Text']
>>> paragraph = document.add_paragraph(style=body_text_style)
>>> paragraph.style.name
'Body Text'

添加或删除样式

通过指定唯一的名称和样式类型,可以将新样式添加到文档中:

>>> from docx.enum.style import WD_STYLE_TYPE
>>> styles = document.styles
>>> style = styles.add_style('Citation', WD_STYLE_TYPE.PARAGRAPH)
>>> style.name
'Citation'
>>> style.type
PARAGRAPH (1)

使用 base_style 属性指定新样式应继承格式设置的样式:

>>> style.base_style
None
>>> style.base_style = styles['Normal']
>>> style.base_style
<docx.styles.style._ParagraphStyle object at 0x10a7a9550>
>>> style.base_style.name
'Normal'

只需调用 delete() 方法:

>>> styles = document.styles
>>> len(styles)
10
>>> styles['Citation'].delete()
>>> len(styles)
9

备注

这个 Style.delete() 方法从文档中删除样式的定义。它不影响应用该样式的文档中的内容。具有未在文档中定义的样式的内容将使用该内容对象的默认样式呈现,例如,对于段落,使用“Normal”。

定义字符格式

字符、段落和表格样式都可以指定要应用于具有该样式的内容的字符格式。可以直接应用于文本的所有字符格式都可以在样式中指定。例如字体字体和大小、粗体、斜体和下划线。

这三种样式类型都有 font 提供对 Font 对象。A风格的 Font 对象提供用于获取和设置该样式的字符格式的属性。

这里提供了几个例子。有关可用属性的完整集合,请参见 Font API文档。

样式的字体可以这样访问:

>>> from docx import Document
>>> document = Document()
>>> style = document.styles['Normal']
>>> font = style.font

字体和大小如下:

>>> from docx.shared import Pt
>>> font.name = 'Calibri'
>>> font.size = Pt(12)

许多字体属性是 tri-state ,意味着他们可以接受这些值 TrueFalseNone . True 表示属性为“开”, False 表示“关闭”。从概念上讲 None 值的意思是“继承”。因为样式存在于继承层次结构中,所以必须能够在层次结构的正确位置指定属性,通常在层次结构的最高层。例如,如果所有标题都应该是Arial字体,那么在 Heading 1 风格和拥有 Heading 2 继承自 Heading 1 .

粗体和斜体是三态属性,所有大写、删除线、上标和许多其他属性也是如此。见 Font 完整列表的API文档:

>>> font.bold, font.italic
(None, None)
>>> font.italic = True
>>> font.italic
True
>>> font.italic = False
>>> font.italic
False
>>> font.italic = None
>>> font.italic
None

下划线有点特殊。它是三态属性和枚举值属性的混合体。 True 表示单下划线,目前最常见。 False 意思是没有下划线,但更常见 None 如果不需要下划线,则是正确的选择,因为很少从基样式继承下划线。其他形式的下划线,如双下划线或虚线下划线,则使用 WD_UNDERLINE 枚举::

>>> font.underline
None
>>> font.underline = True
>>> # or perhaps
>>> font.underline = WD_UNDERLINE.DOT_DASH

定义段落格式

段落样式和表格样式都允许指定段落格式。这些样式提供对 ParagraphFormat 通过他们的 paragraph_format 属性。

段落格式包括布局行为,如对正、缩进、前后空格、前后分页符和窗口/孤立控件。有关可用属性的完整列表,请参阅 ParagraphFormat 对象。

下面是一个如何创建一个段落样式的示例,该样式具有1/4英寸的悬挂缩进,上面有12个点的间距,以及寡妇/孤儿控件:

>>> from docx.enum.style import WD_STYLE_TYPE
>>> from docx.shared import Inches, Pt
>>> document = Document()
>>> style = document.styles.add_style('Indent', WD_STYLE_TYPE.PARAGRAPH)
>>> paragraph_format = style.paragraph_format
>>> paragraph_format.left_indent = Inches(0.25)
>>> paragraph_format.first_line_indent = Inches(-0.25)
>>> paragraph_format.space_before = Pt(12)
>>> paragraph_format.widow_control = True

使用特定于段落的样式特性

段落样式具有 next_paragraph_style 属性,该属性指定要应用于在该样式的段落之后插入的新段落的样式。当样式通常只在一个序列中出现一次时(例如标题),这是最有用的。在这种情况下,段落样式可以在完成标题后自动设置回正文样式。

在最常见的情况下(正文段落),后续段落应采用与当前段落相同的样式。如果没有指定下一个段落样式,则默认设置通过应用相同的样式来很好地处理这种情况。

下面是一个示例,说明如何更改 标题1 样式设置为 正文 ::

>>> from docx import Document
>>> document = Document()
>>> styles = document.styles

>>> styles['Heading 1'].next_paragraph_style = styles['Body Text']

默认行为可以通过指定 None 或者风格本身:

>>> heading_1_style = styles['Heading 1']
>>> heading_1_style.next_paragraph_style.name
'Body Text'

>>> heading_1_style.next_paragraph_style = heading_1_style
>>> heading_1_style.next_paragraph_style.name
'Heading 1'

>>> heading_1_style.next_paragraph_style = None
>>> heading_1_style.next_paragraph_style.name
'Heading 1'

控制样式在Word UI中的显示方式

样式的属性分为两类:, 行为特性格式化属性 . 它的行为属性控制样式出现在单词UI中的时间和位置。其格式属性决定应用样式的内容的格式,例如字体大小和段落缩进。

一种风格有五种行为特征:

风格行为 段在 了解样式 有关这些行为属性如何交互以确定样式出现在单词UI中的时间和位置的描述。

这个 priority 属性接受整数值。其他四个样式行为属性是 tri-state ,意味着他们可以接受价值 True (开), False (关闭),或 None (继承)。

使用潜在风格

内置样式潜在风格 章节在 了解样式 有关潜在样式如何定义尚未在中定义的内置样式的行为属性的说明 styles.xml .docx文件的一部分。

访问文档中的潜在样式

从styles对象访问文档中的潜在样式:

>>> document = Document()
>>> latent_styles = document.styles.latent_styles

A LatentStyles 对象支持 len() ,按样式名进行迭代和字典样式访问:

>>> len(latent_styles)
161

>>> latent_style_names = [ls.name for ls in latent_styles]
>>> latent_style_names
['Normal', 'Heading 1', 'Heading 2', ... 'TOC Heading']

>>> latent_quote = latent_styles['Quote']
>>> latent_quote
<docx.styles.latent.LatentStyle object at 0x10a7c4f50>
>>> latent_quote.priority
29

更改潜在样式默认值

这个 LatentStyles object also provides access to the default behavioral properties for built-in styles in the current document. These defaults provide the value for any undefined attributes of the |_ LatentStyle |定义以及没有显式潜在样式定义的内置样式的所有行为属性。有关 |LatentStyles| 对象获取完整的可用属性集::

>>> latent_styles.default_to_locked
False
>>> latent_styles.default_to_locked = True
>>> latent_styles.default_to_locked
True

添加潜在样式定义

可以使用 add_latent_style() 方法对 LatentStyles . 此代码为内置样式“List Bullet”添加了一个新的潜在样式,将其设置为显示在样式库中:

>>> latent_style = latent_styles['List Bullet']
KeyError: no latent style with name 'List Bullet'
>>> latent_style = latent_styles.add_latent_style('List Bullet')
>>> latent_style.hidden = False
>>> latent_style.priority = 2
>>> latent_style.quick_style = True

删除潜在样式定义

可以通过调用 delete() 方法:

>>> latent_styles['Light Grid']
<docx.styles.latent.LatentStyle object at 0x10a7c4f50>
>>> latent_styles['Light Grid'].delete()
>>> latent_styles['Light Grid']
KeyError: no latent style with name 'Light Grid'