Используйте DocumentBuilder для вставки элементов документа
DocumentBuilder
используется для изменения документов. В этой статье объясняется и описывается, как выполнять ряд задач:
Вставка текстовой строки
Просто передайте строку текста, которую вам нужно вставить в документ, методу DocumentBuilder.Write
. Форматирование текста определяется свойством Font
. Этот объект содержит различные атрибуты шрифта (название шрифта, размер шрифта, цвет и т.д.). Некоторые важные атрибуты шрифта также представлены свойствами DocumentBuilder, что позволяет получить к ним прямой доступ. Это логические свойства Font.Bold
, Font.Italic
и Font.Underline
.
Обратите внимание, что заданное вами форматирование символов будет применяться ко всему тексту, вставленному начиная с текущей позиции в документе.
Приведенный ниже пример вставляет форматированный текст с помощью DocumentBuilder.
// The path to the documents directory. | |
System::String outputDataDir = GetOutputDataDir_WorkingWithDocument(); | |
// Initialize document. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
// Specify font formatting before adding text. | |
System::SharedPtr<Font> font = builder->get_Font(); | |
font->set_Size(16); | |
font->set_Bold(true); | |
font->set_Color(System::Drawing::Color::get_Blue()); | |
font->set_Name(u"Arial"); | |
font->set_Underline(Underline::Dash); | |
builder->Write(u"Sample text."); | |
System::String outputPath = outputDataDir + u"WriteAndFont.doc"; | |
doc->Save(outputPath); |
Вставка абзаца
DocumentBuilder.Writeln
также вставляет строку текста в документ, но, кроме того, добавляет разрыв абзаца. Текущее форматирование шрифта также определяется свойством DocumentBuilder.Font
, а текущее форматирование абзаца определяется свойством DocumentBuilder.ParagraphFormat
. В приведенном ниже примере показано, как вставить абзац в документ.
// The path to the documents directory. | |
System::String outputDataDir = GetOutputDataDir_WorkingWithDocument(); | |
// Initialize document. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
// Specify font formatting | |
System::SharedPtr<Font> font = builder->get_Font(); | |
font->set_Size(16); | |
font->set_Bold(true); | |
font->set_Color(System::Drawing::Color::get_Blue()); | |
font->set_Name(u"Arial"); | |
font->set_Underline(Underline::Dash); | |
// Specify paragraph formatting | |
System::SharedPtr<ParagraphFormat> paragraphFormat = builder->get_ParagraphFormat(); | |
paragraphFormat->set_FirstLineIndent(8); | |
paragraphFormat->set_Alignment(ParagraphAlignment::Justify); | |
paragraphFormat->set_KeepTogether(true); | |
builder->Writeln(u"A whole paragraph."); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertParagraph.doc"; | |
doc->Save(outputPath); |
Вставка таблицы
Базовый алгоритм создания таблицы с помощью DocumentBuilder прост:
- Запустите таблицу с помощью
DocumentBuilder.StartTable
. - Вставьте ячейку, используя
DocumentBuilder.InsertCell
. При этом автоматически начнется новая строка. При необходимости используйте свойствоDocumentBuilder.CellFormat
, чтобы задать форматирование ячейки. - Вставьте содержимое ячейки, используя методы
DocumentBuilder
. - Повторяйте шаги 2 и 3, пока строка не будет завершена.
- Вызовите
DocumentBuilder.EndRow
, чтобы завершить текущую строку. При необходимости используйте свойствоDocumentBuilder.RowFormat
, чтобы задать форматирование строки. - Повторяйте шаги 2-5, пока таблица не будет заполнена полностью.
- Вызовите
DocumentBuilder.EndTable
, чтобы завершить создание таблицы. Ниже описаны соответствующие методы создания таблиц в DocumentBuilder.
Запуск таблицы
Вызов DocumentBuilder.StartTable
является первым шагом в построении таблицы. Он также может быть вызван внутри ячейки, и в этом случае запускается вложенная таблица. Следующий вызываемый метод - DocumentBuilder.InsertCell
.
Вставка ячейки
После вызова DocumentBuilder->InsertCell
будет создана новая ячейка, и любое содержимое, добавленное с помощью других методов класса DocumentBuilder
, будет добавлено в текущую ячейку. Чтобы создать новую ячейку в той же строке, снова вызовите DocumentBuilder->InsertCell
. Используйте свойство DocumentBuilder.CellFormat
, чтобы задать форматирование ячейки. Оно возвращает объект CellFormat
, который представляет все форматирование ячейки таблицы.
Завершение строки
Вызовите DocumentBuilder.EndRow
, чтобы завершить текущую строку. Если вы вызовете DocumentBuilder->InsertCell
сразу после этого, таблица будет продолжена с новой строки.
Используйте свойство DocumentBuilder.RowFormat
, чтобы указать форматирование строк. Оно возвращает объект RowFormat
, который представляет все форматирование для строки таблицы.
Завершение таблицы
Вызовите DocumentBuilder.EndTable
, чтобы завершить работу с текущей таблицей. Этот метод следует вызывать только один раз после вызова DocumentBuilder->EndRow
. При вызове DocumentBuilder.EndTable
курсор перемещается из текущей ячейки в позицию сразу за таблицей. В следующем примере показано, как создать отформатированную таблицу, содержащую 2 строки и 2 столбца.
// The path to the documents directory. | |
System::String outputDataDir = GetOutputDataDir_WorkingWithDocument(); | |
// Initialize document. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
System::SharedPtr<Table> table = builder->StartTable(); | |
// Insert a cell | |
builder->InsertCell(); | |
// Use fixed column widths. | |
table->AutoFit(AutoFitBehavior::FixedColumnWidths); | |
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center); | |
builder->Write(u"This is row 1 cell 1"); | |
// Insert a cell | |
builder->InsertCell(); | |
builder->Write(u"This is row 1 cell 2"); | |
builder->EndRow(); | |
// Insert a cell | |
builder->InsertCell(); | |
// Apply new row formatting | |
builder->get_RowFormat()->set_Height(100); | |
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly); | |
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward); | |
builder->Writeln(u"This is row 2 cell 1"); | |
// Insert a cell | |
builder->InsertCell(); | |
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward); | |
builder->Writeln(u"This is row 2 cell 2"); | |
builder->EndRow(); | |
builder->EndTable(); | |
System::String outputPath = outputDataDir + u"DocumentBuilderBuildTable.doc"; | |
doc->Save(outputPath); |
Вставка разрыва
Если вы хотите явно начать новую строку, абзац, столбец, раздел или страницу, вызовите DocumentBuilder.InsertBreak
. Передайте этому методу тип разрыва, который вам нужно вставить, который представлен перечислением BreakType
. В приведенном ниже примере показано, как вставлять разрывы страниц в документ.
// The path to the documents directory. | |
System::String outputDataDir = GetOutputDataDir_WorkingWithDocument(); | |
// Initialize document. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->Writeln(u"This is page 1."); | |
builder->InsertBreak(BreakType::PageBreak); | |
builder->Writeln(u"This is page 2."); | |
builder->InsertBreak(BreakType::PageBreak); | |
builder->Writeln(u"This is page 3."); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertBreak.doc"; | |
doc->Save(outputPath); |
Вставка изображения
DocumentBuilder предоставляет несколько дополнений к методу DocumentBuilder->InsertImage
, который позволяет вставлять встроенное или плавающее изображение. Если изображение представляет собой метафайл EMF или WMF, оно будет вставлено в документ в формате метафайла. Все остальные изображения будут сохранены в формате PNG. Метод DocumentBuilder->InsertImage
позволяет использовать изображения из разных источников:
- Из файла или
URL
, передав строковый параметрDocumentBuilder->InsertImage
. - Из потока путем передачи параметра
Stream
DocumentBuilder->InsertImage
. - Из объекта Image путем передачи параметра Image
DocumentBuilder->InsertImage
. - Из массива байтов путем передачи параметра массива байтов
DocumentBuilder.InsertImage
.Для каждого из методовDocumentBuilder->InsertImage
существуют дополнительные перегрузки, которые позволяют вставлять изображение со следующими параметрами: - Встроенный или плавающий в определенном положении, например,
DocumentBuilder->InsertImage
. - Процентный масштаб или пользовательский размер, например,
DocumentBuilder.InsertImage
. Кроме того, методDocumentBuilder->InsertImage
возвращает объектShape
, который был только что создан и вставлен, чтобы вы могли дополнительно изменять свойства фигуры.
Вставка встроенного изображения
Передайте одну строку, представляющую файл, содержащий изображение, в DocumentBuilder->InsertImage
, чтобы вставить изображение в документ в качестве встроенной графики. В приведенном ниже примере показано, как вставить встроенное изображение в положение курсора в документе.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->InsertImage(inputDataDir + u"Watermark.png"); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertImage.InsertInlineImage.doc"; | |
doc->Save(outputPath); |
Вставка плавающего (абсолютно расположенного) Изображение
В этом примере вставляется плавающее изображение из файла или URL
в указанном положении и размере.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->InsertImage(inputDataDir + u"Watermark.png", RelativeHorizontalPosition::Margin, 100, RelativeVerticalPosition::Margin, 100, 200, 100, WrapType::Square); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertImage.InsertFloatingImage.doc"; | |
doc->Save(outputPath); |
Вставка закладки
Чтобы вставить закладку в документ, вам необходимо выполнить следующие действия:
- Вызовите
DocumentBuilder->StartBookmark
, передав ему желаемое название закладки. - Вставьте текст закладки, используя методы DocumentBuilder.
- Вызовите
DocumentBuilder.EndBookmark
, передав ему то же имя, которое вы использовали в DocumentBuilder->StartBookmark. - Закладки могут перекрываться и охватывать любой диапазон. Чтобы создать действительную закладку, вам нужно вызвать как
DocumentBuilder->StartBookmark
, так иDocumentBuilder->EndBookmark
с одинаковым именем закладки.
В приведенном ниже примере показано, как вставить закладку в документ с помощью конструктора документов.
// The path to the documents directory. | |
System::String outputDataDir = GetOutputDataDir_WorkingWithDocument(); | |
// Initialize document. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->StartBookmark(u"FineBookmark"); | |
builder->Writeln(u"This is just a fine bookmark."); | |
builder->EndBookmark(u"FineBookmark"); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertBookmark.doc"; | |
doc->Save(outputPath); |
Вставка поля Form
Поля формы - это частный случай полей Word, которые позволяют “взаимодействовать” с пользователем. Поля формы в Microsoft Word включают текстовое поле, поле со списком и флажок.DocumentBuilder предоставляет специальные методы для вставки каждого типа полей формы в документ: DocumentBuilder.InsertTextInput
, DocumentBuilder->InsertCheckBox
и DocumentBuilder.InsertComboBox
. Обратите внимание, что если вы укажете имя для поля формы, то автоматически будет создана закладка с таким же именем.
Вставка текста для ввода
DocumentBuilder.InsertTextInput
чтобы вставить текстовое поле в документ. В приведенном ниже примере показано, как вставить поле формы ввода текста в документ.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->InsertTextInput(u"TextInput", TextFormFieldType::Regular, u"", u"Hello", 0); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertElements.InsertTextInputFormField.doc"; | |
doc->Save(outputPath); |
Установка флажка
Вызовите DocumentBuilder.InsertCheckBox
, чтобы вставить флажок в документ. В приведенном ниже примере показано, как вставить поле формы с флажком в документ.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->InsertCheckBox(u"CheckBox", true, true, 0); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertElements.InsertCheckBoxFormField.doc"; | |
doc->Save(outputPath); |
Вставка поля со списком
Вызовите DocumentBuilder.InsertComboBox
, чтобы вставить поле со списком в документ. В приведенном ниже примере показано, как вставить поле формы со списком в документ.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
System::ArrayPtr<System::String> items = System::MakeArray<System::String>({u"One", u"Two", u"Three"}); | |
builder->InsertComboBox(u"DropDown", items, 0); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertElements.InsertComboBoxFormField.doc"; | |
doc->Save(outputPath); |
Вставка языкового стандарта на уровне поля
Теперь пользователи могут указывать языковой стандарт на уровне поля и могут лучше контролировать его. С каждым полем в DocumentBuilder можно связать идентификаторы языкового стандарта. Приведенные ниже примеры иллюстрируют, как использовать эту опцию.
System::String outputDataDir = GetOutputDataDir_WorkingWithFields(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(); | |
System::SharedPtr<Field> field = builder->InsertField(FieldType::FieldDate, true); | |
field->set_LocaleId(1049); | |
builder->get_Document()->Save(outputDataDir + u"SpecifylocaleAtFieldlevel.docx"); |
Вставка гиперссылки
Используйте DocumentBuilder.InsertHyperlink
, чтобы вставить гиперссылку в документ. Этот метод принимает три параметра: текст ссылки, которая будет отображаться в документе, адрес назначения ссылки (URL или название закладки внутри документа) и логический параметр, который должен иметь значение true, если URL
является именем закладки внутри документа.DocumentBuilder.InsertHyperlink выполняет внутренний вызов DocumentBuilder.InsertField
.Этот метод всегда добавляет апострофы в начале и конце URL-адреса. Обратите внимание, что вам необходимо явно указать форматирование шрифта для отображаемого текста гиперссылки, используя свойство Font
. Приведенный ниже пример вставляет гиперссылку в документ с помощью DocumentBuilder.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->Write(u"Please make sure to visit "); | |
// Specify font formatting for the hyperlink. | |
builder->get_Font()->set_Color(System::Drawing::Color::get_Blue()); | |
builder->get_Font()->set_Underline(Underline::Single); | |
// Insert the link. | |
builder->InsertHyperlink(u"Aspose Website", u"http://www.aspose.com", false); | |
// Revert to default formatting. | |
builder->get_Font()->ClearFormatting(); | |
builder->Write(u" for more information."); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertElements.InsertHyperlink.doc"; | |
doc->Save(outputPath); |
Вставка Ole-объекта
Если вам нужен Ole-объект, вызовите DocumentBuilder.InsertOleObject
. Передайте этому методу значение ProgId
явно с другими параметрами. В приведенном ниже примере показано, как вставить Ole-объект в документ.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->InsertOleObject(u"http://www.aspose.com", u"htmlfile", true, true, nullptr); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertElements.InsertOleObject.doc"; | |
doc->Save(outputPath); |
Задайте имя и расширение файла при вставке Ole-объекта
OLE-пакет - это устаревший и “недокументированный” способ хранения внедренного объекта, если обработчик OLE неизвестен. В ранних версиях Windows, таких как Windows 3.1, 95 и 98, было Packager.exe приложение, которое можно было использовать для встраивания данных любого типа в документ. Теперь это приложение исключено из Windows, но MS Word и другие приложения по-прежнему используют его для встраивания данных, если обработчик OLE отсутствует или неизвестен. Класс OlePackage позволяет получить доступ к свойствам пакета OLE. В приведенном ниже примере показано, как задать имя файла, расширение и отображаемое имя для OLE-пакета.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
System::ArrayPtr<uint8_t> bs = System::IO::File::ReadAllBytes(inputDataDir + u"input.zip"); | |
System::SharedPtr<System::IO::Stream> stream = System::MakeObject<System::IO::MemoryStream>(bs); | |
System::SharedPtr<Shape> shape = builder->InsertOleObject(stream, u"Package", true, nullptr); | |
System::SharedPtr<OlePackage> olePackage = shape->get_OleFormat()->get_OlePackage(); | |
olePackage->set_FileName(u"filename.zip"); | |
olePackage->set_DisplayName(u"displayname.zip"); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertElements.InsertOleObjectwithOlePackage.doc"; | |
doc->Save(outputPath); |
Вставка HTML-кода
Вы можете легко вставить HTML-строку, содержащую HTML-фрагмент или весь HTML-документ целиком, в документ Word. Просто передайте эту строку методу DocumentBuilder->InsertHtml
. Одной из полезных реализаций метода является сохранение HTML-строки в базе данных и вставка ее в документ во время Mail Merge для добавления отформатированного содержимого вместо его создания с помощью различных методов конструктора документов. В приведенном ниже примере показано, как HTML-строка вставляется в документ с помощью DocumentBuilder.
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->InsertHtml(u"<P align='right'>Paragraph right</P><b>Implicit paragraph left</b><div align='center'>Div center</div><h1 align='left'>Heading 1 left.</h1>"); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertElements.InsertHtml.doc"; | |
doc->Save(outputPath); |
Вставить горизонтальную линейку в документ
В примере low code показано, как вставить форму горизонтальной линейки в документ, используя метод DocumentBuilder->InsertHorizontalRule
.
// Initialize document. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<DocumentBuilder> builder = System::MakeObject<DocumentBuilder>(doc); | |
builder->Writeln(u"Insert a horizontal rule shape into the document."); | |
builder->InsertHorizontalRule(); | |
System::String outputPath = outputDataDir + u"DocumentBuilderInsertHorizontalRule.doc"; | |
doc->Save(outputPath); |