使用样式¶

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

中文

Paragraph、Run 和 Table 对象各自都有一个 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

备注

定义字符格式¶

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)

许多字体属性都是三态的，这意味着它们可以取值 True、False 和 None。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

英文

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