Объект Paragraph модуля python-docx представляет собой прокси-объект, который оборачивает XML-элемент <w:p> MS Word документа.
Объект Paragraph не создается вручную, а возвращается в результате вызова метода Document.add_paragraph().
Например:
from docx import Document # создание пустого документа doc = Document() # добавляем абзац с текстом # в результате возвращается объект `Paragraph` p = doc.add_paragraph('Начало строки абзаца, ') # добавляем к абзацу текст p.add_run('а это продолжение строки, ') # и еще раз p.add_run('добавленное как прогон.') doc.save('test.docx')
Paragraph.add_run() добавляет прогон текста в конец абзаца,Paragraph.alignment выравнивание текста в абзаце,Paragraph.clear() очищает содержимое абзаца,Paragraph.insert_paragraph_before() вставляет новый абзац перед текущем абзацем,Paragraph.paragraph_format доступ к свойствам форматирования абзаца,Paragraph.runs список экземпляров прогонов,Paragraph.style стиль, присвоенный абзацу,Paragraph.text весь текст абзаца.Paragraph.add_run(text=None, style=None):Метод Paragraph.add_run() добавляет прогон к этому абзацу, содержащий текст text и имеющий стиль символов style, идентифицируемый стилем идентификатора стиля.
Аргумент style - это встроенный или созданный пользователем стиль в интерфейсе MS Word. Типа Paragraph.style, только тот, который можно применить к символам текста, а не к абзацу целиком. Может быть объектом стиля абзаца Style.
Аргумент text может содержать символы табуляции \t, которые преобразуются в соответствующую XML-форму, а также может содержать символы новой строки \n или возврата каретки \r, каждый из которых преобразуется в разрыв строки.
Метод возвращает объект прогона Run, который дает больше контроля над форматированием текста этого прогона (например: выделение цветом, другой шрифт, его размер и т.д.).
Прогоны в основном используются для пользовательского форматирования текста внутри абзаца. Форматирование на уровне символов, например полужирный и курсив, применяется на уровне прогона paragraph.add_run(). Прогонов в абзаце может быть больше одного. Таким образом, для абзаца с полужирным словом посередине требуется три прогона: обычный, полужирный - содержащий слово, и еще один нормальный для текста после него.
Смотрим пример:
from docx import Document doc = Document() # добавляем пустой параграф p = doc.add_paragraph() # формируем абзац прогонами текста p.add_run('Этот абзац ') # прогон напишем курсивом p.add_run('формируется частями').italic = True p.add_run(', которые добавляются ') # этот прогон сделаем жирным p.add_run('прогонами').bold = True p.add_run(' с текстом.') doc.save('test.docx')
Paragraph.alignment:Свойство Paragraph.alignment - представляет собой перечисление WD_PARAGRAPH_ALIGNMENT, которое определяет настройку выравнивания для этого абзаца.
Значение None указывает, что абзац не имеет прямого значения выравнивания и унаследует это значение из своей иерархии стилей. Назначение None этому свойству удаляет любое значение выравнивания, которое было указано напрямую.
from docx import Document from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.shared import Pt doc = Document() # добавляем пустой параграф p = doc.add_paragraph() # Выравниваем абзац по середине p.alignment = WD_ALIGN_PARAGRAPH.CENTER run = p.add_run('Заголовок, размером 24 pt.') # размер шрифта run.font.size = Pt(24) run.bold = True doc.save('test.docx')
Paragraph.clear():Метод Paragraph.clear() удаляет/очищает все содержимое этого абзаца и возвращает его. При этом сохраняется форматирование на уровне абзаца, такое как стиль.
Paragraph.insert_paragraph_before(text=None, style=None):Метод Paragraph.insert_paragraph_before() вставляет новый абзац с текстом text и стилем style непосредственно перед абзацем Paragraph. Метод возвращает объект вновь созданного абзаца.
Если аргумент text не пустая строка и не None, то новый абзац будет содержать этот текст, добавленный за один прогон. Если указан стиль style, то этот стиль назначается новому абзацу.
from docx import Document doc = Document() # добавляем абзаца p = doc.add_paragraph('Второй абзац.') # вставляем новый абзац перед абзацем `p` prior = p.insert_paragraph_before('Первый абзац.') # стиль первого абзаца prior.style = 'Intense Quote' doc.save('test.docx')
Метод кажется бессмысленным, но это только первое впечатление. Он помогает при редактировании документа, т.к. позволяет вставить нужный абзац в середину документа!!! Например, можно найти объект того абзаца, перед которым нужно вставить новый при помощи регулярных выражений и дело в шляпе...
Paragraph.paragraph_format:Свойство Paragraph.paragraph_format представляет собой объект ParagraphFormat, который предоставляет доступ к свойствам форматирования для этого абзаца, таким как межстрочный интервал, отступ и т. д.
Простой способ форматировать абзац/параграф:
from docx import Document from docx.shared import Mm doc = Document() # Добавляем абзац p = doc.add_paragraph('Новый абзац с отступами и красной строкой.') # получаем объект форматирования fmt = p.paragraph_format # Форматируем: # добавляем отступ слева fmt.first_line_indent = Mm(15) # добавляем отступ до абзаца fmt.space_before = Mm(20) # добавляем отступ слева fmt.space_after = Mm(10) doc.add_paragraph('Новый абзац.') doc.add_paragraph('Еще новый абзац.') doc.save('test.docx')
Paragraph.runs:Свойство Paragraph.runs список экземпляров прогонов Run этого абзаца, которые соответствуют XML-элементам <w:r> в этом параграфе.
Это свойство, например, можно использовать для извлечения текста абзаца не целиком, а по прогонам, или изменения стилей прогонов абзаца...
Например получить текст всех прогонов определенного абзаца, заданного как p, можно как-то так:
runs_txt = [] for run in p.runs: runs_txt.append(run.text) print(''.join(runs_txt))
Paragraph.style:Свойство Paragraph.style представляет собой объект Style, присвоенный этому абзацу. Если абзацу не присвоен явный стиль, то его значением является стиль абзаца по умолчанию для документа. Значение свойства .style можно как считывать, так и присвоить новое.
Значением Paragraph.style может быть Имя стиля абзаца, которое встроено в интерфейс MS Word.
Присвоение значения None удаляет любой примененный стиль, делая его эффективное значение стилем абзаца по умолчанию для документа.
Важно!!! Встроенные стили хранятся в файле WordprocessingML под своим английским именем, например 'Heading 1', и не зависят от локализации MS Word. Так как модуль python-docx работает с файлом WordprocessingML, то поиск стиля должен использовать английское имя. Если файл WordprocessingML не найден (MS Word не установлен, например в OS Linux) то модуль python-docx работает со своей версией этого файла. Что бы создать сопоставление между именами стилей на русском языке и именами на английском языке посетите эту ссылку.
Пользовательские стили, также известные как настраиваемые стили, не локализованы и доступны по имени, как оно отображается в пользовательском интерфейсе Word.
from docx import Document doc = Document() # добавляем параграф p = doc.add_paragraph("Cтиль абзаца 'List Number'.") # применяем стиль p.style = 'List Number' # добавляем параграф и сразу применяем стиль p = doc.add_paragraph('Встроен в MS Office.').style = 'List Number' # добавляем параграф, стиль передаем как аргумент doc.add_paragraph('Cтиль абзаца.', style='List Bullet') doc.add_paragraph('Обычный список.', style='List Bullet') doc.save('test.docx')
Paragraph.text:Свойство Paragraph.text представляет собой строку, сформированную путем объединения текста каждого прогона в абзаце. Табуляции и разрывы строк в XML сопоставляются символам \t и \n соответственно.
# получение текста абзаца p_text = p.text print(p_text) # эквивалентно runs_txt = [] for run in p.runs: runs_txt.append(run.text) print(''.join(runs_txt))
Присвоение текста этому свойству приводит к замене всего существующего содержимого абзаца за один прогон Paragraph.add_run(). Символ \t в тексте сопоставляется элементу <w:tab/>, а каждый символ \n или \r сопоставляется с разрывом строки. Форматирование на уровне абзаца, такое как стиль абзаца, сохраняется. Форматирование на уровне прогонов (объектов Run), такое как жирный шрифт, курсив или цвет текста прогона, удаляется.