Сообщить об ошибке.

Объект Table модуля python-docx

Доступ к таблице в документе docx

Объект Table модуля python-docx представляет собой прокси-объект, который оборачивает элемент WordprocessingML <w:tbl>.

Объект Table не создается вручную, а возвращается в результате вызова метода Document.add_table().

Пример добавления таблицы в документ :

from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH

# создание пустого документа
doc = Document()
# данные таблицы без названий колонок
items = (
    (7, '1024', 'Плюшевые котята'),
    (3, '2042', 'Меховые пчелы'),
    (1, '1288', 'Ошейники для пуделей'),
)
# добавляем таблицу с одной строкой 
# для заполнения названий колонок
table = doc.add_table(1, len(items[0]))
table.style = 'Table Grid'
# Получаем строку с колонками из добавленной таблицы 
head_cells = table.rows[0].cells
# добавляем названия колонок
for i, item in enumerate(['Кол-во', 'ID', 'Описание']):
    p = head_cells[i].paragraphs[0]
    # название колонки
    p.add_run(item).bold = True
    # выравниваем посередине
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
# добавляем данные к существующей таблице
for row in items:
    # добавляем строку с ячейками к объекту таблицы
    cells = table.add_row().cells
    for i, item in enumerate(row):
        # вставляем данные в ячейки
        cells[i].text = str(item)
        # если последняя ячейка
        if i == 2:
            # изменим шрифт
            cells[i].paragraphs[0].runs[0].font.name = 'Arial'
doc.save('test.docx')

Свойства и методы объекта Table.

Table.add_column(width):

Метод Table.add_column() добавляет колонку шириной width в крайний правый угол таблицы и возвращает экземпляр Column добавленной колонки.

Объект Column имеет свойства:

  • cells - последовательность экземпляров Cell, соответствующих ячейкам в этом столбце.
  • table - ссылка на объект таблицы Table, которому принадлежит этот столбец.
  • width - ширина этого столбца в величине EMU или None, если ширина явно не задана.

Table.add_row():

Метод Table.add_row() добавляет строку в самую нижнюю часть таблицы и возвращает экземпляр Row, только что добавленной строки.

Объект Row имеет свойства:

  • cells - последовательность экземпляров Cell, соответствующих ячейкам в этом столбце.
  • table - ссылка на объект таблицы Table, которому принадлежит этот столбец.
  • height - возвращает/устанавливает объект Length, представляющий высоту этой ячейки, или None, если высота явно не задана.
  • height_rule - возвращает/устанавливает правило высоты этой ячейки как член перечисления WD_ROW_HEIGHT_RULE или None, если явное правило высоты не установлено.

Table.alignment:

Свойство Table.alignment возвращает/устанавливает правило, которое определяет расположение этой таблицы между полями страницы. Значение является членом перечисления WD_TABLE_ALIGNMENT или None. Значение None говорит о том, что действующее значение наследуется от иерархии стилей.

Table.autofit:

Свойство Table.autofit принимает/возвращает True, если ширина столбцов автоматически регулируется для лучшего соответствия содержимому ячеек и False, если макет таблицы фиксированный.

Ширина столбца корректируется в любом случае, если общая ширина столбцов превышает ширину страницы.

Table.cell(row_idx, col_idx):

Метод Table.cell() возвращает экземпляр Сell, соответствующий ячейке таблицы на пересечении row_idx, col_idx, где (0, 0) является верхней, самой левой ячейкой.

Table.column_cells(column_idx):

Метод Table.column_cells() представляет собой последовательность ячеек Сell в столбце с номером column_idx в этой таблице.

Table.columns:

Свойство Table.columns представляет собой последовательность объектов столбцов Column в этой таблице.

Table.row_cells(row_idx):

Метод Table.row_cells() представляет собой последовательность ячеек Сell в строке с номером row_idx в этой таблице.

Table.rows:

Свойство Table.rows представляет собой последовательность строк Row в этой таблице. Поддерживает функцию len(), итерацию, доступ к строке по индексу, а так же получение среза строк.

Table.style:

Свойство Table.style устанавливает/возвращает объект стиля таблицы Style или Имя Стиля Таблицы, которое встроено в пользовательский интерфейс редактора MS Word.

Если таблица не имеет стиля, то возвращается стиль таблицы по умолчанию для документа (часто обычная таблица). Назначение этому свойству значения None удаляет любой применяемый напрямую стиль таблицы, заставляя его наследовать стиль таблицы документа по умолчанию.

Обратите внимание, что имя стиля таблицы немного отличается от имени, отображаемого в пользовательском интерфейсе MS Word. Дефис, если он есть, то его необходимо удалить. Например, Light Shading - Accent 1 становится Light Shading Accent 1.

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

Table.table_direction:

Свойство Table.table_direction это элемент WD_TABLE_DIRECTION, который указывает направление, в котором упорядочены ячейки таблицы, например, WD_TABLE_DIRECTION.LTR или WD_TABLE_DIRECTION.RTL.

Значение None указывает, что значение наследуется от иерархии стилей.

from docx.enum.table import WD_TABLE_DIRECTION

table = document.add_table(3, 3)
table.direction = WD_TABLE_DIRECTION.RTL

Свойства и методы объекта ячейки таблицы Cell.

Cell.add_paragraph(text='', style=None):

Метод Cell.add_paragraph() возвращает недавно добавленный абзац Paragraph в конец содержимого этой ячейки. Если присутствует текст text, то он добавляется к абзацу за один прогон Run. Если указан style, то применяется стиль для этого абзаца. Если стиль не указан или имеет значение None, то результат будет таким, как если бы был применен стиль с именем 'Normal'.

Обратите внимание, что на форматирование текста в ячейке может влиять стиль таблицы. Аргумент text может содержать символы табуляции \t, которые преобразуются в соответствующую XML-форму. Текст также может включать символы новой строки \n или возврата каретки \r, каждый из которых преобразуется в разрыв строки.

Cell.add_table(rows, cols):

Метод Cell.add_table() возвращает недавно добавленную таблицу Paragraph в конец содержимого этой ячейки. После таблицы добавляется пустой абзац, так как спецификация MS Word требует, чтобы последним элементом в каждой ячейке был абзац.

Cell.merge(other_cell):

Метод Cell.merge() возвращает объединенную ячейку, созданную путем охвата прямоугольной области, в которой эта ячейка и другая ячейка other_cell являются диагональными углами. Вызывает ошибку InvalidSpanError, если ячейки не определяют прямоугольную область.

Cell.paragraphs:

Свойство Cell.paragraphs представляет собой список объектов абзацев в ячейке. Ячейка таблицы должна содержать по крайней мере один элемент уровня блока и заканчиваться абзацем. По умолчанию новая ячейка содержит один абзац. Свойство только для чтения.

Cell.tables:

Свойство Cell.tables представляет собой список объектов таблиц в ячейке в порядке их появления. Свойство только для чтения.

Cell.text:

Свойство Cell.text представляет собой ВСЕ содержимое этой ячейки в виде строки текста. Назначение строки этому свойству заменяет все существующее содержимое одним абзацем Paragraph, содержащим назначенный текст, за один прогон Run.

Cell.vertical_alignment:

Свойство Cell.vertical_alignment возвращает/устанавливает вертикальное выравнивание ячейки как член перечисления WD_CELL_VERTICAL_ALIGNMENT или None.

Значение None указывает, что вертикальное выравнивание для этой ячейки унаследовано. Назначение None приводит к удалению явно определенного вертикального выравнивания и восстановлению наследования.

Cell.width:

Свойство Cell.width возвращает/устанавливает ширину этой ячейки в величине EMU или None, если ширина явно не задана.