Применить форматирование таблицы

К каждому элементу таблицы можно применить различное форматирование. Например, форматирование таблицы будет применено ко всей таблице, форматирование строк - только к определенным строкам, форматирование ячеек - только к определенным ячейкам.

Aspose.Words предоставляет расширенные возможности API для извлечения и применения форматирования к таблице. Вы можете использовать узлы Table, RowFormat и CellFormat для настройки форматирования.

В этой статье мы поговорим о том, как применить форматирование к различным узлам таблицы и какие настройки форматирования таблицы поддерживает Aspose.Words.

Применить форматирование к различным узлам

В этом разделе мы рассмотрим применение форматирования к различным узлам таблицы.

Форматирование на уровне таблицы

Чтобы применить форматирование к таблице, вы можете использовать свойства, доступные на соответствующем узле Table, используя классы Table, PreferredWidth и TableCollection.

Обратите внимание, что в таблице должна быть хотя бы одна строка, прежде чем можно будет применить свойства таблицы. Это означает, что при построении таблицы с DocumentBuilder это форматирование должно выполняться после первого вызова InsertCell, или после добавления первой строки в таблицу, или когда узлы вставляются непосредственно в DOM.

На рисунках ниже показано представление функций форматирования Table в Microsoft Word и соответствующих им свойств в Aspose.Words.

В следующем примере кода показано, как применить контурную границу к таблице:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);
// Align the table to the center of the page.
table.setAlignment(TableAlignment.CENTER);
// Clear any existing borders from the table.
table.clearBorders();

// Set a green border around the table but not inside.
table.setBorder(BorderType.LEFT, LineStyle.SINGLE, 1.5, Color.GREEN, true);
table.setBorder(BorderType.RIGHT, LineStyle.SINGLE, 1.5, Color.GREEN, true);
table.setBorder(BorderType.TOP, LineStyle.SINGLE, 1.5, Color.GREEN, true);
table.setBorder(BorderType.BOTTOM, LineStyle.SINGLE, 1.5, Color.GREEN, true);

// Fill the cells with a light green solid color.
table.setShading(TextureIndex.TEXTURE_SOLID, Color.lightGray, new Color(0, true));

doc.save(getArtifactsDir() + "WorkingWithTableStylesAndFormatting.ApplyOutlineBorder.docx");

В следующем примере кода показано, как создать таблицу с включенными всеми границами (grid):

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);
        
// Clear any existing borders from the table.
table.clearBorders();
        
// Set a green border around and inside the table.
table.setBorders(LineStyle.SINGLE, 1.5, Color.GREEN);

doc.save(getArtifactsDir() + "WorkingWithTableStylesAndFormatting.BuildTableWithBorders.docx");

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

Форматированием на уровне строк** можно управлять с помощью классов Row, RowFormat и RowCollection.

Обратите внимание, что Row может быть только дочерним узлом для Table. В то же время в Row должен быть хотя бы один Cell, чтобы к нему можно было применить форматирование.

На рисунках ниже показано представление функций форматирования Row в Microsoft Word и соответствующих им свойств в Aspose.Words.

В следующем примере кода показано, как изменить форматирование строк таблицы:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);
        
// Retrieve the first row in the table.
Row firstRow = table.getFirstRow();
firstRow.getRowFormat().getBorders().setLineStyle(LineStyle.NONE);
firstRow.getRowFormat().setHeightRule(HeightRule.AUTO);
firstRow.getRowFormat().setAllowBreakAcrossPages(true);

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

Форматирование на уровне ячеек контролируется классами Cell, CellFormat и CellCollection.

Обратите внимание, что Cell может быть только дочерним узлом Row. В то же время в Cell должен быть хотя бы один Paragraph, чтобы к нему можно было применить форматирование.

В дополнение к Paragraph вы также можете вставить Table в Cell.

На рисунках ниже показано представление функций форматирования Cell в Microsoft Word и соответствующих им свойств в Aspose.Words.

В следующем примере кода показано, как изменить форматирование ячейки таблицы:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");
Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);

Cell firstCell = table.getFirstRow().getFirstCell();
firstCell.getCellFormat().setWidth(30.0);
firstCell.getCellFormat().setOrientation(TextOrientation.DOWNWARD);
firstCell.getCellFormat().getShading().setForegroundPatternColor(Color.GREEN);

В следующем примере кода показано, как задать количество пробелов (в пунктах), добавляемых к левому/верхнему/правому/нижнему краю содержимого ячейки:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.startTable();
builder.insertCell();

// Sets the amount of space (in points) to add to the left/top/right/bottom of the cell's contents.
builder.getCellFormat().setPaddings(30.0, 50.0, 30.0, 50.0);
builder.writeln("I'm a wonderful formatted cell.");

builder.endRow();
builder.endTable();

doc.save(getArtifactsDir() + "WorkingWithTableStylesAndFormatting.CellPadding.docx");

Указание высоты строк

Самый простой способ задать высоту строки - использовать параметр DocumentBuilder. Используя соответствующие свойства RowFormat, вы можете установить значение высоты по умолчанию или применить различную высоту для каждой строки в таблице.

В Aspose.Words высота строки таблицы регулируется с помощью:

• свойство высоты строки – Height
• свойство правила высоты для данной строки – HeightRule

В то же время для каждой строки можно задать разную высоту – это позволяет вам широко управлять настройками таблицы.

Параметры правила для указания высоты объекта можно задать с помощью полей HeightRule.

В следующем примере кода показано, как создать таблицу, содержащую одну ячейку, и применить форматирование строк:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Table table = builder.startTable();
builder.insertCell();

RowFormat rowFormat = builder.getRowFormat();
rowFormat.setHeight(100.0);
rowFormat.setHeightRule(HeightRule.EXACTLY);
        
// These formatting properties are set on the table and are applied to all rows in the table.
table.setLeftPadding(30.0);
table.setRightPadding(30.0);
table.setTopPadding(30.0);
table.setBottomPadding(30.0);

builder.writeln("I'm a wonderful formatted row.");

builder.endRow();
builder.endTable();

doc.save(getArtifactsDir() + "WorkingWithTableStylesAndFormatting.ApplyRowFormatting.docx");

Укажите ширину таблицы и ячеек

Таблица в документе Microsoft Word предоставляет несколько различных способов изменения размера таблицы и отдельных ячеек. Эти свойства позволяют в значительной степени контролировать внешний вид и поведение таблицы, так что Aspose.Words поддерживает поведение таблиц, как в Microsoft Word.

Важно знать, что элементы таблицы обладают несколькими различными свойствами, которые могут влиять на то, как рассчитывается ширина всей таблицы, а также отдельных ячеек:

• Предпочтительная ширина таблицы
• Предпочтительная ширина отдельных ячеек
• Включение автоматической подгонки по таблице

В этой статье подробно описывается, как работают различные свойства вычисления ширины таблицы и как получить полный контроль над вычислением ширины таблицы. Это особенно полезно знать это в тех случаях, когда макет таблицы отображается не так, как ожидалось.

В большинстве случаев рекомендуется использовать предпочтительную ячейку, а не ширину таблицы. Предпочтительная ширина ячейки в большей степени соответствует спецификации формата DOCX, а также модели Aspose.Words.

Ширина ячейки на самом деле является расчетным значением для формата DOCX. Фактическая ширина ячейки может зависеть от многих факторов. Например, изменение полей страницы или предпочтительной ширины таблицы может повлиять на фактическую ширину ячейки.

Предпочтительная ширина ячейки - это свойство ячейки, которое хранится в документе. Оно ни от чего не зависит и не меняется при изменении таблицы или других свойств ячейки.

Все свойства и методы, описанные в этой статье, связаны с тем, как работают таблицы в Microsoft Word. Таким образом, в большинстве случаев, если вы создаете свою таблицу программно, но вам трудно создать нужную таблицу, вы можете вместо этого сначала попробовать визуально создать ее в Microsoft Word, а затем просто скопировать значения форматирования в свое приложение.

Как использовать предпочтительную ширину

Желаемая ширина таблицы или отдельных ячеек определяется с помощью свойства preferred width, которое представляет собой размер, который должен соответствовать элементу. То есть предпочтительная ширина может быть указана как для всей таблицы, так и для отдельных ячеек. В некоторых ситуациях может оказаться невозможным точно установить эту ширину, но в большинстве случаев фактическая ширина будет близка к этому значению.

Соответствующий предпочтительный тип и значение ширины устанавливаются с помощью методов класса PreferredWidth:

• поле Auto для указания автоматической ширины или “нет предпочтительной ширины”
• метод FromPercent для указания процентной ширины
• метод FromPoints для указания ширины в точках

На рисунках ниже показано представление preferred width setting features в Microsoft Word и соответствующих им свойств в Aspose.Words.

Пример того, как эти параметры применяются к реальной таблице в документе, можно увидеть на рисунке ниже.

Прежде чем вы сможете использовать предпочтительную ширину в таблице, вы должны убедиться, что таблица содержит хотя бы одну строку. Это связано с тем, что такое форматирование таблицы в документе Microsoft Word или в документе, созданном в Aspose.Words, сохраняется в строках таблицы.

Укажите предпочтительную ширину таблицы или ячейки

В Aspose.Words ширина таблицы и ячеек задается с помощью свойств Table.PreferredWidth и CellFormat.PreferredWidth, а параметры доступны в перечислении PreferredWidthType:

• Auto, что эквивалентно отсутствию предпочтительной установленной ширины
• Percent, который соответствует размеру элемента относительно доступного пространства в окне или контейнера и пересчитывает значение при изменении доступной ширины
• Points, который соответствует элементу заданной ширины в точках

По умолчанию таблица может быть указана как занимающая 100% доступного пространства на странице. В данном случае это означает, что таблица будет пытаться занять пространство между левым и правым полями страницы.

Использование свойства Table.PreferredWidth позволяет настроить ее предпочтительную ширину относительно контейнера: страницы, текстового столбца или ячейки внешней таблицы, если это вложенная таблица.

В следующем примере кода показано, как настроить автоматическое соответствие таблицы 50% ширины страницы:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a table with a width that takes up half the page width.
Table table = builder.startTable();

builder.insertCell();
table.setPreferredWidth(PreferredWidth.fromPercent(50.0));
builder.writeln("Cell #1");

builder.insertCell();
builder.writeln("Cell #2");

builder.insertCell();
builder.writeln("Cell #3");

doc.save(getArtifactsDir() + "WorkingWithTables.AutoFitToPageWidth.docx");

Использование свойства CellFormat.PreferredWidth для данной ячейки позволит настроить ее предпочтительную ширину.

В следующем примере кода показано, как установить различные предпочтительные параметры ширины:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a table row made up of three cells which have different preferred widths.
builder.startTable();

// Insert an absolute sized cell.
builder.insertCell();
builder.getCellFormat().setPreferredWidth(PreferredWidth.fromPoints(40.0));
builder.getCellFormat().getShading().setBackgroundPatternColor(Color.YELLOW);
builder.writeln("Cell at 40 points width");

// Insert a relative (percent) sized cell.
builder.insertCell();
builder.getCellFormat().setPreferredWidth(PreferredWidth.fromPercent(20.0));
builder.getCellFormat().getShading().setBackgroundPatternColor(Color.BLUE);
builder.writeln("Cell at 20% width");

// Insert a auto sized cell.
builder.insertCell();
builder.getCellFormat().setPreferredWidth(PreferredWidth.AUTO);
builder.getCellFormat().getShading().setBackgroundPatternColor(Color.GREEN);
builder.writeln(
    "Cell automatically sized. The size of this cell is calculated from the table preferred width.");
builder.writeln("In this case the cell will fill up the rest of the available space.");

doc.save(getArtifactsDir() + "WorkingWithTables.PreferredWidthSettings.docx");

Найдите предпочтительный тип и значение ширины

Вы можете использовать свойства Type и Value, чтобы найти предпочтительную ширину нужной таблицы или ячейки.

В следующем примере кода показано, как получить предпочтительный тип ширины ячейки таблицы:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);
table.setAllowAutoFit(true);

Cell firstCell = table.getFirstRow().getFirstCell();
/*PreferredWidthType*/int type = firstCell.getCellFormat().getPreferredWidth().getType();
double value = firstCell.getCellFormat().getPreferredWidth().getValue();

Как настроить автоматическую подгонку

Свойство AllowAutoFit позволяет ячейкам таблицы увеличиваться и уменьшаться в размере в соответствии с выбранным критерием. Например, вы можете использовать параметр AutoFit to Window, чтобы таблица соответствовала ширине страницы, а параметр AutoFit to Content - чтобы разрешить каждой ячейке увеличиваться или уменьшаться в размере в соответствии с ее содержимым.

Кроме того, свойство AllowAutoFit можно использовать в сочетании с предпочтительной шириной ячейки для форматирования ячейки, которая автоматически соответствует ее содержимому, но также имеет начальную ширину. При необходимости ширина ячейки может превышать эту ширину.

По умолчанию Aspose.Words вставляет новую таблицу, используя AutoFit to Window. Размер таблицы будет соответствовать доступной ширине страницы. Чтобы изменить размер таблицы, вы можете вызвать метод AutoFit. Этот метод принимает перечисление AutoFitBehavior, которое указывает, какой тип автозаполнения применяется к таблице.

Важно знать, что метод автозаполнения на самом деле является сокращением, которое одновременно применяет различные свойства к таблице. Это свойства, которые на самом деле обеспечивают наблюдаемое поведение таблицы. Мы обсудим эти свойства для каждого параметра автозаполнения.

В следующем примере кода показано, как настроить таблицу на сжатие или увеличение каждой ячейки в соответствии с ее содержимым:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
table.setAllowAutoFit(true);

В качестве демонстрации мы будем использовать следующую таблицу для применения различных настроек автоматической подгонки.

AutoFit От таблицы к окну

Когда к таблице применяется автоматическая подгонка под окно, фактически за кулисами выполняются следующие операции:

1. Свойство Table.AllowAutoFit позволяет автоматически изменять размер столбцов в соответствии с доступным содержимым, используя значение Table.PreferredWidth, равное 100%
2. CellFormat.PreferredWidth удаляется из всех ячеек таблицы
   Обратите внимание, что это немного отличается от поведения Microsoft Word, когда для предпочтительной ширины каждой ячейки устанавливаются соответствующие значения в зависимости от их текущего размера и содержимого. Aspose.Words не обновляет предпочтительную ширину, поэтому вместо этого они просто очищаются.
3. Ширина столбцов пересчитывается с учетом текущего содержимого таблицы – конечным результатом является таблица, занимающая всю доступную ширину
4. Ширина столбцов в таблице изменяется автоматически по мере того, как пользователь редактирует текст

В следующем примере кода показано, как автоматически подогнать таблицу под ширину страницы:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);
// Autofit the first table to the page width.
table.autoFit(AutoFitBehavior.AUTO_FIT_TO_WINDOW);

doc.save(getArtifactsDir() + "WorkingWithTables.AutoFitTableToWindow.docx");

Пример того, как эти параметры применяются к приведенной выше таблице, можно увидеть на рисунке ниже.

AutoFit Таблица с содержимым

Когда в таблицу автоматически добавляется содержимое, следующие шаги фактически выполняются за кулисами:

1. Свойство Table.AllowAutoFit позволяет автоматически изменять размер каждой ячейки в соответствии с ее содержимым

2. Предпочтительная ширина таблицы удаляется из Table.PreferredWidth, CellFormat.PreferredWidth удаляется для каждой ячейки таблицы

   Обратите внимание, что этот параметр автоматической подгонки удаляет предпочтительную ширину из ячеек, как и в Microsoft Word. Если вы хотите сохранить размеры столбцов и увеличить или уменьшить их в соответствии с содержимым, вам следует установить для свойства Table.AllowAutoFit значение True само по себе, а не использовать ярлык автоматической подгонки.

3. Ширина столбцов пересчитывается для текущего содержимого таблицы – конечным результатом является таблица, в которой ширина столбцов и ширина всей таблицы автоматически изменяются, чтобы наилучшим образом соответствовать содержимому, когда пользователь редактирует текст

В следующем примере кода показано, как автоматически подогнать таблицу к ее содержимому:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);
table.autoFit(AutoFitBehavior.AUTO_FIT_TO_CONTENTS);

doc.save(getArtifactsDir() + "WorkingWithTables.AutoFitTableToContents.docx");

Пример того, как эти параметры применяются к приведенной выше таблице, можно увидеть на рисунке ниже.

Отключите AutoFit в таблице и используйте фиксированную ширину столбцов

Если в таблице отключена автоматическая подгонка и вместо нее используется фиксированная ширина столбцов, выполняются следующие действия:

1. Table.AllowAutoFit свойство отключено, поэтому столбцы не увеличиваются и не сжимаются до их содержимого
2. Предпочтительная ширина всей таблицы удаляется из Table.PreferredWidth, CellFormat.PreferredWidth удаляется из всех ячеек таблицы
3. Конечным результатом является таблица, ширина столбцов которой определяется свойством CellFormat.Width и размер столбцов которой не изменяется автоматически при вводе пользователем текста или при изменении размера страницы

Обратите внимание, что если для параметра CellFormat.Width ширина не указана, то используется значение по умолчанию в один дюйм (72 пункта).

В следующем примере кода показано, как отключить автозаполнение и включить фиксированную ширину для указанной таблицы:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);
// Disable autofitting on this table.
table.autoFit(AutoFitBehavior.FIXED_COLUMN_WIDTHS);

doc.save(getArtifactsDir() + "WorkingWithTables.AutoFitTableToFixedColumnWidths.docx");

Пример того, как эти параметры применяются к приведенной выше таблице, можно увидеть на рисунке ниже.

Порядок приоритета при вычислении ширины ячейки

Aspose.Words позволяет пользователям определять ширину таблицы или ячейки с помощью нескольких объектов, включая CellFormat – его свойство Width в основном осталось от предыдущих версий, однако оно по-прежнему полезно для упрощения настройки ширины ячейки.

Важно знать, что свойство CellFormat.Width работает по-разному в зависимости от того, какие из других свойств ширины уже существуют в таблице.

Aspose.Words для вычисления ширины ячеек используется следующий порядок:

Заказ	Собственность	Описание
	AllowAutoFit определяется	Если параметр AutoFit включен: - размер таблицы может превышать желаемую ширину для размещения содержимого – обычно он не уменьшается ниже желаемой ширины - любое изменение значения CellFormat.Width игнорируется, и вместо этого ячейка будет соответствовать своему содержимому
	PreferredWidthType со значением Points или Percent	CellFormat.Width игнорируется
	PreferredWidthType со значением Auto	Значение из CellFormat.Width копируется и становится предпочтительной шириной ячейки (в пунктах)

Любые изменения свойства width не обновляются в соответствии с предпочтительной шириной и должны быть применены к предпочтительной ширине.

При создании фиксированного формата таблицы укажите ширину ячейки. Ячейка без ширины не может быть сохранена в формате DOC. Форматы документов, отличные от DOC, такие как DOCX, в принципе, позволяют сохранять ячейки без ширины в фиксированном формате таблицы.

Разрешить Интервал Между Ячейками

Вы можете задать любое дополнительное расстояние между ячейками таблицы, аналогичное параметру “Расстояние между ячейками” в Microsoft Word. Это можно сделать с помощью свойства AllowCellSpacing.

Пример того, как эти параметры применяются к реальной таблице в документе, можно увидеть на рисунке ниже.

В следующем примере кода показано, как установить интервал между ячейками:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document(getMyDir() + "Tables.docx");

Table table = (Table) doc.getChild(NodeType.TABLE, 0, true);
table.setAllowCellSpacing(true);
table.setCellSpacing(2.0);
        
doc.save(getArtifactsDir() + "WorkingWithTableStylesAndFormatting.AllowCellSpacing.docx");

Примените границы и растушевку

Границы и штриховка могут быть применены либо ко всей таблице с помощью Table.SetBorder, Table.SetBorders и Table.SetShading, либо только к определенным ячейкам с помощью CellFormat.Borders и CellFormat.Shading. Кроме того, границы строк можно задать с помощью RowFormat.Borders, однако штриховка не может быть применена таким образом.

На рисунках ниже показаны настройки границ и теней в Microsoft Word и соответствующие им свойства в Aspose.Words.

В следующем примере кода показано, как отформатировать таблицу и ячейку с различными границами и оттенками:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Table table = builder.startTable();
builder.insertCell();

// Set the borders for the entire table.
table.setBorders(LineStyle.SINGLE, 2.0, Color.BLACK);
        
// Set the cell shading for this cell.
builder.getCellFormat().getShading().setBackgroundPatternColor(Color.RED);
builder.writeln("Cell #1");

builder.insertCell();
        
// Specify a different cell shading for the second cell.
builder.getCellFormat().getShading().setBackgroundPatternColor(Color.GREEN);
builder.writeln("Cell #2");

builder.endRow();

// Clear the cell formatting from previous operations.
builder.getCellFormat().clearFormatting();

builder.insertCell();

// Create larger borders for the first cell of this row. This will be different
// compared to the borders set for the table.
builder.getCellFormat().getBorders().getLeft().setLineWidth(4.0);
builder.getCellFormat().getBorders().getRight().setLineWidth(4.0);
builder.getCellFormat().getBorders().getTop().setLineWidth(4.0);
builder.getCellFormat().getBorders().getBottom().setLineWidth(4.0);
builder.writeln("Cell #3");

builder.insertCell();
builder.getCellFormat().clearFormatting();
builder.writeln("Cell #4");
        
doc.save(getArtifactsDir() + "WorkingWithTableStylesAndFormatting.FormatTableAndCellWithDifferentBorders.docx");