Работа с объектом Style модуля docx-python

Пользовательские и встроенный стили в DOCX

Содержание:

Работа со стилями при создании документа DOCX.
Добавление/удаление пользовательского стиля документа.
Изменение существующего стиля документа.
Методы и свойства объекта Style.

Работа со стилями при создании документа DOCX.

Доступ к стилям документа осуществляется с помощью атрибута Document.styles. Возвращаемый объект представляет собой последовательность, который хранит все встроенные в редактор MS Word, а так же созданные пользователем объекты стилей Style. Обращаться к этой последовательности можно как к словарю.

>>> from docx import Document
>>> doc = Document()
# получаем все стили определенные стили 
>>> all_styles = doc.styles
# получаем объект `Style` по имени
>>> all_styles['Normal']
# _ParagraphStyle('Normal') id: 140214642449472

Важно!!! Встроенные стили хранятся в файле WordprocessingML под своим английским именем, например 'Heading 1', и не зависят от локализации MS Word. Так как модуль python-docx работает с файлом WordprocessingML, то поиск стиля должен использовать английское имя. Если файл WordprocessingML не найден (MS Word не установлен, например в OS Linux) то модуль python-docx работает со своей версией этого файла. Что бы создать сопоставление между именами стилей на русском языке и именами на английском языке посетите эту ссылку.

Пользовательские стили, также известные как настраиваемые стили, не локализованы и доступны по имени, как оно отображается в пользовательском интерфейсе Word.

Используя свойство идентификации стиля Style.type и перечисление WD_STYLE_TYPE можно создавать подмножества определенных стилей. Например, этот код создаст список стилей абзаца:

>>> from docx import Document
>>> from docx.enum.style import WD_STYLE_TYPE
>>> doc = Document()
>>> all_styles = doc.styles
>>> paragraph_styles = [s for s in all_styles if s.type == WD_STYLE_TYPE.PARAGRAPH]
>>> for style in paragraph_styles:
...     print(style.name)
# Normal
# Header
# Footer
# Heading 1
...

Каждый из объектов документа DOCX: абзац Paragraph, прогон Run и таблица Table имеет атрибут стиля .style (например Paragraph.style). Назначение этому атрибуту объекта стиля Style или имени стиля, применяет этот стиль соответствующему объекту:

>>> from docx import Document
>>> doc = Document()
>>> p = doc.add_paragraph()
# имя стиля созданного абзаца
>>> p.style.name
# 'Normal'

# присвоение созданному абзацу 
# нового стиля, как объекта
>>> p.style = doc.styles['Heading 1']
# можно поменять стиль, просто 
# присвоив имя стиля
>>> p.style = 'Heading 1'
>>> p.style.name
# 'Heading 1'

Стиль Style также можно применить во время создания, используя либо объект стиля, либо его имя:

# применяем стиль по имени
>>> p = doc.add_paragraph(style='Body Text')
>>> p.style.name
# 'Body Text'

# применяем стиль по имени
>>> text_style = doc.styles['Body Text']
# применяем стиль как объект
>>> p = doc.add_paragraph(style=text_style)
>>> p.style.name
'Body Text'

Добавление/удаление пользовательского стиля документа.

О стилях в модуле python-docx можно думать как об определении CSS-классов в начале HTML-документа, а потом их применении к HTML-тегам. Например, после создания абзаца Paragraph можно изменить отдельные свойства его стиля: шрифт (размер, название), форматирование параграфа (межстрочный интервал, отступы) и т.д. Так вот, лучше всего создать пользовательский стиль (подобно CSS-классу), который объединит эти свойства в какую-то группу, а потом применять его при добавлении абзацев.

Пользовательские стили создаются и добавляются (преимущественно сразу после создании объекта документа) при помощи метода Document.styles.add_style(name, style_type, builtin=False), при этом, необходимо указать его уникальное (произвольное) имя name и тип, к которому относится создаваемый стиль style_type (задается перечислением WD_STYLE_TYPE).

Важно! Стиль, созданный, для абзаца (с типом WD_STYLE_TYPE.PARAGRAPH) нельзя применить, например, к таблице Table, так как тип стиля будет отличатся WD_STYLE_TYPE.TABLE.

from docx import Document
from docx.shared import Pt
from docx.enum.style import WD_STYLE_TYPE
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()
# создаем пользовательский стиль заголовка, с именем UserHead1
style = doc.styles.add_style('UserHead1', WD_STYLE_TYPE.PARAGRAPH)
style.font.name = 'Arial'
style.font.size = Pt(21)
style.font.underline = True
style.paragraph_format.alignment = WD_ALIGN_PARAGRAPH.CENTER
# Добавляем контент 
doc.add_paragraph('Пользовательский заголовок.', style='UserHead1')
doc.add_paragraph('Текст первого абзаца страницы 1' * 10)
doc.add_page_break()
doc.add_paragraph('Пользовательский заголовок.', style='UserHead1')
doc.add_paragraph('Текст первого абзаца страницы 2' * 10)
doc.save('test.docx')

Объект стиля можно удалить из документа, просто вызвав его метод doc.styles['ИмяСтиля'].delete():

>>> from docx import Document
>>> doc = Document()
>>> styles = doc.styles
>>> len(styles)
# 164
>>> styles['Body Text'].delete()
>>> len(styles)
# 163

Изменение существующего стиля документа.

Изменение существующего стиля документа, рассмотрим на встроенном стиле по умолчанию Получить стиль по умолчанию для конкретного типа можно при помощи свойства doc.styles.default(style_type):

Получим стиль абзаца по умолчанию:

>>> from docx import Document
>>> from docx.enum.style import WD_STYLE_TYPE
>>> doc = Document()
# получим стиль абзаца по умолчанию
>>> style = doc.styles.default(WD_STYLE_TYPE.PARAGRAPH)
>>> style.name
'Normal'

Имя стиля по умолчанию для абзаца документа MS Word является Normal. Изменение настроек этого стиля в любом месте кода Python применит сделанные изменения ко всему документу DOCX!!!

Смотрим пример:

from docx import Document
from docx.shared import Mm, Pt

doc = Document()
# добавим несколько абзацев с контентом 
doc.add_paragraph('Текст первого абзаца. ' * 5)
doc.add_paragraph('Текст второго абзаца.' * 5)
doc.add_paragraph('Текст третьего абзаца. ' * 5)
doc.add_paragraph('Текст четвертого абзаца.' * 5)

# Меняем стиль абзаца по умолчанию:
# получаем объект стиля `Normal`
style = doc.styles['Normal']
# изменяем настройки шрифта
style.font.name = 'Arial'
style.font.size = Pt(14)
# настраиваем красную строку абзаца
style.paragraph_format.first_line_indent = Mm(15)
doc.save('test.docx')

Методы и свойства объекта `Style`.

Style.base_style объект стиля, от которого наследуется этот стиль,
Style.builtin возвращает True если этот стиль является встроенным,
Style.delete() удаляет этот стиль из документа,
Style.element XML-элемент, проксируемый объектом этого стиля,
Style.name имя этого стиля в интерфейсе MS Word,
Style.type тип этого стиля, как член перечисления WD_STYLE_TYPE,
Style.font объект Font этого стиля,
Style.next_paragraph_style стиль, применяться к новому абзацу,
Style.paragraph_format объект ParagraphFormat этого стиля.

`Style.base_style`:

Свойство Style.base_style возвращает/устанавливает объект стиля, от которого наследуется этот стиль, или None, если этот стиль не основан на другом стиле.