样式相关对象

Style-related objects

中文

样式用于将一组格式属性集中到一个名称下，并一次性将这些属性应用于内容对象。这可以提高整个文档以及相关文档的格式一致性，并允许通过更改相应样式中的定义来全局更改格式。

英文

A style is used to collect a set of formatting properties under a single name and apply those properties to a content object all at once. This promotes formatting consistency throughout a document and across related documents and allows formatting changes to be made globally by changing the definition in the appropriate style.

Styles 对象

Styles objects

class docx.styles.styles.Styles

Provides access to the styles defined in a document.

Accessed using the Document.styles property. Supports len(), iteration, and dictionary-style access by style name.

add_style(name, style_type, builtin=False)

Return a newly added style object of style_type and identified by name.

A builtin style can be defined by passing True for the optional builtin argument.

default(style_type: WD_STYLE_TYPE)

Return the default style for style_type or None if no default is defined for that type (not common).

property element

The lxml element proxied by this object.

property latent_styles

A LatentStyles object providing access to the default behaviors for latent styles and the collection of _LatentStyle objects that define overrides of those defaults for a particular named latent style.

BaseStyle 对象

BaseStyle objects

class docx.styles.style.BaseStyle

Base class for the various types of style object, paragraph, character, table, and numbering.

These properties and methods are inherited by all style objects.

property builtin

Read-only.

True if this style is a built-in style. False indicates it is a custom (user-defined) style. Note this value is based on the presence of a customStyle attribute in the XML, not on specific knowledge of which styles are built into Word.

delete()

Remove this style definition from the document.

Note that calling this method does not remove or change the style applied to any document content. Content items having the deleted style will be rendered using the default style, as is any content with a style not defined in the document.

property element

The lxml element proxied by this object.

property hidden

True if display of this style in the style gallery and list of recommended styles is suppressed.

False otherwise. In order to be shown in the style gallery, this value must be False and quick_style must be True.

property locked

Read/write Boolean.

True if this style is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

property name

The UI name of this style.

property priority

The integer sort key governing display sequence of this style in the Word UI.

None indicates no setting is defined, causing Word to use the default value of 0. Style name is used as a secondary sort key to resolve ordering of styles having the same priority value.

property quick_style

True if this style should be displayed in the style gallery when hidden is False.

Read/write Boolean.

property type

Member of WD_STYLE_TYPE corresponding to the type of this style, e.g. WD_STYLE_TYPE.PARAGRAPH.

property unhide_when_used

True if an application should make this style visible the next time it is applied to content.

False otherwise. Note that python-docx does not automatically unhide a style having True for this attribute when it is applied to content.

CharacterStyle 对象

CharacterStyle objects

class docx.styles.style.CharacterStyle

基类：BaseStyle

A character style.

A character style is applied to a Run object and primarily provides character- level formatting via the Font object in its font property.

property base_style

Style object this style inherits from or None if this style is not based on another style.

property builtin

Read-only.

True if this style is a built-in style. False indicates it is a custom (user-defined) style. Note this value is based on the presence of a customStyle attribute in the XML, not on specific knowledge of which styles are built into Word.

delete()

Remove this style definition from the document.

Note that calling this method does not remove or change the style applied to any document content. Content items having the deleted style will be rendered using the default style, as is any content with a style not defined in the document.

property font

The Font object providing access to the character formatting properties for this style, such as font name and size.

property hidden

True if display of this style in the style gallery and list of recommended styles is suppressed.

False otherwise. In order to be shown in the style gallery, this value must be False and quick_style must be True.

property locked

Read/write Boolean.

True if this style is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

property name

The UI name of this style.

property priority

The integer sort key governing display sequence of this style in the Word UI.

None indicates no setting is defined, causing Word to use the default value of 0. Style name is used as a secondary sort key to resolve ordering of styles having the same priority value.

property quick_style

True if this style should be displayed in the style gallery when hidden is False.

Read/write Boolean.

property unhide_when_used

True if an application should make this style visible the next time it is applied to content.

False otherwise. Note that python-docx does not automatically unhide a style having True for this attribute when it is applied to content.

ParagraphStyle 对象

ParagraphStyle objects

class docx.styles.style.ParagraphStyle

基类：CharacterStyle

A paragraph style.

A paragraph style provides both character formatting and paragraph formatting such as indentation and line-spacing.

property base_style

Style object this style inherits from or None if this style is not based on another style.

property builtin

Read-only.

True if this style is a built-in style. False indicates it is a custom (user-defined) style. Note this value is based on the presence of a customStyle attribute in the XML, not on specific knowledge of which styles are built into Word.

delete()

Remove this style definition from the document.

Note that calling this method does not remove or change the style applied to any document content. Content items having the deleted style will be rendered using the default style, as is any content with a style not defined in the document.

property font

The Font object providing access to the character formatting properties for this style, such as font name and size.

property hidden

True if display of this style in the style gallery and list of recommended styles is suppressed.

False otherwise. In order to be shown in the style gallery, this value must be False and quick_style must be True.

property locked

Read/write Boolean.

True if this style is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

property name

The UI name of this style.

property next_paragraph_style

ParagraphStyle object representing the style to be applied automatically to a new paragraph inserted after a paragraph of this style.

Returns self if no next paragraph style is defined. Assigning None or self removes the setting such that new paragraphs are created using this same style.

property paragraph_format

The ParagraphFormat object providing access to the paragraph formatting properties for this style such as indentation.

property priority

The integer sort key governing display sequence of this style in the Word UI.

None indicates no setting is defined, causing Word to use the default value of 0. Style name is used as a secondary sort key to resolve ordering of styles having the same priority value.

property quick_style

True if this style should be displayed in the style gallery when hidden is False.

Read/write Boolean.

property unhide_when_used

True if an application should make this style visible the next time it is applied to content.

False otherwise. Note that python-docx does not automatically unhide a style having True for this attribute when it is applied to content.

_TableStyle 对象

_TableStyle objects

class docx.styles.style._TableStyle

基类：ParagraphStyle

A table style.

A table style provides character and paragraph formatting for its contents as well as special table formatting properties.

property base_style

Style object this style inherits from or None if this style is not based on another style.

property builtin

Read-only.

True if this style is a built-in style. False indicates it is a custom (user-defined) style. Note this value is based on the presence of a customStyle attribute in the XML, not on specific knowledge of which styles are built into Word.

delete()

Remove this style definition from the document.

Note that calling this method does not remove or change the style applied to any document content. Content items having the deleted style will be rendered using the default style, as is any content with a style not defined in the document.

property font

The Font object providing access to the character formatting properties for this style, such as font name and size.

property hidden

True if display of this style in the style gallery and list of recommended styles is suppressed.

False otherwise. In order to be shown in the style gallery, this value must be False and quick_style must be True.

property locked

Read/write Boolean.

True if this style is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

property name

The UI name of this style.

property next_paragraph_style

ParagraphStyle object representing the style to be applied automatically to a new paragraph inserted after a paragraph of this style.

Returns self if no next paragraph style is defined. Assigning None or self removes the setting such that new paragraphs are created using this same style.

property paragraph_format

The ParagraphFormat object providing access to the paragraph formatting properties for this style such as indentation.

property priority

The integer sort key governing display sequence of this style in the Word UI.

None indicates no setting is defined, causing Word to use the default value of 0. Style name is used as a secondary sort key to resolve ordering of styles having the same priority value.

property quick_style

True if this style should be displayed in the style gallery when hidden is False.

Read/write Boolean.

property unhide_when_used

True if an application should make this style visible the next time it is applied to content.

False otherwise. Note that python-docx does not automatically unhide a style having True for this attribute when it is applied to content.

_NumberingStyle 对象

_NumberingStyle objects

class docx.styles.style._NumberingStyle

A numbering style.

Not yet implemented.

LatentStyles 对象

LatentStyles objects

class docx.styles.latent.LatentStyles

Provides access to the default behaviors for latent styles in this document and to the collection of _LatentStyle objects that define overrides of those defaults for a particular named latent style.

add_latent_style(name)

Return a newly added _LatentStyle object to override the inherited defaults defined in this latent styles object for the built-in style having name.

property default_priority

Integer between 0 and 99 inclusive specifying the default sort order for latent styles in style lists and the style gallery.

None if no value is assigned, which causes Word to use the default value 99.

property default_to_hidden

Boolean specifying whether the default behavior for latent styles is to be hidden.

A hidden style does not appear in the recommended list or in the style gallery.

property default_to_locked

Boolean specifying whether the default behavior for latent styles is to be locked.

A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

property default_to_quick_style

Boolean specifying whether the default behavior for latent styles is to appear in the style gallery when not hidden.

property default_to_unhide_when_used

Boolean specifying whether the default behavior for latent styles is to be unhidden when first applied to content.

property element

The lxml element proxied by this object.

property load_count

Integer specifying the number of built-in styles to initialize to the defaults specified in this LatentStyles object.

None if there is no setting in the XML (very uncommon). The default Word 2011 template sets this value to 276, accounting for the built-in styles in Word 2010.

_LatentStyle 对象

_LatentStyle objects

class docx.styles.latent._LatentStyle

Proxy for an w:lsdException element, which specifies display behaviors for a built-in style when no definition for that style is stored yet in the styles.xml part.

The values in this element override the defaults specified in the parent w:latentStyles element.

delete()

Remove this latent style definition such that the defaults defined in the containing LatentStyles object provide the effective value for each of its attributes.

Attempting to access any attributes on this object after calling this method will raise AttributeError.

property element

The lxml element proxied by this object.

property hidden

Tri-state value specifying whether this latent style should appear in the recommended list.

None indicates the effective value is inherited from the parent <w:latentStyles> element.

property locked

Tri-state value specifying whether this latent styles is locked.

A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

property name

The name of the built-in style this exception applies to.

property priority

The integer sort key for this latent style in the Word UI.

property quick_style

Tri-state value specifying whether this latent style should appear in the Word styles gallery when not hidden.

None indicates the effective value should be inherited from the default values in its parent LatentStyles object.

property unhide_when_used

Tri-state value specifying whether this style should have its hidden attribute set False the next time the style is applied to content.

None indicates the effective value should be inherited from the default specified by its parent LatentStyles object.