Working with Styles

Working with Styles

This guide shows how to work with paragraph, character, table, and list styles in Aspose.Words FOSS for .NET — looking up and applying built-in and custom styles, and configuring per-region conditional formatting on table styles.

A Style object represents a single built-in or user-defined style — the named collection of paragraph, font, and list formatting that Word applies when a paragraph or run is assigned that style. Every document exposes its styles through the Document.Styles property, which returns a StyleCollection. Table styles are represented by TableStyle, a subclass of Style that adds table-specific formatting and per-region conditional formatting through ConditionalStyleCollection.

Style Types and Identification

Each Style has a Type property of type StyleType, which is one of Paragraph, Character, Table, or List — matching the four kinds of styles Word supports. Built-in styles also carry a locale-independent StyleIdentifier enum value (for example values corresponding to headings, emphasis, and hyperlink styles) so that code can look up a built-in style without depending on its display name in a particular language. A style’s human-readable name is available through Style.Name, and Style.Aliases returns any alternate names Word recognizes for the same style. Style.BuiltIn reports whether the style ships with Word itself versus being defined in the document, and Style.IsHeading reports whether the style is one of the built-in heading styles.

Accessing and Managing the Style Collection

StyleCollection is the collection of all Style objects — built-in and custom — attached to a document, reached through Document.Styles. Retrieve a style by its display name using the StyleCollection indexer — styles[name] — or retrieve a built-in style by its locale-independent StyleIdentifier using the same indexer — styles[sti] — which is more reliable than name lookup across documents authored in different languages. New styles are created with StyleCollection.Add(type, name), specifying the StyleType and a name, and an existing style can be duplicated into the collection with StyleCollection.AddCopy(style). StyleCollection.Count reports how many styles the document holds, and the collection also exposes DefaultFont and DefaultParagraphFormat, which describe the document-wide default formatting new content inherits before any explicit style is applied. StyleCollection.ClearQuickStyleGallery() removes all styles from the Word UI’s quick-style gallery without deleting the styles themselves.

Applying Styles to Paragraphs and Runs

Formatting objects that can carry a style expose both a Style property (the Style object itself) and a StyleName property (a shortcut that resolves or creates a style by name). ParagraphFormat.Style and ParagraphFormat.StyleName apply a paragraph style, while Font.Style and Font.StyleName apply a character style to a run’s formatting. A style’s own LinkedStyleName, BaseStyleName, and NextParagraphStyleName properties describe how it relates to other styles: BaseStyleName names the style it inherits unset formatting from, LinkedStyleName names a paired paragraph/character style (as Word does for built-in styles like Heading 1 and its linked character style), and NextParagraphStyleName names the style Word assigns to a new paragraph typed after one using this style.

Table Styles and Conditional Formatting

TableStyle extends Style with table-layout properties such as Alignment, CellSpacing, LeftIndent, Shading, VerticalAlignment, and padding (LeftPadding, RightPadding, TopPadding, BottomPadding), plus RowStripe and ColumnStripe, which control how many rows or columns a banding pattern repeats over. Beyond uniform table formatting, TableStyle.ConditionalStyles returns a ConditionalStyleCollection holding one ConditionalStyle per table region — FirstRow, LastRow, FirstColumn, LastColumn, OddRowBanding, EvenRowBanding, OddColumnBanding, EvenColumnBanding, and the four corner cells (TopLeftCell, TopRightCell, BottomLeftCell, BottomRightCell). Each ConditionalStyle carries its own Font, ParagraphFormat, Shading, Borders, and cell padding, and its Type property reports which ConditionalStyleType region it represents. ConditionalStyle.ClearFormatting() and ConditionalStyleCollection.ClearFormatting() reset formatting for one region or the whole set of conditional regions.

Style Metadata and Behavior Flags

Several boolean and numeric properties on Style control how Word treats a style in its UI rather than how it renders: Locked prevents the style from being changed when formatting protection is active, IsQuickStyle controls whether it appears in the quick-style gallery, AutomaticallyUpdate makes the style redefine itself from manually-applied direct formatting, SemiHidden and UnhideWhenUsed control visibility in the style list before and after first use, and Priority affects sort order in the gallery. A style also exposes List and ListFormat properties when it defines list numbering, and Style.Remove() deletes the style from its StyleCollection.

Tips and Best Practices

• Prefer the StyleCollection indexer with a StyleIdentifier value over looking up by name when finding a built-in style — names are localized, but StyleIdentifier values are not.
• Set BaseStyleName to build style hierarchies (for example, a set of heading styles that all inherit font choices from one base style) instead of repeating formatting on every style.
• When copying a style between documents, use StyleCollection.AddCopy(style) rather than manually reading and reapplying every formatting property.
• Configure TableStyle.ConditionalStyles regions for banded tables instead of manually formatting alternating rows in code — each ConditionalStyle region’s formatting is applied based on its ConditionalStyleType, rather than by setting direct formatting on individual rows.
• Check Style.BuiltIn before removing or renaming a style programmatically; built-in styles are usually referenced by name elsewhere in the document.

Common Issues

FAQ

How do I get the collection of all styles in a document?

Read Document.Styles, which returns a StyleCollection containing every built-in and user-defined Style in that document.

What’s the difference between Style and StyleIdentifier?

Style is the actual style object with its formatting; StyleIdentifier is a locale-independent enum value used to look up a specific built-in style regardless of the document’s language, via the StyleCollection indexer.

How do table styles differ from paragraph or character styles?

TableStyle is a subclass of Style that adds table-layout properties (Alignment, CellSpacing, padding) and a ConditionalStyles collection for region-specific formatting such as banded rows, header rows, and corner cells — formatting concepts that don’t apply to paragraph or character styles.

Can I create a brand-new style instead of modifying an existing one?

Yes — call StyleCollection.Add(type, name) with the desired StyleType and a new name to create an empty style, then set its formatting properties (Font, ParagraphFormat, and so on for paragraph/character styles).

How do I duplicate a style, including from another document?

Use StyleCollection.AddCopy(style), passing a Style object (which can come from a different Document’s StyleCollection) to add a copy of it to the target collection.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation