Используйте DocumentBuilder для вставки элементов документа

Символ DocumentBuilder используется для изменения документов. В этой статье объясняется и описывается, как выполнять ряд задач.

Вставка текстовой строки

Просто передайте строку текста, которую вам нужно вставить в документ, в метод DocumentBuilder.write. Форматирование текста определяется свойством Font. Этот объект содержит различные атрибуты шрифта (название шрифта, размер шрифта, цвет и т.д.). Некоторые важные атрибуты шрифта также представлены свойствами DocumentBuilder, позволяющими получить к ним прямой доступ. Это логические свойства Font.getBold, Font.getItalic и Font.getUnderline.

В следующем примере кода форматированный текст вставляется с помощью DocumentBuilder.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Font font = builder.getFont();
font.setSize(16);
font.setColor(Color.blue);
font.setBold(true);
font.setName("Algerian");
font.setUnderline(Underline.DOUBLE);
builder.write("aspose......... aspose_words_java");

Вставка абзаца

DocumentBuilder.writeln также вставляет строку текста в документ, но, кроме того, добавляет разрыв абзаца. Текущее форматирование шрифта также определяется свойством DocumentBuilder.getFont, а текущее форматирование абзаца определяется свойством DocumentBuilder.getParagraphFormat.

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Font font = builder.getFont();
font.setSize(16);
font.setColor(Color.DARK_GRAY);
font.setBold(true);
font.setName("Algerian");
font.setUnderline(2);
ParagraphFormat paragraphFormat = builder.getParagraphFormat();
paragraphFormat.setFirstLineIndent(12);
paragraphFormat.setAlignment(1);
paragraphFormat.setKeepTogether(true);
builder.write("This is a sample Paragraph");
doc.save(dataDir + "InsertParagraph_out.doc");

Вставка таблицы

Базовый алгоритм создания таблицы с использованием DocumentBuilder прост:

  1. Запустите таблицу с помощью DocumentBuilder.startTable.
  2. Вставьте ячейку, используя DocumentBuilder.insertCell. При этом автоматически начнется новая строка. При необходимости используйте свойство DocumentBuilder.getCellFormat, чтобы задать форматирование ячейки.
  3. Вставьте содержимое ячейки, используя методы DocumentBuilder.
  4. Повторяйте шаги 2 и 3, пока строка не будет завершена.
  5. Вызовите DocumentBuilder.endRow, чтобы завершить текущую строку. При необходимости используйте свойство DocumentBuilder.RowFormat, чтобы задать форматирование строки.
  6. Повторяйте шаги 2-5, пока таблица не будет заполнена полностью.
  7. Вызовите DocumentBuilder.endTable, чтобы завершить создание таблицы. Ниже описаны соответствующие методы создания таблицы DocumentBuilder.

Запуск таблицы

Вызов DocumentBuilder.startTable - это первый шаг в построении таблицы. Он также может быть вызван внутри ячейки, в этом случае он запускает вложенную таблицу. Следующий вызываемый метод - DocumentBuilder.insertCell.

Вставка ячейки

После вызова DocumentBuilder.insertCell будет создана новая ячейка, и любое содержимое, добавленное с помощью других методов класса DocumentBuilder, будет добавлено в текущую ячейку. Чтобы создать новую ячейку в той же строке, снова вызовите DocumentBuilder.insertCell. Используйте свойство DocumentBuilder.getCellFormat, чтобы задать форматирование ячейки. Оно возвращает объект getCellFormat, который представляет все форматирование ячейки таблицы.

Завершение строки

Вызовите DocumentBuilder.endRow, чтобы завершить текущую строку. Если вы вызовете DocumentBuilder.insertCell сразу после этого, таблица будет продолжена с новой строки. Используйте свойство DocumentBuilder.RowFormat, чтобы задать форматирование строк. Он возвращает объект RowFormat, который представляет все форматирование для строки таблицы.

Завершение таблицы

Вызовите DocumentBuilder.endTable, чтобы завершить работу с текущей таблицей. Этот метод следует вызывать только один раз после вызова DocumentBuilder.endRow. При вызове DocumentBuilder.endTable курсор перемещается из текущей ячейки в позицию сразу за таблицей. В следующем примере показано, как создать отформатированную таблицу, содержащую 2 строки и 2 столбца.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderBuildTable.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Table table = builder.startTable();
builder.insertCell();
table.autoFit(AutoFitBehavior.FIXED_COLUMN_WIDTHS);
builder.getCellFormat().setVerticalAlignment(CellVerticalAlignment.CENTER);
builder.write("This is Row 1 Cell 1");
builder.insertCell();
builder.write("This is Row 1 Cell 2");
builder.endRow();
builder.getRowFormat().setHeight(100);
builder.getRowFormat().setHeightRule(HeightRule.EXACTLY);
builder.getCellFormat().setOrientation(TextOrientation.UPWARD);
builder.write("This is Row 2 Cell 1");
builder.insertCell();
builder.getCellFormat().setOrientation(TextOrientation.DOWNWARD);
builder.write("This is Row 2 Cell 2");
builder.endRow();
builder.endTable();
doc.save(dataDir + "output.doc");

Вставка разрыва

Если вы хотите явно начать новую строку, абзац, столбец, раздел или страницу, вызовите DocumentBuilder.insertBreak. Передайте этому методу тип разрыва, который вам нужно вставить, который представлен перечислением BreakType. В следующем примере кода показано, как вставлять разрывы страниц в документ.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertBreak.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("This is Page 1");
builder.insertBreak(BreakType.PAGE_BREAK);
builder.write("This is Page 2");
builder.insertBreak(BreakType.PAGE_BREAK);
builder.write("This is Page 3");
doc.save(dataDir + "output.doc");

Вставка изображения

DocumentBuilder содержит несколько дополнений к методу DocumentBuilder.insertImage, который позволяет вставлять встроенное или плавающее изображение. Если изображение представляет собой метафайл EMF или WMF, оно будет вставлено в документ в формате метафайла. Все остальные изображения будут сохранены в формате PNG. Метод DocumentBuilder.insertImage может использовать изображения из разных источников:

  • Из файла или URL путем передачи строкового параметра
  • Из потока путем передачи параметра Stream
  • Из объекта Image путем передачи параметра Image
  • Из массива байтов путем передачи параметра массива байтов
  • И другие

Для каждого из методов DocumentBuilder.insertImage существуют дополнительные перегрузки, которые позволяют вставлять изображение со следующими параметрами:

  • Встроенный или плавающий в определенном положении
  • Процентная шкала или пользовательский размер

Кроме того, метод DocumentBuilder.insertImage возвращает объект Shape, который был только что создан и вставлен, чтобы вы могли дополнительно изменять свойства фигуры.

Вставка встроенного изображения

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertInlineImage.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertImage(dataDir + "test.jpg");
doc.save(dataDir + "output.doc");

Вставка плавающего (абсолютно расположенного) Изображение

В этом примере вставляется плавающее изображение из файла или URL в указанном положении и размере.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertFloatingImage.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertImage(dataDir + "test.jpg",
RelativeHorizontalPosition.MARGIN,
100,
RelativeVerticalPosition.MARGIN,
100,
200,
100,
WrapType.SQUARE);
doc.save(dataDir + "output.doc");

Вставка закладки

Чтобы вставить закладку в документ, вам необходимо выполнить следующие действия:

  1. Вызовите DocumentBuilder.startBookmark, передав ему желаемое название закладки.
  2. Вставьте текст закладки, используя методы DocumentBuilder.
  3. Вызовите DocumentBuilder.endBookmark, передав ему то же имя, которое вы использовали в DocumentBuilder.startBookmark.

Закладки могут перекрываться и охватывать любой диапазон. Чтобы создать действительную закладку, вам нужно вызвать оба параметра DocumentBuilder.startBookmark и DocumentBuilder.endBookmark с одинаковым именем закладки.

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

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertBookmark.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.startBookmark("FineBookMark");
builder.write("This is just a fine bookmark.");
builder.endBookmark("FineBookmark");
doc.save(dataDir + "output.doc");//

Вставка поля

Поля в документах Microsoft Word состоят из кода поля и результата работы с полем. Код поля подобен формуле, а результат работы с полем - это значение, которое выдает формула. Код поля может также содержать переключатели полей, которые являются дополнительными инструкциями для выполнения определенного действия. Вы можете переключаться между отображением кодов полей и результатов в вашем документе в Microsoft Word с помощью сочетания клавиш Alt+F9. Коды полей отображаются в фигурных скобках ( { } ).Используйте DocumentBuilder.insertField для создания полей в документе. Вам необходимо указать тип поля, код поля и значение поля. Если вы не уверены в синтаксисе конкретного кода поля, сначала создайте поле в Microsoft Word и переключитесь на просмотр его кода поля. Следующий пример кода вставляет поле слияния в документ, используя DocumentBuilder.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertField.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.getFont().setLocaleId(1031);
builder.insertField("MERGEFIELD Date1 \\@ \"dddd, d MMMM yyyy\"");
builder.write(" - ");
builder.insertField("MERGEFIELD Date2 \\@ \"dddd, d MMMM yyyy\"");
doc.save(dataDir + "output.doc");

Вставка поля Form

Поля формы - это частный случай полей Word, которые позволяют “взаимодействовать” с пользователем. Поля формы в Microsoft Word включают текстовое поле, Combobox и checkbox. DocumentBuilder предоставляет специальные методы для вставки каждого типа полей формы в документ: DocumentBuilder.insertTextInput, DocumentBuilder.insertCheckBox и DocumentBuilder.insertComboBox. Обратите внимание, что если вы укажете имя для поля формы, то автоматически будет создана закладка с таким же именем.

Вставка текста для ввода

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertTextInputFormField.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Hello", 0);
doc.save(dataDir + "output.doc");

Вставка CheckBox

Вызовите DocumentBuilder.insertCheckBox, чтобы вставить checkbox в документ. В следующем примере кода показано, как вставить поле формы checkbox в документ.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertCheckBoxFormField.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertCheckBox("CheckBox", true, true, 0);
doc.save(dataDir + "output.doc");

Вставка поля со списком

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertComboBoxFormField.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
String[] items = {"One", "Two", "Three"};
builder.insertComboBox("DropDown", items, 0);
doc.save(dataDir + "output.doc");

Вставка языкового стандарта на уровне поля

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
DocumentBuilder builder = new DocumentBuilder();
Field field = builder.insertField(FieldType.FIELD_DATE, true);
field.setLocaleId(1049);
builder.getDocument().save(getArtifactsDir() + "WorkingWithFields.SpecifylocaleAtFieldlevel.docx");

Вставка HTML

Вы можете легко вставить строку HTML, содержащую фрагмент HTML или весь документ HTML, в документ Word. Просто передайте эту строку методу DocumentBuilder.insertHtml. Одной из полезных реализаций метода является сохранение строки HTML в базе данных и вставка ее в документ во время Mail Merge для добавления отформатированного содержимого вместо его создания с использованием различных методов конструктора документов. В следующем примере кода показано, как вставить HTML в документ с помощью DocumentBuilder.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(DocumentBuilderInsertHtml.class);
// Open the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertHtml(
"<P align='right'>Paragraph right</P>" +
"<b>Implicit paragraph left</b>" +
"<div align='center'>Div center</div>" +
"<h1 align='left'>Heading 1 left.</h1>");
doc.save(dataDir + "output.doc");

Вставка гиперссылки

Используйте DocumentBuilder.insertHyperlink, чтобы вставить гиперссылку в документ. Этот метод принимает три параметра: текст ссылки, которая будет отображаться в документе, место назначения ссылки (URL или название закладки внутри документа) и логический параметр, который должен иметь значение true, если URL является именем закладки внутри документа. DocumentBuilder.insertHyperlink вызывает внутренний вызов DocumentBuilder.insertField. Метод всегда добавляет апострофы в начале и конце URL. Обратите внимание, что вам необходимо явно указать форматирование шрифта для текста, отображаемого гиперссылкой, используя свойство Font. Следующий пример кода вставляет гиперссылку в документ, используя DocumentBuilder.

Вставка оглавления

Вы можете вставить поле TOC (оглавление) в документ в текущей позиции, вызвав метод DocumentBuilder.insertTableOfContents. Метод DocumentBuilder.insertTableOfContents вставит в документ только поле TOC. Чтобы создать оглавление и отобразить его в соответствии с номерами страниц, после вставки поля необходимо вызвать метод both Document.UpdateFields. В следующем примере кода показано, как вставить поле оглавления в документ.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
String dataDir = Utils.getDataDir(DocumentBuilderInsertTableOfContents.class);
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");
builder.insertBreak(BreakType.PAGE_BREAK);
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
builder.writeln("Heading 1");
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
builder.writeln("Heading 1.1");
builder.writeln("Heading 1.2");
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
builder.writeln("Heading 2");
builder.writeln("Heading 3");
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
builder.writeln("Heading 3.1");
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_3);
builder.writeln("Heading 3.1.1");
builder.writeln("Heading 3.1.2");
builder.writeln("Heading 3.1.3");
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
builder.writeln("Heading 3.2");
builder.writeln("Heading 3.3");
doc.updateFields();
doc.save(dataDir + "output.doc");

Вставка Ole-объекта

Если вы хотите, чтобы Ole-объект вызывал DocumentBuilder.insertOleObjectAsIcon.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertOleObject("http://www.aspose.com", "htmlfile", true, true, null);
doc.save(getArtifactsDir() + "WorkingWithOleObjectsAndActiveX.InsertOleObject.docx");

Задайте имя и расширение файла при вставке Ole-объекта

OLE пакет - это устаревший и “недокументированный” способ хранения встроенных объектов, если обработчик OLE неизвестен. В ранних версиях Windows, таких как Windows 3.1, 95 и 98, было приложение Packager.exe, которое можно было использовать для встраивания в документ данных любого типа. Теперь это приложение исключено из Windows, но MS Word и другие приложения по-прежнему используют его для встраивания данных, если обработчик OLE отсутствует или неизвестен. OlePackage класс позволяет получить доступ к OLE Package свойствам.В следующем примере кода показано, как задать имя файла, расширение и отображаемое имя для OLE Package.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
byte[] bs = FileUtils.readFileToByteArray(new File(getMyDir() + "Zip file.zip"));
try (ByteArrayInputStream stream = new ByteArrayInputStream(bs))
{
Shape shape = builder.insertOleObject(stream, "Package", true, null);
OlePackage olePackage = shape.getOleFormat().getOlePackage();
olePackage.setFileName("filename.zip");
olePackage.setDisplayName("displayname.zip");
doc.save(getArtifactsDir() + "WorkingWithOleObjectsAndActiveX.InsertOleObjectWithOlePackage.docx");
}

Получить доступ к необработанным данным объекта OLE

Следующий пример кода демонстрирует, как получить необработанные данные объекта OLE с помощью метода OleFormat.GetRawData().

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Shape oleShape = (Shape) doc.getChild(NodeType.SHAPE, 0, true);
byte[] oleRawData = oleShape.getOleFormat().getRawData();

Вставить горизонтальную линейку в документ

В следующем примере кода показано, как вставить форму горизонтальной линейки в документ, используя метод DocumentBuilder.InsertHorizontalRule.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// Initialize document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Insert a horizontal rule shape into the document.");
builder.insertHorizontalRule();
dataDir = dataDir + "DocumentBuilder.InsertHorizontalRule_out.doc";
doc.save(dataDir);

Работа с формами

Вставка встроенных и свободно плавающих фигур

Вы можете вставить в документ встроенную фигуру заданного типа и размера и свободно перемещающуюся фигуру с заданным положением, размером и типом переноса текста, используя метод DocumentBuilder.InsertShape. Метод DocumentBuilder.InsertShape позволяет вставить фигуру DML в модель документа. Документ должен быть сохранен в формате, поддерживающем формы DML, в противном случае такие узлы будут преобразованы в форму VML при сохранении документа. В следующем примере кода показано, как вставить эти типы фигур в документ.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
//Free-floating shape insertion.
Shape shape = builder.insertShape(ShapeType.TEXT_BOX,
RelativeHorizontalPosition.PAGE, 100,
RelativeVerticalPosition.PAGE, 100,
50, 50,
WrapType.NONE);
shape.setRotation(30.0);
builder.writeln();
//Inline shape insertion.
shape = builder.insertShape(ShapeType.TEXT_BOX, 50, 50);
shape.setRotation(30.0);
OoxmlSaveOptions so = new OoxmlSaveOptions(SaveFormat.DOCX);
// "Strict" or "Transitional" compliance allows to save shape as DML.
so.setCompliance(OoxmlCompliance.ISO_29500_2008_TRANSITIONAL);
dataDir = dataDir + "Shape_InsertShapeUsingDocumentBuilder_out.docx";
// Save the document to disk.
doc.save(dataDir, so);

Создайте прямоугольник с отрезанным углом

Вы можете создать прямоугольник с отрезанным углом, используя Aspose.Words. Существуют следующие типы фигур SingleCornerSnipped, TopCornersSnipped, DiagonalCornersSnipped, TopCornersOneRoundedOneSnipped, SingleCornerRounded, TopCornersRounded, и DiagonalCornersRounded. Фигура DML создается с использованием метода DocumentBuilder.InsertShape с использованием этих типов фигур. Эти типы не могут быть использованы для создания фигур VML. Попытка создать фигуру с помощью открытого конструктора класса “Shape” приводит к возникновению исключения “NotSupportedException”. В следующем примере кода показано, как вставлять эти типы фигур в документ.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.insertShape(ShapeType.TOP_CORNERS_SNIPPED, 50, 50);
OoxmlSaveOptions so = new OoxmlSaveOptions(SaveFormat.DOCX);
so.setCompliance(OoxmlCompliance.ISO_29500_2008_TRANSITIONAL);
dataDir = dataDir + "AddCornersSnipped_out.docx";
//Save the document to disk.
doc.save(dataDir, so);

Импортируйте фигуры с математикой XML в виде фигур в DOM

Вы можете использовать свойство LoadOptions.ConvertShapeToOfficeMath для преобразования фигур с уравнением EquationXML в объекты Office Math. Значение этого свойства по умолчанию соответствует MS поведению Word, т.е. фигуры с уравнением XML не преобразуются в объекты Office math.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
LoadOptions lo = new LoadOptions();
lo.setConvertShapeToOfficeMath(true);
// Specify load option to use previous default behaviour i.e. convert math
// shapes to office math ojects on loading stage.
Document doc = new Document(dataDir + "OfficeMath.docx", lo);
// Save the document into DOCX
doc.save(dataDir + "ConvertShapeToOfficeMath_out.docx", SaveFormat.DOCX);