总览

DocumentBuilder是一个用来操作Document的很强大的类。它提供了一系列的方法，方便你插入文本、段落、列表、表格、图片和其他内容。使用它有点类似于使用java的StringBuilder。

DOM的Node能办到的事，使用DocumentBuilder也一样能办到。而且比使用dom的方式操作document的代码要少。

DocumentBuilder内部维护了一个游标Cursor，它允许你指向任何你想指向的地方。我们通过调用DocumentBuilder.MoveToXXX这个方法来指向。比方说，DocumentBuilder.MoveToDocumentStart，DocumentBuilder.MoveToField。

MoveToXXX之后，你可以通过DocumentBuilder.InsertXXX在那里插入文字，图片，书签，域或者是其他元素。比方说， DocumentBuilder.InsertField, DocumentBuilder.InsertHtml。

插入元素

接下去，我就详细讲下用DocumentBuilder怎么插入各种类型的元素。

插入字符串

要插入一段字符串，我们可以通过使用DocumentBuilder.write。然后文字规格类型，是通过Font类来控制。 

我们来看下实例：

DocumentBuilder builder = new DocumentBuilder();

// Specify font formatting before adding text.
Font font = builder.getFont();
font.setSize(16);
font.setBold(true);
font.setColor(Color.BLUE);
font.setName("Arial");
font.setUnderline(Underline.DASH);

builder.write("Sample text.");

可以看到，Font是通过builder.getFont();获取到的。

插入Paragraph

DocumentBuilder.writeln，看到这个，聪明的你肯定知道，这个是比write多了个换行。对的，不过，这里的换行也被看做是paragraph break，顾名思义，专门用来结束这个paragraph的。

然后调用DocumentBuilder.writeln，和write一样，需要DocumentBuilder.Font，它还可以需要DocumentBuilder.ParagraphFormat，用来设定paragraph的格式。

代码实例：

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
 
// Specify font formatting
Font font = builder.getFont();
font.setSize(16);
font.setBold(true);
font.setColor(Color.BLUE);
font.setName("Arial");
font.setUnderline(Underline.DASH);
 
// Specify paragraph formatting
ParagraphFormat paragraphFormat = builder.getParagraphFormat();
paragraphFormat.setFirstLineIndent(8);
paragraphFormat.setAlignment(ParagraphAlignment.JUSTIFY);
paragraphFormat.setKeepTogether(true);
 
builder.writeln("A whole paragraph.");

插入表格

用DocumentBuilder创建一个表格是一件很简单的事，大体可以分为7步：

1.开始创建，通过DocumentBuilder.StartTable。 

2.通过DocumentBuilder.InsertCell插入一个单元格。如果需要更改格式，使用DocumentBuilder.CellFormat。 

3.在Cell里通过DocumentBuilder插入文本。 

4.重复步骤2和3，插入多格内容。 

5.通过调用DocumentBuilder.EndRow来结束当前一行。如果需要，你可以通过DocumentBuilder.RowFormat来指定一行的格式。 

6.重复步骤2 - 5，插入多行内容。 

7.调用DocumentBuilder.EndTable来结束一个表格编辑。

这里再详细讲解下每个步骤：

StartTable

创建一个表格的第一步就是DocumentBuilder.StartTable。要注意的是，这个也可以在一个单元格里调用，这样就创建了一个内嵌的表格。

InsertCell

通过调用DocumentBuilder.InsertCell在当前行插入一个单元格，在里面，你可以写入内容。然后要继续在当前行添加单元格，继续调用DocumentBuilder.InsertCell。

通过DocumentBuilder.CellFormat来指定单元格的格式。

EndRow

通过调用DocumentBuilder.EndRow来结束当前一行的编辑。如果你接着再调用DocumentBuilder.InsertCell，那就会在新的一行开始创建单元格。

通过DocumentBuilder.RowFormat来指定一行的格式。

EndTable

通过调用DocumentBuilder.EndTable来结束一个表格。要注意的是，在调用这个之前，要先调用DocumentBuilder.EndRow。原因很简单，通过调用endRow，把DocumentBuilder的Cursor游标移出那一行。

我们来看下代码实例：

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
 
Table table = builder.startTable();
 
// Insert a cell
builder.insertCell();
// Use fixed column widths.
table.autoFit(AutoFitBehavior.FIXED_COLUMN_WIDTHS);
 
builder.getCellFormat().setVerticalAlignment(CellVerticalAlignment.CENTER);
builder.write("This is row 1 cell 1");
 
// Insert a cell
builder.insertCell();
builder.write("This is row 1 cell 2");
 
builder.endRow();
 
// Insert a cell
builder.insertCell();
 
// Apply new row formatting
builder.getRowFormat().setHeight(100);
builder.getRowFormat().setHeightRule(HeightRule.EXACTLY);
 
builder.getCellFormat().setOrientation(TextOrientation.UPWARD);
builder.writeln("This is row 2 cell 1");
 
// Insert a cell
builder.insertCell();
builder.getCellFormat().setOrientation(TextOrientation.DOWNWARD);
builder.writeln("This is row 2 cell 2");
 
builder.endRow();
 
builder.endTable();

上述三个代码实例的运行结果，请看图（我把它们写一起了）：

插入break

如果你要明确指明开始新的一行、一个段落、一列、一个Section或者是一页，通过调用DocumentBuilder.InsertBreak。分隔符break有多种类型，通过BreakType枚举类来区分。

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
 
builder.writeln("This is page 1.");
builder.insertBreak(BreakType.PAGE_BREAK);
 
builder.writeln("This is page 2.");
builder.insertBreak(BreakType.PAGE_BREAK);
 
builder.writeln("This is page 3.");

插入图片

我们通过调用DocumentBuilder.InsertImage来插入一张图片，插入的方式有两种：内嵌和悬浮，分别通过InsertImage的两种重载方法。

大部分情况下，我们插入的图片会以png形式储存到文档里。

插入图片的来源可以分为以下四种：

1.来自文件。 

2.来自一个输入流。 

3.来自缓存Image。 

4.来自一个byte array。

然后，DocumentBuilder.InsertImage会返回一个Shape类型。你如果需要，可以通过它修改一些属性。

有人或许会问，内嵌图片和悬浮图片的区别是什么？

内嵌图片，顾名思义，就是内部嵌入一个图片。它的特点是，图片插入后，周围环境会相应调整。

悬浮图片，顾名思义，就是悬浮在上面的图片。它的特点是，哪里都能放，大不了覆盖其他内容，也可以设置为不覆盖形式，所以这个需要指定位置和类型。

插入内嵌图片

如下代码显示了如何插入内嵌图片：

    builder.moveToParagraph(1, 0);
 
    Bitmap bitmap = MyApplication.decodeSampleBitmapResource(
            getResources(), R.drawable.a, 200, 300
    );
 
    // inline image
    builder.insertImage(bitmap,100,150);

上述有对图片先进行了压缩：decodeSampleBitmapResource，如果这块不清楚的话，可以查看我先前写的Android Bitmap大量使用不产生OOM之“加载大图片资源优化”

如下图，是内嵌图片：

插入悬浮图片

如下代码显示了如何插入悬浮图片：

    builder.moveToParagraph(1, 0);
 
    Bitmap bitmap = MyApplication.decodeSampleBitmapResource(
            getResources(), R.drawable.a, 200, 300
    );
 
    // floating image
    builder.insertImage(bitmap,
        RelativeHorizontalPosition.MARGIN,
        100,
        RelativeVerticalPosition.MARGIN,
        100,
        100,
        150,
        WrapType.NONE);

这里，WrapType用来指定悬浮类型

悬浮图片，如下图：

插入书签

通过DocumentBuidler插入书签，是一件很轻松的事。我们可以把它的过程分三步：

1.DocumentBuilder.StartBookmark 

2.插入内容 

3.DocumentBuilder.EndBookmark

书签可以覆盖，并且可以跨度很大。要创建一个书签，你需要调用StartBookmark和EndBookmark，并且两者设置的名称一致。

    // 下划线不设置
    font.setUnderline(Underline.NONE);
    // 颜色更改
    font.setColor(Color.GREEN);
    font.setSize(12);
    // inline image
    builder.insertImage(bitmap,100,150);
    // floating image
//                builder.insertImage(bitmap,
//                        RelativeHorizontalPosition.MARGIN,
//                        100,
//                        RelativeVerticalPosition.MARGIN,
//                        100,
//                        100,
//                        150,
//                        WrapType.NONE);
    // bookmark
    builder.startBookmark("firstBookmark");
    builder.writeln("My first bookmark");
    builder.endBookmark("firstBookmark");

因为先前一直没有把下划线给设掉，发现很难看，所以在插入图片开始把它设置掉。这里需要注意的是，设置格式属性要在DocumentBuilder.moveToXXX方法调用之后调用，否则会失效。

下图就是执行的效果：

我们再来看看它的DOM树：

注意到没，图片、bookmarkStart和bookmark内容放在同一个paragraph，而bookmarkEnd放到了另一个paragraph。如果你有细致的看过上一篇，那么应该是知道的，原因就在于bookmark插入的内容是通过writeln。这个会附带插入一个paragraph break，所以就直接结束了一个paragraph，然后另起一个新的paragraph。

如果改成builder.write(“My first bookmark”)，DOM树是这样的：

而且它的显示方式也变了：

产生这种变化的原因其实不难想到，区别就在于一个是writeln，一个是write。前者在字符串结尾马上加上了’\n’，而后者没有。也就是说，前者相当于直接回车了，而后者是Aspose.words给你加的，它在一段的末尾加上了’\n’，自然文字就被拉长了。

插入域

域有两部分组成：field code和field result。field code就像是一个公式，而field result就像是一个值。

要插入一个域，通过调用DocumentBuilder.InsertField。如果你不清楚怎么写field code，你可以通过office word或者WPS插入一个域，然后 Alt+F9查看它的field code。

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField("MERGEFIELD $MyFieldName \\* MERGEFORMAT");

插入form field

form field是一种特殊的域，它可以允许用户与其进行交互。在office里，form field包含文本框、联合框和勾选框。需要注意的是，你指定了form field的名称，就会自动生成相同名称的bookmark。

针对这几种框，DocumentBuilder提供了各自独立的方法：DocumentBuilder.InsertTextInput, DocumentBuilder.InsertCheckBox和DocumentBuilder.InsertComboBox。

插入textinput

如下代码是插入一个文本框的form field示例：

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Hello", 0);

插入checkbox

如下代码是插入一个勾选框的form field示例：

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertCheckBox("CheckBox", true, 0);

插入Combobox

如下代码是插入一个联合框的form field示例：

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
String[] items = {"One", "Two", "Three"};
builder.insertComboBox("DropDown", items, 0);

如下图，是这三个的展示效果：

它的DOM树：

可以看到，的确同时生成了相同名称的bookmark。

插入html

通过DocumentBuilder.InsertHtml，你可以很轻松的插入一段html字符串。

如下代码所示：

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(getMyDir() + "DocumentBuilder.InsertHtml Out.doc");

如下图所示：

插入链接

通过DocumentBuilder.InsertHyperlink插入一个链接。它内部是调用DocumentBuilder.InsertField。

需要注意的是，你必须设置一下font，比方说下划线。

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Please make sure to visit ");
// Specify font formatting for the hyperlink.
builder.getFont().setColor(Color.YELLOW);
builder.getFont().setUnderline(Underline.SINGLE);
// Insert the link.
builder.insertHyperlink("Aspose Website", "http://www.aspose.com", false);
// Revert to default formatting.
builder.getFont().clearFormatting();
builder.write(" for more information.");
doc.save(getMyDir() + "DocumentBuilder.InsertHyperlink Out.doc");

结果如下图：

因为在builder.write(” for more information.”)之前调用了builder.getFont().clearFormatting()，所以font的格式恢复到默认值了。