Объект прогона Run в основном используется для создания абзаца по частям с целью стилизации отдельных слов/символов в абзаце, а так же добавления картинок в документ MS Word.
Объект Run не создается вручную, а возвращается в результате вызова метода Paragraph.add_run().
Run:from docx import Document from docx.shared import Pt, RGBColor from docx.enum.text import WD_UNDERLINE # создание документа doc = Document() # задаем стиль текста по умолчанию style = doc.styles['Normal'] style.font.name = 'Calibri' style.font.size = Pt(14) # добавляем абзац p = doc.add_paragraph('Пользовательское ') # добавляем в абзац текст прогоном с # целью стилизации отдельных слов run = p.add_run('форматирование ') # Форматируем: # размер шрифта run.font.size = Pt(16) # курсив run.font.italic = True # добавляем еще текст прогоном run = p.add_run('символов текста') # Форматируем: # название шрифта run.font.name = 'Arial' # размер шрифта run.font.size = Pt(18) # цвет текста run.font.color.rgb = RGBColor(255, 0, 0) # + жирный и подчеркнутый run.font.bold = True run.font.underline = WD_UNDERLINE.DOUBLE # прогон без стиля p.add_run(' в ') # прогон с простым подчеркиванием, так можно # делать, если применяется только одно свойство p.add_run('абзаце').underline = True # и последний прогон с точкой в конце # предложения (ее не подчеркиваем) run = p.add_run('.') doc.save('test.docx')
Run.Объект Run представляет собой прокси-объект, оборачивающий XML элемент
Некоторые свойства объекта Run принимают значение с тремя состояниями:
True - соответствуют включению свойства;False - соответствуют выключению свойства;None - означает, что действующее значение свойства берется/наследуется из иерархии стилей документа.Объект Run не создается вручную, а возвращается в результате вызова метода Paragraph.add_run().
Run.Run.add_break() добавляет в прогон элемент разрыва,Run.add_picture() добавляет в прогон изображение,Run.add_tab() добавляет в прогон символ табуляции,Run.add_text() добавляет в прогон текст,Run.bold выделяет текст прогона полужирным шрифтом,Run.clear() очищает прогон,Run.font доступ к форматированию сов/символов прогона,Run.italic выделяет текст прогона курсивом,Run.style возвращает или устанавливает стиля прогона по имени,Run.text возвращает или заменяет текст прогона,Run.underline подчеркивает текст прогона.Run.add_break(break_type=6):Метод Run.add_break() добавляет в этот прогон элемент разрыва, определенного типа break_type.
Аргумент break_type может принимать значения:
WD_BREAK.LINE - добавляет перенос строки.WD_BREAK.PAGE - добавляет разрыв страницы.WD_BREAK.COLUMN - добавляет разрыв колонки.в котором WD_BREAK импортируется из docx.enum.text, тип разрыва по умолчанию равен WD_BREAK.LINE.
Пример:
from docx import Document from docx.enum.text import WD_BREAK doc = Document() p = doc.add_paragraph() # добавляем прогон с текстом и переносом на следующую строку p.add_run('Пользовательское форматирование').add_break(WD_BREAK.LINE) p.add_run('символов текста в абзаце') # перенос строки можно добавить с помощью символа новой строки `\n` doc.add_paragraph('Перенос строки можно добавить\nс помощью символа новой строки') doc.save('test.docx')
По большому счету, метод Document.add_page_break() эквивалентен функции page_break(), которая определена в коде ниже:
from docx import Document def page_break(): """Метод Document.add_page_break()""" from docx.enum.text import WD_BREAK doc.add_paragraph().add_run().add_break(WD_BREAK.PAGE) doc.add_paragraph() doc = Document() page_break() doc.save('test.docx')
Run.add_picture(image_path_or_stream, width=None, height=None):Метод Run.add_picture() добавляет в конец этого прогона изображение image_path_or_stream. метод возвращает экземпляр InlineShape, содержащий это изображение.
Аргумент image_path_or_stream может быть строкой c путем к файлу с изображением или файловым объектом, содержащим двоичное изображение.
Если не указана ни ширина width, ни высота height, то изображение отображается в исходном размере. Если указан только один размер, то он используется для вычисления коэффициента масштабирования, который затем применяется к отсутствующему размеру, сохраняя соотношение сторон.
Собственный размер изображения рассчитывается с использованием значения точек на дюйм dpi, указанного в файле изображения. Если значение dpi не указано, как это часто бывает, то оно принимается равным 72 dpi.
Пример:
from docx import Document from docx.shared import Mm doc = Document() # добавляем пустой абзац p = doc.add_paragraph() # добавляем к абзацу прогон с картинкой p.add_run().add_picture('/path/to/image.jpg', width=Mm(25)) # добавляем к абзацу прогон с текстом p.add_run('Какой то текст какой то текст какой то текст') # новая страница doc.add_page_break() # добавляем абзац с пустым прогоном run = doc.add_paragraph().add_run() # добавляем картинку в прогон run.add_picture('/path/to/image.jpg', width=Mm(25)) # добавляем текст к прогону с картинкой run.add_text('Какой то текст какой то текст какой то текст') # смотрим, что получилось doc.save('test.docx')
По большому счету, метод Document.add_picture() эквивалентен функции add_img(), которая определена в коде ниже:
from docx import Document from docx.shared import Mm def add_img(image_path, width=None, height=None): """Метод Document.add_picture()""" doc.add_paragraph().add_run().add_picture(image_path, width, height) doc = Document() add_img('/path/to/image.jpg', width=Mm(25)) doc.save('test.docx')
Run.add_tab():Метод Run.add_tab() добавляет XML элемент <w:tab/> в конец прогона, который MS Word интерпретирует как символ табуляции.
Run.add_text(text):Метод Run.add_text() добавляет в прогон текст text, который соответствующий новому дочернему XML-элементу <w:t>.
Обратите внимание на возможно более удобный подход к назначению текста объекту прогона, при помощи свойства Run.text.
Пример:
from docx import Document doc = Document() p = doc.add_paragraph('') run = p.add_run('Добавляем') run.bold = True run.add_text(' текст к прогону.') p.add_run(' Это новый прогон.') doc.save('test.docx')
Run.bold:Свойство Run.bold выделяет текст прогона полужирным шрифтом. Может принимать три состояния.
paragraph.add_run('Какой то текст').bold = True # Эквивалентно run = paragraph.add_run('Какой то текст') run.bold = True # или run.font.bold = True
Run.clear():Метод Run.clear() удаляет/очищает все содержимое прогона, при этом все форматирование прогона сохраняется.
Возвращает ссылку на содержимое, которое удалилось.
Run.font:Свойство Run.font представляет собой объект Font, который предоставляет доступ к свойствам форматирования стов/символов для этого прогона, таким как имя шрифта, размер, цвет и т.д.
run = paragraph.add_run('Какой то текст') # название шрифта run.font.name = 'Arial' # размер шрифта run.font.size = Pt(18) # цвет текста run.font.color.rgb = RGBColor(0, 255, 0)
Run.italic:Свойство Run.italic выделяет текста прогона курсивом. Может принимать три состояния.
paragraph.add_run('Какой то текст').italic = True # Эквивалентно run = paragraph.add_run('Какой то текст') run.italic = True # или run.font.italic = True
Run.style:Свойство Run.style представляет собой объект Style или имя встроенного в MS Word стиля символа, которое будет применено к этому прогону.
Если к прогону не применен какой либо стиль слов/символов, то возвращается стиль символов по умолчанию для документа (часто шрифт символа по умолчанию). Установка для этого свойства значения None удаляет любой стиль символов, применяемый напрямую.
Важно!!! Значением этого свойства может быть Имя стиля символа, которое встроено в интерфейс MS Word. Встроенные стили хранятся в файле WordprocessingML под своим английским именем и не зависят от локализации MS Word. Так как модуль python-docx работает с файлом WordprocessingML, то и поиск стиля должен использовать английское имя. Если файл WordprocessingML не найден (MS Word не установлен, например в OS Linux) то модуль python-docx работает со своей версией этого файла.
Пользовательские стили, которые ВЫ сами создали/настроили, не локализованы и доступны по имени, как они отображается в пользовательском интерфейсе MS Word.
Run.text:Свойство Run.text представляет собой строку, сформированную путем объединения текстового эквивалента каждого дочернего элемента прогона в строку Python. Каждый дочерний XML-элемент <w:t> добавляет содержащиеся в нем текстовые символы. Дочерний элемент <w:tab/> добавляет символ \t. Каждый дочерний элемент <w:cr/> или <w:br> добавляет символ \n.
Обратите внимание, что элемент <w:br> может указывать на разрыв страницы или столбца, а также на разрыв строки. Все элементы <w:br> переводятся в один символ \n независимо от их типа. Все остальные дочерние элементы содержимого, такие как <w:drawing>, игнорируются.
Присвоение текста этому свойству имеет обратный эффект, переводя каждый символ \t в элемент <w:tab/>, а каждый символ \n или \r в элемент <w:cr/>. Все существующее содержимое прогона заменяется. Форматирование прогона сохраняется.
Run.underline:Свойство Run.underline подчеркивает текст прогона определенным стилем. Может принимать значения: None, True, False или значение из WD_UNDERLINE.
None - указывает на то, что прогон наследует значение подчеркивания содержащего абзаца, при этом удаляет все напрямую применяемые значения подчеркивания. False - указывает на настройку прогона без подчеркивания, переопределяющую любое унаследованное значение. True - указывает одинарное подчеркивание. WD_UNDERLINE используются для определения других стилей подчеркивания, таких как двойное, волнистое и пунктирное и т.д.Смотрим пример:
import docx from docx.enum.text import WD_UNDERLINE doc = docx.Document() p = doc.add_paragraph() p.add_run('Подчеркивает только слова.\n').underline = WD_UNDERLINE.WORDS p.add_run('Подчеркивает точками.\n').underline = WD_UNDERLINE.DOTTED p.add_run('Подчеркивает двойной линией.\n').underline = WD_UNDERLINE.DOUBLE p.add_run('Подчеркивает волнистой линией.').underline = WD_UNDERLINE.WAVY doc.save('test.docx')