样式对象¶

Style objects

中文

样式有四种类型：字符、段落、表格或编号。

所有样式对象都具有行为属性和格式属性。格式属性集因样式类型而异。一般来说，格式属性会沿着以下层次结构继承：字符 -> 段落 -> 表格。编号样式没有格式属性，也不会继承。

英文

A style is one of four types; character, paragraph, table, or numbering. All style objects have behavioral properties and formatting properties. The set of formatting properties varies depending on the style type. In general, formatting properties are inherited along this hierarchy: character -> paragraph -> table. A numbering style has no formatting properties and does not inherit.

行为协议¶

Behavioral properties

中文

有六种行为属性：

hidden: 样式用于分配格式属性，但在任何情况下都不会出现在 UI 中。用于由应用程序分配的“内部”样式，这些样式不应受最终用户的控制。
priority: 确定样式在 UI 呈现的序列中的排序顺序。
semi-hidden: 样式在所谓的“主”用户界面中隐藏。在 Word 中，这意味着 推荐列表 和样式库。样式仍然出现在 所有样式 列表中。
unhide_when_used: 标记应用程序在下次使用样式时将 semi-hidden 设置为 False。
quick_style: 当样式未隐藏时，在样式库中显示样式。
closed: 文档格式保护处于活动状态时，样式被隐藏且无法应用。

英文

There are six behavior properties:

hidden: Style operates to assign formatting properties, but does not appear in the UI under any circumstances. Used for internal styles assigned by an application that should not be under the control of an end-user.
priority: Determines the sort order of the style in sequences presented by the UI.
semi-hidden: The style is hidden from the so-called "main" user interface. In Word this means the recommended list and the style gallery. The style still appears in the all styles list.
unhide_when_used: Flag to the application to set semi-hidden False when the style is next used.
quick_style: Show the style in the style gallery when it is not hidden.
locked: Style is hidden and cannot be applied when document formatting protection is active.

隐藏¶

hidden

中文

hidden 属性不适用于内置样式，其在自定义样式上的行为也不稳定。暂时跳过此属性。如果有人要求并提供具体用例，我会重新考虑。

英文

The hidden attribute doesn't work on built-in styles and its behavior on custom styles is spotty. Skipping this attribute for now. Will reconsider if someone requests it and can provide a specific use case.

行为¶

Behavior

中文

范围。 hidden 在“普通”或“标题 1”样式上根本不起作用。

它也不适用于称呼。 w:latentStyles 上没有 w:defHidden 属性，这证实了它未对内置样式启用的假设。*假设：*不适用于内置样式。

UI 行为。 将 w:hidden 设置为 True 的自定义样式在库和所有样式窗格列表中隐藏。但是，当光标位于该样式的段落上时，它会出现在样式窗格中的“所选文本的当前样式”框中。用户可以从此当前样式 UI 元素修改样式。用户可以为具有隐藏样式的段落分配新样式。

英文

Scope. hidden doesn't work at all on 'Normal' or 'Heading 1' style. It doesn't work on Salutation either. There is no w:defHidden attribute on w:latentStyles, lending credence to the hypothesis it is not enabled for built-in styles. Hypothesis: Doesn't work on built-in styles.

UI behavior. A custom style having w:hidden set True is hidden from the gallery and all styles pane lists. It does however appear in the "Current style of selected text" box in the styles pane when the cursor is on a paragraph of that style. The style can be modified by the user from this current style UI element. The user can assign a new style to a paragraph having a hidden style.

权重¶

priority

中文

priority 属性是整数主排序键，用于确定样式在 UI 列表中的位置。次要排序按名称字母顺序进行。负值有效，但不是 Word 本身分配的，并且似乎被视为 0。

英文

The priority attribute is the integer primary sort key determining the position of a style in a UI list. The secondary sort is alphabetical by name. Negative values are valid, although not assigned by Word itself and appear to be treated as 0.

行为¶

Behavior

中文

默认。 Word behavior 似乎将自定义样式的优先级默认为 0。规范表明，有效默认值在概念上是无穷大，因此样式出现在样式列表的末尾，大概是按字母顺序排列在其他未分配优先级的样式中。

英文

Default. Word behavior appears to default priority to 0 for custom styles. The spec indicates the effective default value is conceptually infinity, such that the style appears at the end of the styles list, presumably alphabetically among other styles having no priority assigned.

候选协议¶

Candidate protocol

>>> style = document.styles['Foobar']
>>> style.priority
None
>>> style.priority = 7
>>> style.priority
7
>>> style.priority = -42
>>> style.priority
0

semi-hidden¶

semi-hidden

中文

w:semiHidden 元素指定样式在所谓的 main 用户界面中的可见性。对于 Word，这意味着样式库和推荐的、正在使用的样式和当前文档中的列表。样式窗格中的全部样式列表和当前样式下拉列表将被视为 advanced 用户界面的一部分。

英文

The w:semiHidden element specifies visibility of the style in the so-called main user interface. For Word, this means the style gallery and the recommended, styles-in-use, and in-current-document lists. The all-styles list and current-style dropdown in the styles pane would then be considered part of an advanced user interface.

行为¶

Behavior

中文

Default. 如果省略 w:semiHidden 元素，则其有效值为 False。此值没有继承。

Scope. 适用于内置样式和自定义样式。

Word 行为。 Word 不使用 @w:val 属性。它为 True 写入 <w:semiHidden/>，并为 False 省略元素。

英文

Default. If the w:semiHidden element is omitted, its effective value is False. There is no inheritance of this value.

Scope. Works on both built-in and custom styles.

Word behavior. Word does not use the @w:val attribute. It writes <w:semiHidden/> for True and omits the element for False.

候选协议¶

Candidate protocol

>>> style = document.styles['Foo']
>>> style.hidden
False
>>> style.hidden = True
>>> style.hidden
True

XML 例子¶

Example XML

style.hidden = True:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:semiHidden/>
</w:style>

style.hidden = False:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
</w:style>

Alternate constructions should also report the proper value but not be used when writing XML:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:semiHidden w:val="0"/>  <!-- style.hidden is False -->
</w:style>

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:semiHidden w:val="1"/>  <!-- style.hidden is True -->
</w:style>

使用未隐藏样式¶

unhide-when-used

中文

w:unhideWhenUsed 元素向应用程序发出信号，表示下次使用时该样式应该可见。

英文

The w:unhideWhenUsed element signals an application that this style should be made visibile the next time it is used.

行为¶

Behavior .. tab:: 中文

Default. 如果省略 w:unhideWhenUsed 元素，则其有效值为 False。此值不继承。

Word 行为。 下次使用样式时， w:unhideWhenUsed 元素不会更改或删除。只有 w:semiHidden 元素（如果存在）会受到影响。据推测，这样样式就可以重新隐藏，并在后续使用时取消隐藏。

请注意，Word 中的此行为仅由用户实际应用样式触发。仅加载在其内容中某处应用了样式的文档不会导致 w:semiHidden 元素被删除。

英文

Default. If the w:unhideWhenUsed element is omitted, its effective value is False. There is no inheritance of this value.

Word behavior. The w:unhideWhenUsed element is not changed or removed when the style is next used. Only the w:semiHidden element is affected, if present. Presumably this is so a style can be re-hidden, to be unhidden on the subsequent use.

Note that this behavior in Word is only triggered by a user actually applying a style. Merely loading a document having the style applied somewhere in its contents does not cause the w:semiHidden element to be removed.

候选协议¶

Candidate protocol

>>> style = document.styles['Foo']
>>> style.unhide_when_used
False
>>> style.unhide_when_used = True
>>> style.unhide_when_used
True

XML 例子¶

Example XML

style.unhide_when_used = True:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:semiHidden/>
  <w:unhideWhenUsed/>
</w:style>

style.unhide_when_used = False:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
</w:style>

Alternate constructions should also report the proper value but not be used when writing XML:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:unhideWhenUsed w:val="0"/>  <!-- style.unhide_when_used is False -->
</w:style>

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:unhideWhenUsed w:val="1"/>  <!-- style.unhide_when_used is True -->
</w:style>

快速样式¶

quick-style

中文

w:qFormat 元素指定 Word 是否应在样式库中显示此样式。为了显示在样式库中，此属性必须为 True，并且 hidden 必须为 False。

英文

The w:qFormat element specifies whether Word should display this style in the style gallery. In order to appear in the gallery, this attribute must be True and hidden must be False.

行为¶

Behavior

中文

默认。 如果省略 w:qFormat 元素，则其有效值为 False。此值没有继承。

Word 行为。 如果 w:qFormat 为 True 且样式未隐藏，则它将按照 w:uiPriority 指定的顺序出现在图库中。

英文

Default. If the w:qFormat element is omitted, its effective value is False. There is no inheritance of this value.

Word behavior. If w:qFormat is True and the style is not hidden, it will appear in the gallery in the order specified by w:uiPriority.

候选协议¶

Candidate protocol

>>> style = document.styles['Foo']
>>> style.quick_style
False
>>> style.quick_style = True
>>> style.quick_style
True

XML 例子¶

Example XML

style.quick_style = True:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:qFormat/>
</w:style>

style.quick_style = False:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
</w:style>

Alternate constructions should also report the proper value but not be used when writing XML:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:qFormat w:val="0"/>  <!-- style.quick_style is False -->
</w:style>

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:qFormat w:val="1"/>  <!-- style.quick_style is True -->
</w:style>

锁定¶

locked

中文

w:locked 元素指定 Word 是否应阻止将此样式应用于内容。此行为仅在打开格式保护时才会激活。

英文

The w:locked element specifies whether Word should prevent this style from being applied to content. This behavior is only active if formatting protection is turned on.

行为¶

Behavior

中文

默认。 如果省略 w:locked 元素，其有效值为 False。此值没有继承。

英文

Default. If the w:locked element is omitted, its effective value is False. There is no inheritance of this value.

候选协议¶

Candidate protocol

>>> style = document.styles['Foo']
>>> style.locked
False
>>> style.locked = True
>>> style.locked
True

XML 例子¶

Example XML

style.locked = True:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:locked/>
</w:style>

style.locked = False:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
</w:style>

Alternate constructions should also report the proper value but not be used when writing XML:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:locked w:val="0"/>  <!-- style.locked is False -->
</w:style>

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:locked w:val="1"/>  <!-- style.locked is True -->
</w:style>

候选协议¶

Candidate protocols

Identification:

>>> style = document.styles['Body Text']
>>> style.name
'Body Text'
>>> style.style_id
'BodyText'
>>> style.type
WD_STYLE_TYPE.PARAGRAPH (1)

delete():

>>> len(styles)
6
>>> style.delete()
>>> len(styles)
5
>>> styles['Citation']
KeyError: no style with id or name 'Citation'

Style.base_style:

>>> style = styles.add_style('Citation', WD_STYLE_TYPE.PARAGRAPH)
>>> style.base_style
None
>>> style.base_style = styles['Normal']
>>> style.base_style
<docx.styles.style._ParagraphStyle object at 0x10a7a9550>
>>> style.base_style.name
'Normal'

XML 例子¶

Example XML

<w:styles>

  <!-- ... -->

  <w:style w:type="paragraph" w:default="1" w:styleId="Normal">
    <w:name w:val="Normal"/>
    <w:qFormat/>
  </w:style>
  <w:style w:type="character" w:default="1" w:styleId="DefaultParagraphFont">
    <w:name w:val="Default Paragraph Font"/>
    <w:uiPriority w:val="1"/>
    <w:semiHidden/>
    <w:unhideWhenUsed/>
  </w:style>
  <w:style w:type="table" w:default="1" w:styleId="TableNormal">
    <w:name w:val="Normal Table"/>
    <w:uiPriority w:val="99"/>
    <w:semiHidden/>
    <w:unhideWhenUsed/>
    <w:tblPr>
      <w:tblInd w:w="0" w:type="dxa"/>
      <w:tblCellMar>
        <w:top w:w="0" w:type="dxa"/>
        <w:left w:w="108" w:type="dxa"/>
        <w:bottom w:w="0" w:type="dxa"/>
        <w:right w:w="108" w:type="dxa"/>
      </w:tblCellMar>
    </w:tblPr>
  </w:style>
  <w:style w:type="numbering" w:default="1" w:styleId="NoList">
    <w:name w:val="No List"/>
    <w:uiPriority w:val="99"/>
    <w:semiHidden/>
    <w:unhideWhenUsed/>
  </w:style>

  <w:style w:type="paragraph" w:customStyle="1" w:styleId="Foobar">
    <w:name w:val="Foobar"/>
    <w:basedOn w:val="Normal"/>
    <w:qFormat/>
  </w:style>

</w:styles>

Schema 摘录¶

Schema excerpt

<xsd:complexType name="CT_Style">
  <xsd:sequence>
    <xsd:element name="name"            type="CT_String"        minOccurs="0"/>
    <xsd:element name="aliases"         type="CT_String"        minOccurs="0"/>
    <xsd:element name="basedOn"         type="CT_String"        minOccurs="0"/>
    <xsd:element name="next"            type="CT_String"        minOccurs="0"/>
    <xsd:element name="link"            type="CT_String"        minOccurs="0"/>
    <xsd:element name="autoRedefine"    type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="hidden"          type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="uiPriority"      type="CT_DecimalNumber" minOccurs="0"/>
    <xsd:element name="semiHidden"      type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="unhideWhenUsed"  type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="qFormat"         type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="locked"          type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="personal"        type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="personalCompose" type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="personalReply"   type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="rsid"            type="CT_LongHexNumber" minOccurs="0"/>
    <xsd:element name="pPr"             type="CT_PPrGeneral"    minOccurs="0"/>
    <xsd:element name="rPr"             type="CT_RPr"           minOccurs="0"/>
    <xsd:element name="tblPr"           type="CT_TblPrBase"     minOccurs="0"/>
    <xsd:element name="trPr"            type="CT_TrPr"          minOccurs="0"/>
    <xsd:element name="tcPr"            type="CT_TcPr"          minOccurs="0"/>
    <xsd:element name="tblStylePr"      type="CT_TblStylePr"    minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
  <xsd:attribute name="type"        type="ST_StyleType"/>
  <xsd:attribute name="styleId"     type="s:ST_String"/>
  <xsd:attribute name="default"     type="s:ST_OnOff"/>
  <xsd:attribute name="customStyle" type="s:ST_OnOff"/>
</xsd:complexType>

<xsd:complexType name="CT_OnOff">
  <xsd:attribute name="val" type="s:ST_OnOff"/>
</xsd:complexType>

<xsd:complexType name="CT_String">
  <xsd:attribute name="val" type="s:ST_String" use="required"/>
</xsd:complexType>

<xsd:simpleType name="ST_OnOff">
  <xsd:union memberTypes="xsd:boolean ST_OnOff1"/>
</xsd:simpleType>

<xsd:simpleType name="ST_OnOff1">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="on"/>
    <xsd:enumeration value="off"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_StyleType">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="paragraph"/>
    <xsd:enumeration value="character"/>
    <xsd:enumeration value="table"/>
    <xsd:enumeration value="numbering"/>
  </xsd:restriction>
</xsd:simpleType>