Документы word на java

Время на прочтение
8 мин

Количество просмотров 15K

Для языка Java (как, впрочем, и для любого другого языка программирования) всё еще не придумали более простого и действенного способа генерации документов docx, чем библиотека Apache POI. В конце нулевых появился сей высокоуровнеый API, позволящий говорить с формируемым документом не на языке разметки XML, а с помощью удобных полей и выводов.

Судя по моим Google-запросам на протяжении более чем года сообщество пользователей этой библиотеки продержалось года этак до 2012, в то время как новые версии библиотеки всё еще появляются на главной странице проекта. Не на все вопросы, касающиеся формирования самого примитивного документа, есть ответы в документации или stackoverflow, не говоря уже о текстах на русском языке. Постараемся компенсировать этот недостаток данных для тех, кому это может понадобиться.

Основные классы API

XWPFDocument — целостное представление Word документа. В нём не только содержится xml-код, интерпретируемый редакторами (Word, LibreOffice), но также содержатся и методы для определения метаданных отображения — набора стилей, сносок и т.п. В этой статье поговорим о первом, так как работа с метаданными не так явно задокументирована, к тому же многие редакторы успешно справляются с отображением документа и без подсказок.

Итак, предположим, у вас на руках есть (ненужный) файл docx. Преобразуем его в файл zip (осторожно, обратное преобразование путем переименования zip -> docx может сделать файл недоступным для вашего редактора(!)), в получившемся архиве откроем папку word, а в ней — файл document.xml. Перед нами xml-представление word-файла, которое также можно было бы получить через Apache POI, с меньшими трудностями.

File file = new File("C:/username/document.docx");
FileInputStream fis = new FileInputStream(file.getAbsolutePath());
XWPFDocument document = new XWPFDocument(fis); // Вот и объект описанного нами класса
String documentLine = document.getDocument().toString(); 

Для того, чтобы поближе познакомиться с содержимым документа, придется вооружиться еще двумя классами API: XWPFParagraph и XWPFTable.

XWPFParagraph — как следует из названия, представляет собой параграф документа. Расположен он может быть как внутри XWPFDocument,

document.getParagraphs();
XWPFParagraph lastParagraph = document.createParagraph();

так и внутри таблицы (если точнее — внутри ячейки таблицы, вложенной в ряд таблицы, вложенного непосредственно в таблицу).

document.createTable().createRow().createCell().addParagraph();

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

XWPFTable — класс, олицетворяющий таблицу. Также как и в XWPFParagraph, XWPFTable можно добавлять к самому документу и к ячейке таблицы (создавая, тем самым, таблицу внутри таблицы). Семантика в таком случае чуточку усложняется.

XWPFTable table = document.createTable(); //Здесь всё просто, создаем таблицу в документе и работаем с ней.
XWPFCell cell = table.createRow().createCell();//Добавим к таблице ряд, к ряду - ячейку, и используем её.
XWPFTable innerTable = new XWPFTable(cell.getCTTc().addNewTbl(), cell, 2, 2); // Воспользуемся конструктором для добавления таблицы - возьмем cell и её внутренние свойства, а так же зададим число рядов и колонок вложенной таблицы
cell.insertTable(cell.getTables().size(), innerTable);

XWPFRun — набор данных о выводе текста внутри параграфа. Находится может только внутри параграфа, создается через вызов метода параграфа-родителя:

paragraph.createRun();

Из нескольких «ранов», как я предпочитаю их называть, и состоит целый параграф текста в Word. Каждый «ран» имеет свою настройку шрифта, его цвета и размера, а также стилизации. Через добавление различных «ранов», подчиняющихся разметке параграфа, можно выводить тексты с совершенно разной стилизацией.

Как становится видно из обзора классов, перенос, скажем, css-стиля в документ будет связан с дополнительной сложностью: часть свойств необходимо будет применить к параграфу docx, часть — к объекту класса XWPFRun.

Итак, библиотека легла в External Libraries/jar лежит под рукой, пора творить.

Создадим документ, добавим таблицу 2х2 и параграф.

XWPFDocument document = new XWPFDocument();
XWPFTable table = document.createTable(2, 2);
XWPFParagraph paragraph = document.createParagraph();
fillTable(table);
fillParagraph(paragraph);

Заполним параграф, добавив ран для вывода текста. После перевода строки стилизация параграфа будет потеряна, и в Word новый параграф будет выведен без красной строки.

void fillParagraph(XWPFParagraph paragraph) {
  paragraph.setIndent(20);
  XWPFRun run = paragraph.createRun();
  run.setFontSize(12);
  run.setFontFamily("Times New Roman");
  run.setText("My text");
  run.addBreak();
  run.setText("New line");
}

Теперь займёмся заполнением таблицы. Мы можем обращаться не только к уже созданным элементам, но и вызвать у сформированной таблицы метод для добавления рядов или колонок.

void fillTable(XWPFTable table) {
XWPFRow firstRow = table.getRows().get(0);
XWPFRow secondRow = table.getRows().get(1);
XWPFRow thirdRow = table.createRow();
fillRow(firstRow);
}

Опускаемся глубже, на уровень ряда таблицы. Именно в таком порядке предстаёт разбор таблицы в Apache POI — сначала ряды, потом клетки. Напрямую из таблицы можно получить лишь количество колонок в таблице:

table.getColBandSize();

Итак, ряд.

void fillRow(XWPFRow row) {
   List<XWPFTableCell> cellsList = row.getCells();
   cellsList.forEach(cell -> fillParagraph(cell.createParagraph()));
}

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

Итак, можно легко уловить суть структуры документа в Word: вкладывай одно в другое и предоставляй доступ (в том числе и к созданию новых экземпляров). К сожалению, далеко не всегда есть возможность получить последний элемент во вложенной коллекции. Чаще всего приходится пользоваться такими вот ухищрениями:

XWPFRun lastRunOfParagraph = paragraph.getRuns(paragraph.getRuns().size() - 1);

Хорошо, с содержимым таблицы разобрались. Что если нам нужно явно уточнить ширину таблицы, а не оставлять её для волной интерпретации редактора?

Для некоторых на первый взгляд числовых значений, например, ширины таблицы, в Apache POI существуют целые классы.

CTTblWidth widthRepr = table.getCTTbl().getTblPr().addNewTblW();
widthRepr.setType(STTblWidth.DXA);
widthRepr.setW(BigInteger.valueOf(4000));

С помощью типа укажем, какая именно ширина нам нужна: auto, pct или dxa. В первом случае таблицы займёт всю предоставленную ей ширину, во втором — процент от всей ширины, указанный позже методом setW. В нашем же случае вмешиватеся специальная единица измерения — dxa, равная 1/20 точки.

Классы, подобные CTTblWidth, используются повсеместно: для определения ширины страницы (PgSize), ширины ячейки и др.

Единцы измерения в Apache POI

В хорошем документе всё выверенно и расчерчено идеально, вплоть до самого пикселя. Возможно, в теории можно сделать всё средствами Apache POI и без углубления в тему единиц измерения, но лучше уделить им внимание сразу, чтобы избежать недопониманий в духе «почему это схлопнулось» и «когда переместил картинку в word на один сантиметр».

О поддержке сантиметров и остальной метрической системы тут остается только мечтать. Это резонно (каждый шрифт уникален, у каждого редактора своя специфика), но дико неудобно. Придется прибегнуть ко множеству конвертаций, если вы хотите задавать отступы (ведь именно в сантиметрах мы привыкли видеть их в word) в сантиметрах. Итак, указав тип измерения dxa для некоторой ширины, как описно в параграфе выше, мы получаем в распоряжение некоторое точное значение, но абсолютно не представляем как им воспользоваться. Для перевода в сантиметры на stackoverflow есть формула. Для всего остального существует класс Units. В нем определены как методы для перевода единиц измерения, так и сами соотношения между значениями.

Запись готового документа

Для записи в конечный файл есть удобный метод XWPFDocument — write. На вход принимается поток, в который пойдёт запись.

document.write(new FileOutputStream(new File("/path/to/file.docx")));

Если готовый документ нужно куда-то передать можно подать в качестве аргумента не File-, а ByteArrayOutputStream.

Информация об элементе отображения в формате xml

Имея документ, отображающийся корректно в определенном редакторе, полезно было бы узнать как именно представлен необходимый параграф или другой элемент. Для этого определенны специальные методы, возвращающие объекты классов пакета org.openxmlformats.schemas.wordprocessingml.x2006.main. Из названия (wordprocessingml) видно, что данный набор классов используется только для работы с документами word. Например, для xlsx документов есть пакет spreadsheetml, некоторые классы которого очень и очень похожи на классы wordprocessingml, поэтому конвертация между форматами достаточно затруднена.

paragraph.getCTP();
table.getCTTbl();

Так, пустой параграф будет иметь скромное представление

<xml-fragment/>

Пустая таблица покажет больше интересного.

<xml-fragment xmlns:main="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
  <main:tblPr>
    <main:tblW main:w="0" main:type="auto"/>
    <main:tblBorders>
      <main:top main:val="single"/>
      <main:left main:val="single"/>
      <main:bottom main:val="single"/>
      <main:right main:val="single"/>
      <main:insideH main:val="single"/>
      <main:insideV main:val="single"/>
    </main:tblBorders>
  </main:tblPr>
  <main:tr>
    <main:tc>
      <main:p/>
    </main:tc>
    <main:tc>
      <main:p/>
    </main:tc>
  </main:tr>
  <main:tr>
    <main:tc>
      <main:p/>
    </main:tc>
    <main:tc>
      <main:p/>
    </main:tc>
  </main:tr>
  <main:tr>
    <main:tc>
      <main:p/>
    </main:tc>
    <main:tc>
      <main:p/>
    </main:tc>
  </main:tr>
</xml-fragment>

Что здесь интересного? Свойства tblPr — всевозможные свойства таблицы. Внутри уже описанная ширина таблицы (установлена 0, но свойство «auto» все равно выведет таблицу в приемлимой, автоматической ширине). Также tblBorders — набор информации о границах таблицы. Далее идёт явно выраженное представление внутренностей таблицы. tr — ряд таблицы, внутри вложенны tc. Внутри tc оказался бы набор вложенный параграфов, если бы мы добавили хотя бы один.
Попробуем пополнить параграф информацией и посмотреть что из этого получится.

XWPFParagraph xwpfParagraph = document.getParagraphs().get(0);
        xwpfParagraph.setFirstLineIndent(10);
        XWPFRun run = xwpfParagraph.createRun();
        run.setFontFamily("Times New Roman");
        run.setText("New text");

Получаем:

<xml-fragment xmlns:main="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
  <main:pPr>
    <main:ind main:firstLine="10"/>
  </main:pPr>
  <main:r>
    <main:rPr>
      <main:rFonts main:ascii="Times New Roman" main:hAnsi="Times New Roman" main:cs="Times New Roman" main:eastAsia="Times New Roman"/>
    </main:rPr>
    <main:t>New text</main:t>
  </main:r>
</xml-fragment>

Здесь ситуация ровно такая же: объект с мета-информацией (в него добавлена информация об отступе красной строки, который мы вложили в коде), а так же само содержимое: там размещается список «ранов». В первый и единственный мы добавили текст и информацию о шрифте. Эта информация также разделилась внутри «рана» — информация о шрифте попала в rPr, сам текст — в элемент t.

Вместо вывода

Apache POI предоставляет удобный, и, что не менее важно, бесплатный API для работы с документами. В нем непросто добиться единого отображения во всех редакторах (Office Online и LibreOffice обязательно будут выглядеть иначе), есть множество неудобств с единицами измерения, а так же непонятно где и какие свойства в элементах должны находиться. Тем не менее, работа с этими свойствами подчинена логике, а возможность подглядеть в xml не нарушая эту логику делает разработку гораздо более удобной.

A Word file is supposed to be created without Word with the help of Java application protocol interfaces.

Concepts Involved: Apache POI and Maven

Apache POI Is an API provided by Apache foundation which is a collection of different java libraries. This facility gives the library to read, write, and manipulate different Microsoft files such as Excel sheets, PowerPoint, and Word files. There are two types basically older version including ‘.doc’, ‘.ppt’ while newer versions of files as ‘.docx’, ‘.pptx’. There are two ways to deal with Apache POI as mentioned below:

Binary Distribution	Source Distribution
No compilation is required to generate file.jar files	Files to generated needs to be compiled in order to generate file.jar files
If working with Linux go for the ‘.tar.gz’ version (version 3.5 backward) otherwise simply download the .zip. the file extension for installation to work on Apache POI.	Here format does not matter because file is not compiled so can be altered as per need

Here zip file is taken for consideration and also if the operating system is Windows, zip files should be preferred. It is a simple java project so binary distribution API is used. In the process of creating the document, several paragraphs will be inserted as a sample to display output and will be providing styles to paragraphs such as font color, font name, and font size. 

Now in order to create a Word file without using Microsoft Word, there is a java interface called Spire and if there is a need to create a PDF document without using Adobe Acrobat then it can be done with the use of an interface known as ‘E-Ice blue’. Here ‘Spire.doc’ must have to be imported as per problem statement as all dealing is in word format.

Spire.Doc for Java is a professional Java Word API that enables Java applications to create, convert, manipulate, and print Word documents without using Microsoft Office. It will be imported as a reference for this program as a reference. 

Syntax: For importing libraries in java of Spire

import Spire.Doc.jar ;

Components Of Spire involved are as follows:

Component	Responsibility
XML Word Processor Format (XWPF)	Reading and writing in ‘docx’ extensions files of MS-Word
Horrible Word Processor Format (HWPF)	Reading and writing in ‘doc’ extensions files of MS-Word

Additionally, there is another Java API for PDF format as discussed above ‘E-Ice Blue’ that enables developers to read, write, convert, and print PDF documents in Java applications without using Adobe Acrobat. Similarly, a PowerPoint API allows developers to create, read, edit, convert, and print PowerPoint files within Java applications.

If user is creating shear Maven project, one can easily add the jar dependency by adding the following configurations to the pom.xml.

Now, just like any class Apache POI contains classes and methods to work on. Major components of Apache POI are discussed below to understand the internal working of a file, how it is been generated without Word with help of classes and methods. There are basically two versions of files been present in Word itself.

Older files extensions	Newer file extension (Version 3.5)
doc	docx
xls	xlsx
ppt	pptx

Maven 

These files are accessed using Maven. Maven is a powerful project management tool that is based on POM (project object model). It is used for projects to build, dependency, and documentation. It simplifies the build process like ANT. But it is too much advanced than ANT.
In short terms we can tell maven is a tool that can be used for building and managing any Java-based project. Maven makes the day-to-day work of Java developers easier and generally help with the comprehension of any Java-based project.

Maven does have some specific commands to deal with files. Most frequently used are:

poi + poi + scratchpadpoi    // In order to deal with older Word file versions 
poi + poi-ooxml              // In order to deal with new Word file versions

Implementation: Below program depicts the responsibility of Spire API in creating a Word file:

Output:

package ua.com.prologistic;

import org.apache.poi.xwpf.model.XWPFHeaderFooterPolicy;

import org.apache.poi.xwpf.usermodel.ParagraphAlignment;

import org.apache.poi.xwpf.usermodel.XWPFDocument;

import org.apache.poi.xwpf.usermodel.XWPFParagraph;

import org.apache.poi.xwpf.usermodel.XWPFRun;

import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP;

import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR;

import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTSectPr;

import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTText;

import java.io.FileOutputStream;

public class WordWorker {

    public static void main(String[] args) {

        try {

            // создаем модель docx документа,

            // к которой будем прикручивать наполнение (колонтитулы, текст)

            XWPFDocument docxModel = new XWPFDocument();

            CTSectPr ctSectPr = docxModel.getDocument().getBody().addNewSectPr();

            // получаем экземпляр XWPFHeaderFooterPolicy для работы с колонтитулами

            XWPFHeaderFooterPolicy headerFooterPolicy = new XWPFHeaderFooterPolicy(docxModel, ctSectPr);

            // создаем верхний колонтитул Word файла

            CTP ctpHeaderModel = createHeaderModel(

            «Верхний колонтитул — создано с помощью Apache POI на Java :)»

            );

            // устанавливаем сформированный верхний

            // колонтитул в модель документа Word

            XWPFParagraph headerParagraph = new XWPFParagraph(ctpHeaderModel, docxModel);

            headerFooterPolicy.createHeader(

                    XWPFHeaderFooterPolicy.DEFAULT,

                    new XWPFParagraph[]{headerParagraph}

            );

            // создаем нижний колонтитул docx файла

            CTP ctpFooterModel = createFooterModel(«Просто нижний колонтитул»);

            // устанавливаем сформированый нижний

            // колонтитул в модель документа Word

            XWPFParagraph footerParagraph = new XWPFParagraph(ctpFooterModel, docxModel);

            headerFooterPolicy.createFooter(

                    XWPFHeaderFooterPolicy.DEFAULT,

                    new XWPFParagraph[]{footerParagraph}

            );

            // создаем обычный параграф, который будет расположен слева,

            // будет синим курсивом со шрифтом 25 размера

            XWPFParagraph bodyParagraph = docxModel.createParagraph();

            bodyParagraph.setAlignment(ParagraphAlignment.RIGHT);

            XWPFRun paragraphConfig = bodyParagraph.createRun();

            paragraphConfig.setItalic(true);

            paragraphConfig.setFontSize(25);

            // HEX цвет без решетки #

            paragraphConfig.setColor(«06357a»);

            paragraphConfig.setText(

            «Prologistic.com.ua — новые статьи по Java и Android каждую неделю. Подписывайтесь!»

            );

            // сохраняем модель docx документа в файл

            FileOutputStream outputStream = new FileOutputStream(«F:/Apache POI Word Test.docx»);

            docxModel.write(outputStream);

            outputStream.close();

        } catch (Exception e) {

            e.printStackTrace();

        }

        System.out.println(«Успешно записан в файл»);

    }

    private static CTP createFooterModel(String footerContent) {

        // создаем футер или нижний колонтитул

        CTP ctpFooterModel = CTP.Factory.newInstance();

        CTR ctrFooterModel = ctpFooterModel.addNewR();

        CTText cttFooter = ctrFooterModel.addNewT();

        cttFooter.setStringValue(footerContent);

        return ctpFooterModel;

    }

    private static CTP createHeaderModel(String headerContent) {

        // создаем хедер или верхний колонтитул

        CTP ctpHeaderModel = CTP.Factory.newInstance();

        CTR ctrHeaderModel = ctpHeaderModel.addNewR();

        CTText cttHeader = ctrHeaderModel.addNewT();

        cttHeader.setStringValue(headerContent);

        return ctpHeaderModel;

    }

}

Word documents have been widely used to create reports, quotations, invoices, etc. Generating Word documents automatically could save us lots of time and energy. This article will show you how to create a Word document on Java applications.

Add Spire.Doc.jar as a dependency

First of all, download Free Spire.Doc for Java 2.7.3. Unzip it, and you’ll get the jar file from the ‘lib’ folder. Then, create a Java application in your IDE. Import the jar file in your project as a dependency.

In the following sections, I will introduce how to insert different elements such as text, paragraphs, tables, lists and images, to a Word document.

Create a Word document

Usually, a large part of the content in a Word document is text. Firstly, we need to create a new instance of Document. And then add a section by Document.addSection() method and add a paragraph to the section by Section.addParagraph() method. After that, add text strings in paragraph by Paragraph.appendText(string text) method. We could also set the styles and format by ParagraphStyle. Finally, invoke document.saveToFile() method to save the document.

Output

Create a table in Word

Table sets text into rows and columns, which makes the text easy to edit and check. Spire.Doc for Java offers a method section.addTable() to add tables to the Word document. We can use Table.resetCells(int rowsNum, int columnsNum) method to set row and column numbers.

Output

Create lists in Word

There are two kinds of lists in Word: bulleted lists and numbered lists. Spire.Doc for Java offers Paragraph.getListFormat().applyBulletStyle() method and Paragraph.getListFormat().applyNumberedStyle() method to add the bulleted list and numbered list to the Word document.

Output

Add an image to Word

Images can beautify the document to attract more readers. Insertion of an image to Word documents can easily be done by using paragraph.appendPicture() method.

Output

Besides creating Word documents from scratch, Spire.Doc also supports to operate the existing Word documents, such as saving Word to PDF/image, adding digital signature to Word, etc. We will introduce more Word functions on Java platform in the future. Enjoy your reading!