Работа с таблицами

Работа с таблицами

Таблицы в Aspose.Words FOSS for .NET представлены Aspose.Words.Tables пространство имён: Table, Row, и Cell образуют трехуровневую составную иерархию узлов, расположенную в дереве документа рядом с абзацами. На этой странице рассматривается построение таблиц с DocumentBuilder, форматированием строк и ячеек, управлением общим макетом таблицы и объединением ячеек.

Объектная модель таблицы

Table — это CompositeNode, содержащий Row узлов, и каждый Row — это CompositeNode, содержащий Cell узлов; Cell в свою очередь содержит абзацы и, при необходимости, вложенные таблицы. Table.Rows возвращает RowCollection, Row.Cells возвращает CellCollection, а Body или другой Story раскрывает каждую таблицу верхнего уровня в нём через свойство Tables, которое является TableCollection. Все три коллекции поддерживают Add(), Insert(), Remove(), RemoveAt(), Contains() и IndexOf(). Table.EnsureMinimum(), Row.EnsureMinimum() и Cell.EnsureMinimum() каждый заполняет минимально допустимое содержимое, необходимое узлу данного типа (соответственно пустую строку, пустую ячейку или пустой абзац) после того, как программные правки оставят его без него.

Создание таблиц с помощью DocumentBuilder

DocumentBuilder.StartTable() начинает новую таблицу в позиции курсора, InsertCell() добавляет ячейку в текущую строку, EndRow() закрывает текущую строку, а EndTable() закрывает таблицу. Установите DocumentBuilder.CellFormat и DocumentBuilder.RowFormat перед вызовом InsertCell() или EndRow(), чтобы применить форматирование по умолчанию к ячейкам и строкам при их создании — эти свойства действуют как шаблон для содержимого, которое построитель вставит дальше, а не как ретроактивное изменение уже существующих ячеек в документе.

Форматирование ячеек и строк

Cell.CellFormat представляет собой экземпляр CellFormat (Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth, LeftPadding, RightPadding, TopPadding, BottomPadding, HideMark, Orientation) с ClearFormatting() для сброса и SetPaddings() для установки всех четырёх отступов ячейки одновременно. Row.RowFormat представляет собой экземпляр RowFormat (Borders, Height, HeightRule, AllowBreakAcrossPages, HeadingFormat) со своим собственным ClearFormatting().

Форматирование всей таблицы и AutoFit

Table сам по себе раскрывает свойства макета — Alignment (TableAlignment), Bidi, LeftIndent, PreferredWidth, Style, StyleIdentifier, StyleName, StyleOptions (TableStyleOptions), TextWrapping, а также метаданные доступности через Title и Description. Table.AutoFit(AutoFitBehavior) изменяет размер таблицы и её ячеек в соответствии с заданным поведением. SetBorder() задаёт одну сторону границы, а SetBorders() задаёт все границы одинаковым стилем линии, шириной и цветом по всей таблице; ClearBorders() и ClearShading() сбрасывают их. ConvertToHorizontallyMergedCells() преобразует ячейки, объединённые по совпадающей ширине, в ячейки, явно помеченные HorizontalMerge.

Предпочтительные и ширины ячеек

PreferredWidth представляет ширину и её единицу измерения, создаётся с помощью статических фабричных методов PreferredWidth.FromPercent() или PreferredWidth.FromPoints(); PreferredWidthType определяет, какой тип значения (Auto, Percent или Points) содержит данный PreferredWidth. Как Table.PreferredWidth, так и CellFormat.PreferredWidth принимают эти значения.

Объединённые ячейки

CellFormat.HorizontalMerge и CellFormat.VerticalMerge (CellMerge) указывают, как ячейка участвует в горизонтальном или вертикальном объединении с соседями. CellVerticalAlignment управляет вертикальным выравниванием содержимого в ячейке, независимо от состояния объединения.

Советы и лучшие практики

• Закройте каждый StartTable() соответствующим EndRow() в каждой строке и финальным EndTable() – незакрытая строка или таблица приводит к некорректному внутреннему состоянию билдера (и к искажённому дереву документа).
• Установите DocumentBuilder.CellFormat и DocumentBuilder.RowFormat перед каждым вызовом InsertCell() или EndRow(), если разные строки или ячейки в одной таблице требуют различного форматирования; билдер применяет то, что в данный момент установлено при вставке.
• Вызовите Table.EnsureMinimum(), Row.EnsureMinimum() или Cell.EnsureMinimum() после программного удаления содержимого, чтобы узел сохранял минимальную корректную структуру, ожидаемую Word.
• Используйте PreferredWidth.FromPercent() для таблиц, которые должны адаптироваться к доступной ширине страницы, и PreferredWidth.FromPoints() для фиксированной ширины макета.
• AutoFitBehavior применяется, когда вы вызываете Table.AutoFit() – он не запускается постоянно при добавлении или удалении содержимого, поэтому вызовите его снова после значительных правок, если требуется переадаптация таблицы.

Распространённые проблемы

FAQ

Как создать таблицу с нуля с помощью DocumentBuilder?

Вызовите StartTable(), затем InsertCell() для каждой ячейки в строке, EndRow() для закрытия строки, повторите для дополнительных строк и, наконец, EndTable() для закрытия таблицы.

Как установить ширину таблицы в процентах вместо фиксированной ширины?

Назначьте Table.PreferredWidth = PreferredWidth.FromPercent(value) вместо PreferredWidth.FromPoints(value).

Как сбросить всё форматирование в ячейке или строке?

Вызовите CellFormat.ClearFormatting() на CellFormat ячейки, либо RowFormat.ClearFormatting() на RowFormat строки.

Как задать границы и затенение для всей таблицы сразу?

Используйте Table.SetBorders() для одинаковой границы со всех сторон, Table.SetBorder() для одной стороны за раз, и Table.SetShading() для равномерного затенения; ClearBorders() и ClearShading() сбрасывают их.

API Reference Сводка

См. также:

• Aspose.Words for .NET — Enterprise Documentation