使用样式

Working with Styles

本页使用了上一页中开发的概念,但未作介绍。如果术语不熟悉,请参阅上一页 了解样式 以了解其定义。

This page uses concepts developed in the prior page without introduction. If a term is unfamiliar, consult the prior page 了解样式 for a definition.

访问样式

Access a style

使用 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_list

用户定义的样式(也称为 自定义样式 )未本地化,并且可以使用与 Word UI 中显示的名称完全相同的名称进行访问。

Styles 对象也是可迭代的。通过使用 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

Styles are accessed using the Document.styles attribute:

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

The Styles object provides dictionary-style access to defined styles by name:

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

备注

Built-in styles are stored in a WordprocessingML file using their English name, e.g. 'Heading 1', even though users working on a localized version of Word will see native language names in the UI, e.g. 'Kop 1'. Because python-docx operates on the WordprocessingML file, style lookups must use the English name. A document available on this external site allows you to create a mapping between local language names and English style names: http://www.thedoctools.com/index.php?show=mt_create_style_name_list

User-defined styles, also known as custom styles, are not localized and are accessed with the name exactly as it appears in the Word UI.

The Styles object is also iterable. By using the identification properties on BaseStyle, various subsets of the defined styles can be generated. For example, this code will produce a list of the defined paragraph styles:

>>> 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

应用样式

Apply a style

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'

The Paragraph, Run, and Table objects each have a style attribute. Assigning a style object to this attribute applies that 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'

A style name can also be assigned directly, in which case python-docx will do the lookup for you:

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

A style can also be applied at creation time using either the style object or its name:

>>> 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'

添加或删除样式

Add or delete a style

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

>>> 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

备注

The Style.delete() method removes the style's definition from the document. It does not affect content in the document to which that style is applied. Content having a style not defined in the document is rendered using the default style for that content object, e.g. 'Normal' in the case of a paragraph.

A new style can be added to the document by specifying a unique name and a style type:

>>> 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)

Use the base_style property to specify a style the new style should inherit formatting settings from:

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

A style can be removed from the document simply by calling its delete() method:

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

备注

The Style.delete() method removes the style's definition from the document. It does not affect content in the document to which that style is applied. Content having a style not defined in the document is rendered using the default style for that content object, e.g. 'Normal' in the case of a paragraph.

定义字符格式

Define character formatting

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

这三种样式类型中的每一种都有一个 font 属性,用于访问 Font 对象。样式的 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)

许多字体属性都是 三态 的,这意味着它们可以取值 TrueFalseNoneTrue 表示属性处于“开启”状态,False 表示属性处于“关闭”状态。从概念上讲,None 值表示“继承”。由于样式存在于继承层次结构中,因此能够在层次结构的正确位置指定属性非常重要,通常尽可能地位于层次结构的上层。例如,如果所有标题都应采用 Arial 字体,则更有意义的做法是将该属性设置为 Heading 1 样式,并让 Heading 2Heading 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

Character, paragraph, and table styles can all specify character formatting to be applied to content with that style. All the character formatting that can be applied directly to text can be specified in a style. Examples include font typeface and size, bold, italic, and underline.

Each of these three style types have a font attribute providing access to a Font object. A style's Font object provides properties for getting and setting the character formatting for that style.

Several examples are provided here. For a complete set of the available properties, see the Font API documentation.

The font for a style can be accessed like this:

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

Typeface and size are set like this:

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

Many font properties are tri-state, meaning they can take the values True, False, and None. True means the property is "on", False means it is "off". Conceptually, the None value means "inherit". Because a style exists in an inheritance hierarchy, it is important to have the ability to specify a property at the right place in the hierarchy, generally as far up the hierarchy as possible. For example, if all headings should be in the Arial typeface, it makes more sense to set that property on the Heading 1 style and have Heading 2 inherit from Heading 1.

Bold and italic are tri-state properties, as are all-caps, strikethrough, superscript, and many others. See the Font API documentation for a full list:

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

Underline is a bit of a special case. It is a hybrid of a tri-state property and an enumerated value property. True means single underline, by far the most common. False means no underline, but more often None is the right choice if no underlining is wanted since it is rare to inherit it from a base style. The other forms of underlining, such as double or dashed, are specified with a member of the WD_UNDERLINE enumeration:

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

定义段落格式

Define paragraph formatting

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

段落格式包括布局行为,例如对齐、缩进、前后空格、分页符和孤行控制。有关可用属性的完整列表,请参阅 ParagraphFormat 对象的 API 文档页面。

以下是如何创建具有 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

Both a paragraph style and a table style allow paragraph formatting to be specified. These styles provide access to a ParagraphFormat object via their paragraph_format property.

Paragraph formatting includes layout behaviors such as justification, indentation, space before and after, page break before, and widow/orphan control. For a complete list of the available properties, consult the API documentation page for the ParagraphFormat object.

Here's an example of how you would create a paragraph style having hanging indentation of 1/4 inch, 12 points spacing above, and widow/orphan control:

>>> 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

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

Use paragraph-specific style properties

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

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

以下是如何将 Heading 1 样式的下一个段落样式更改为 Body Text 的示例:

>>> 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'

A paragraph style has a next_paragraph_style property that specifies the style to be applied to new paragraphs inserted after a paragraph of that style. This is most useful when the style would normally appear only once in a sequence, such as a heading. In that case, the paragraph style can automatically be set back to a body style after completing the heading.

In the most common case (body paragraphs), subsequent paragraphs should receive the same style as the current paragraph. The default handles this case well by applying the same style if a next paragraph style is not specified.

Here's an example of how you would change the next paragraph style of the Heading 1 style to Body Text:

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

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

The default behavior can be restored by assigning None or the style itself:

>>> 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 中的显示方式

Control how a style appears in the Word UI

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

样式有五种行为属性:

有关这些行为属性如何相互作用以确定样式在 Word UI 中出现的时间和位置的描述,请参阅 了解样式 中的 样式行为 部分.

priority 属性采用整数值。其他四个样式行为属性是 三态,这意味着它们可以采用值 |True|(开启)、|False|(关闭)或 |None|(继承)。

The properties of a style fall into two categories, behavioral properties and formatting properties. Its behavioral properties control when and where the style appears in the Word UI. Its formatting properties determine the formatting of content to which the style is applied, such as the size of the font and its paragraph indentation.

There are five behavioral properties of a style:

See the 样式行为 section in 了解样式 for a description of how these behavioral properties interact to determine when and where a style appears in the Word UI.

The priority property takes an integer value. The other four style behavior properties are tri-state, meaning they can take the value True (on), False (off), or None (inherit).

在样式库中显示样式

Display a style in the style gallery

以下代码将使 'Body Text' 段落样式首先出现在样式库中:

>>> from docx import Document
>>> document = Document()
>>> style = document.styles['Body Text']

>>> style.hidden = False
>>> style.quick_style = True
>>> style.priorty = 1

The following code will cause the 'Body Text' paragraph style to appear first in the style gallery:

>>> from docx import Document
>>> document = Document()
>>> style = document.styles['Body Text']

>>> style.hidden = False
>>> style.quick_style = True
>>> style.priorty = 1

从样式库中删除样式

Remove a style from the style gallery

此代码将从样式库中删除 'Normal' 段落样式,但允许其保留在推荐列表中:

>>> style = document.styles['Normal']

>>> style.hidden = False
>>> style.quick_style = False

This code will remove the 'Normal' paragraph style from the style gallery, but allow it to remain in the recommended list:

>>> style = document.styles['Normal']

>>> style.hidden = False
>>> style.quick_style = False

使用潜在样式

Working with Latent Styles

请参阅 了解样式 中的 内置样式潜在样式 部分,了解潜在样式如何定义 .docx 文件的 styles.xml 部分中尚未定义的内置样式的行为属性。

See the 内置样式 and 潜在样式 sections in 了解样式 for a description of how latent styles define the behavioral properties of built-in styles that are not yet defined in the styles.xml part of a .docx file.

访问文档中的潜在样式

Access the latent styles in a document

文档中的潜在样式可以通过样式对象访问:

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

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

The latent styles in a document are accessed from the styles object:

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

A LatentStyles object supports len(), iteration, and dictionary-style access by style name:

>>> 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

更改潜在样式默认值

Change latent style defaults

LatentStyles 对象还提供对当前文档中内置样式的默认行为属性的访问。这些默认值为 _LatentStyle 定义中任何未定义的属性以及没有明确潜在样式定义的内置样式的所有行为属性提供值。有关可用属性的完整集合,请参阅 LatentStyles 对象的 API 文档:

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

The 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 definitions and to all behavioral properties of built-in styles having no explicit latent style definition. See the API documentation for the LatentStyles object for the complete set of available properties:

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

添加潜在样式定义

Add a latent style definition

可以使用 LatentStyles 上的 add_latent_style() 方法添加新的潜在样式。此代码为内置样式'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

A new latent style can be added using the add_latent_style() method on LatentStyles. This code adds a new latent style for the builtin style 'List Bullet', setting it to appear in the style gallery:

>>> 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 a latent style definition

可以通过调用其 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'

A latent style definition can be deleted by calling its delete() method:

>>> 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'