使用文本¶

Working with Text

中文

为了有效地处理文本，首先需要了解一些块级元素（例如段落）和行内级对象（例如运行(runs)）。

英文

To work effectively with text, it's important to first understand a little about block-level elements like paragraphs and inline-level objects like runs.

块级文本对象与内联文本对象¶

Block-level vs. inline text objects

中文

段落是 Word 中的主要块级对象。

块级项目将其包含的文本流动在其左边缘和右边缘之间，每次文本超出其右边界时都会添加一条额外的行。对于段落，边界通常是页边距，但如果页面按列布局，它们也可以是列边界，如果段落出现在表格单元格内，它们也可以是单元格边界。

表格也是块级对象。

内联对象是块级项目内出现的内容的一部分。例如，以粗体显示的单词或全大写的句子。最常见的内联对象是“运行”。块容器内的所有内容都在内联对象内。通常，段落包含一个或多个运行，每个运行都包含段落文本的某些部分。

块级项目的属性指定其在页面上的位置，例如段落前后的缩进和空格。内联项目的属性通常指定内容显示的字体，例如字体、字体大小、粗体和斜体。

英文

The paragraph is the primary block-level object in Word.

A block-level item flows the text it contains between its left and right edges, adding an additional line each time the text extends beyond its right boundary. For a paragraph, the boundaries are generally the page margins, but they can also be column boundaries if the page is laid out in columns, or cell boundaries if the paragraph occurs inside a table cell.

A table is also a block-level object.

An inline object is a portion of the content that occurs inside a block-level item. An example would be a word that appears in bold or a sentence in all-caps. The most common inline object is a run. All content within a block container is inside of an inline object. Typically, a paragraph contains one or more runs, each of which contain some part of the paragraph's text.

The attributes of a block-level item specify its placement on the page, such items as indentation and space before and after a paragraph. The attributes of an inline item generally specify the font in which the content appears, things like typeface, font size, bold, and italic.

应用字符格式¶

Apply character formatting

中文

字符格式应用于 Run 级别。示例包括字体字型和大小、粗体、斜体和下划线。

Run 对象具有只读 font 属性，用于访问 Font 对象。运行的 Font 对象提供用于获取和设置该运行的字符格式的属性。

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

可以像这样访问运行的字体:

>>> from docx import Document
>>> document = Document()
>>> run = document.add_paragraph().add_run()
>>> font = run.font

字体和大小设置如下:

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

许多字体属性都是三态，这意味着它们可以采用值 True、False 和 None。True 表示属性为“开”，False 表示属性为“关”。从概念上讲，None 值表示“继承”。运行存在于样式继承层次结构中，默认情况下从该层次结构继承其字符格式。使用 Font 对象直接应用的任何字符格式都会覆盖继承的值。

粗体和斜体是三态属性，全大写、删除线、上标和许多其他属性也是如此。请参阅 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
>>> # 或者可能
>>> font.underline = WD_UNDERLINE.DOT_DASH

英文

Character formatting is applied at the Run level. Examples include font typeface and size, bold, italic, and underline.

A Run object has a read-only font property providing access to a Font object. A run's Font object provides properties for getting and setting the character formatting for that run.

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

The font for a run can be accessed like this:

>>> from docx import Document
>>> document = Document()
>>> run = document.add_paragraph().add_run()
>>> font = run.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". A run exists in the style inheritance hierarchy and by default inherits its character formatting from that hierarchy. Any character formatting directly applied using the Font object overrides the inherited values.

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

字体颜色¶

Font color

中文

每个 Font 对象都有一个 ColorFormat 对象，可通过其只读 color 属性访问其颜色。

将特定的 RGB 颜色应用于字体:

>>> from docx.shared import RGBColor
>>> font.color.rgb = RGBColor(0x42, 0x24, 0xE9)

还可以通过分配 MSO_THEME_COLOR_INDEX 枚举的成员将字体设置为主题颜色:

>>> from docx.enum.dml import MSO_THEME_COLOR
>>> font.color.theme_color = MSO_THEME_COLOR.ACCENT_1

可以通过分配 None 将字体的颜色恢复为其默认（继承）值到 ColorFormat 的 rgb 或 theme_color 属性:

>>> font.color.rgb = None

确定字体的颜色首先要确定其颜色类型:

>>> font.color.type
RGB (1)

type 属性的值可以是 MSO_COLOR_TYPE 枚举的成员或 None。MSO_COLOR_TYPE.RGB 表示它是 RGB 颜色。MSO_COLOR_TYPE.THEME 表示主题颜色。

MSO_COLOR_TYPE.AUTO 表示其值由应用程序自动确定，通常设置为黑色。（此值相对罕见。）|None| 表示未应用任何颜色，颜色从样式层次结构继承；这是最常见的情况。

当颜色类型为 MSO_COLOR_TYPE.RGB 时，rgb 属性将为表示 RGB 颜色的 RGBColor 值:

>>> font.color.rgb
RGBColor(0x42, 0x24, 0xe9)

当颜色类型为 MSO_COLOR_TYPE.THEME 时， theme_color 属性将为 MSO_THEME_COLOR_INDEX 的成员，表示主题颜色:

>>> font.color.theme_color
ACCENT_1 (5)

英文

Each Font object has a ColorFormat object that provides access to its color, accessed via its read-only color property.

Apply a specific RGB color to a font:

>>> from docx.shared import RGBColor
>>> font.color.rgb = RGBColor(0x42, 0x24, 0xE9)

A font can also be set to a theme color by assigning a member of the MSO_THEME_COLOR_INDEX enumeration:

>>> from docx.enum.dml import MSO_THEME_COLOR
>>> font.color.theme_color = MSO_THEME_COLOR.ACCENT_1

A font's color can be restored to its default (inherited) value by assigning None to either the rgb or theme_color attribute of ColorFormat:

>>> font.color.rgb = None

Determining the color of a font begins with determining its color type:

>>> font.color.type
RGB (1)

The value of the type property can be a member of the MSO_COLOR_TYPE enumeration or None. MSO_COLOR_TYPE.RGB indicates it is an RGB color. MSO_COLOR_TYPE.THEME indicates a theme color. MSO_COLOR_TYPE.AUTO indicates its value is determined automatically by the application, usually set to black. (This value is relatively rare.) None indicates no color is applied and the color is inherited from the style hierarchy; this is the most common case.

When the color type is MSO_COLOR_TYPE.RGB, the rgb property will be an RGBColor value indicating the RGB color:

>>> font.color.rgb
RGBColor(0x42, 0x24, 0xe9)

When the color type is MSO_COLOR_TYPE.THEME, the theme_color property will be a member of MSO_THEME_COLOR_INDEX indicating the theme color:

>>> font.color.theme_color
ACCENT_1 (5)

使用文本¶

块级文本对象与内联文本对象¶

段落属性¶

水平对齐（对齐）¶

缩进¶

制表位¶

段落间距¶

行间距¶

分页属性¶

应用字符格式¶

字体颜色¶