第18章. iText PDF 生成

第18章. iText PDF 生成

18.1. 使用PDF支持

18.1.1. 创建一个文档

18.1.2. 基本的文本元素

18.1.3. 页眉和页脚

18.1.4. 章节

18.1.5. 列表

18.1.6. 表格

18.1.7. 文档常量

18.2. 图表

18.3. 条形码

18.4. 填写表单

18.5. 渲染Swing/AWT组件

18.6. 配置iText

18.7. 进一步的文件

Seam现在包括了一个生成iText文档的组件集。 Seam的iText文档主要是关注对PDF文档生成的支持， 但是Seam 也提供对RTF文档生成的基本支持。

18.1. 使用PDF支持

jboss-seam-pdf.jar提供iText支持。这个JAR包含iText JSF控件， 它被用来构建能渲染PDF的视窗，并且DocumentStore 组件，它提供渲染文档给用户。为在你的应用程序中包含PDF支持，jboss-seam-pdf.jar 连同iText JAR 一起包含在你的WEB-INF/lib 目录中。为使用Seam的iText支持不需要更进一步的配置。

Seam iText模块需要用Facelets作为视窗技术来使用。未来的库版本可能也支持JSP使用。另外，它需要seam-ui 包的使用。

examples/itext项目在实践中包含了一个PDF支持的例子。 它示范了正确的部署包，并且它包含一些例子，示范了目前支持的PDF生成的关键特性。

18.1.1. 创建一个文档

<p:document>

描述 文档是由namespacefacelet XHTML文件利用了在http://jboss.com/products/seam/pdf命名空间中的标签生成。文档应该总是在文档的根结点有document标签。document标签为Seam生成一个文档到文档库和渲染一个HTML重定向到库内容做准备。 属性： type —生成文档的类型。 有效值为PDF、RTF 和 HTML 模式。 Seam默认为PDF生成，并且很多特性只有在生成PDF文档时才能正确工作。 pageSize —生成的页面大小。最常用的值是 LETTER（信函） 和A4。支持的页面大小的全部列表可以在com.lowagie.text.PageSize类中找到。 另外，pageSize可以直接规定宽度和高度。例如，值"612 792"与LETTER的页面大小是一样的。 orientation — 页面方位。有效值是portrait（肖像）和 landscape（风景）。在landscape模式下，页面大小的高度和宽度被倒置。 margins —左边距，右边距，上边距和下边距值。 marginMirroring —指明边距设置应该倒置预备页面。 disposition — 当在一个网页浏览器中生成PDF时，这决定了文档的HTTP Content-Disposition。有效值是inline，它指明文档如果可能应该被显示在浏览器窗口，并且附属指明文档被视为下载状态。默认值是inline。 fileName —作为附属，这个值覆盖下载文件的名字。 元数据属性 标题 主题 关键字 作者 创建者 用法 <p:document xmlns:p="http://jboss.com/products/seam/pdf">    The document goes here.  </p:document>

18.1.2. 基本的文本元素

有用的文档需要包含的不仅仅是文本。然而，标准的UI组件是面向HTML生成的，并不利于生成PDF内容。作为替换，Seam提供了一种特殊的UI组件为生成适当的PDF内容。 如<p:image> 和 <p:paragraph>标签是简单文档的基础。如 <p:font>标签给围绕它们的所有内容都提供了字体信息。

 

<p:paragraph>	描述 为了文本片能以逻辑组方式布局、格式化、样式化，大部分使用的文本被分成段落。 属性 firstLineIndent首行缩进 extraParagraphSpace 额外段落空格 leading 行距 multipliedLeading 多倍行距 spacingBefore —插入在元素前的空格 spacingAfter —插入在元素后的空格 indentationLeft 左缩进 indentationRight 右缩进 keepTogether 保持对齐 用法 <p:paragraph alignment="justify">     This is a simple document.  It isn't very fancy. </p:paragraph>
<p:text>	描述 text 标签允许根据使用了标准的JSF转换机制的应用程序数据产生文本片段。它是非常类似于在渲染HTML文档时使用的 outputText 标签。 属性 value — 被显示的值。这通常是一个值绑定表达式。 用法 <p:paragraph>     The item costs <p:text value="#{product.price}">       <f:convertNumber type="currency" currencySymbol="$"/>     </p:text> </p:paragraph>
<p:html>	描述 html标签渲染HTML内容成PDF。 属性 值 — 显示的文本。 用法 <p:html value="This is HTML with <b>some markup</b>." /> <p:html>     <h1>This is more complex HTML</h1>     <ul>         <li>one</li>         <li>two</li>         <li>three</li>     </ul> </p:html> <p:html> <s:formattedText value="*This* is |Seam Text| as HTML.  It's very^cool^." /> </p:html>
<p:font>	描述 font标签为它内部的所有文本定义要使用的默认字体。 属性 name — 字体名字，例如： COURIER、HELVETICA、 TIMES-ROMAN、SYMBOL 或者 ZAPFDINGBATS。 size — 字体的点大小 style — 字体样式。任意组合：NORMAL、BOLD、 ITALIC、OBLIQUE、 UNDERLINE、LINE-THROUGH encoding —编码字符集 用法 <p:font name="courier" style="bold" size="24">     <p:paragraph>My Title</p:paragraph> </p:font>
<p:newPage>	描述 p:newPage 插入一个新页面。 用法  <p:newPage />
<p:image>	描述 p:image 插入一张图片到文档中。 利用value 属性从类路径或者Web应用程序上下文加载图片。 资源也能由应用程序代码动态生成。imageData 属性可以指定一个值是 java.awt.Image 对象的值绑定表达式。 属性 ·         value —一个资源名或者一个绑定了生成应用程序图象的方法。 ·         rotation — 图象旋转角度。 ·         height — 图象高度。 ·         width — 图象宽度。 ·         alignment— 图片对齐方式。（可能的值见章节见18.1.7.2 “对齐方式值”） ·         alt — 替换图片的文本。 ·         indentationLeft 左缩进 ·         indentationRight 右缩进 ·         spacingBefore —插入在元素前的空格。 ·         spacingAfter —插入在元素后的空格 ·         widthPercentage 宽度百分比 ·         initialRotation 初始旋转 ·         dpi 像素 ·         scalePercent —图象放缩比例因子（百分比）。 可以用一个百分比值表示，或用X方向和Y方向的两个百分比值表示。 ·         wrap 约束 ·         underlying 下划线 用法 <p:image value="/jboss.jpg" /> <p:image value="#{images.chart}" />
<p:anchor>	描述 p:anchor 根据文档定义可点击链接. 它支持下面的属性： 属性 ·         name — 文档内锚点目标的名称。 ·         reference — 链接指向的目标。链接到文档内应该以一个"#"开头的其它点。 例如，"#link1" 指向一个名为link1的一个锚点位置。 链接也可以是指向文档外的一个资源的完整URL路径。 用法 <p:listItem><p:anchor reference="#reason1">Reason 1</p:anchor></p:listItem>  ... <p:paragraph>     <p:anchor name="reason1">It's the quickest way to get "rich"</p:anchor>      ...  </p:paragraph>

18.1.3. 页眉和页脚

<p:header> <p:footer>

描述 p:header 和 p:footer 组件提供了将页眉和页脚文本放在生成文档的每个页面上的能力。除了第一个页面之外。页眉和页脚声明应该显示在文档的顶部。 属性 alignment — 页眉／页脚框部分的对齐方式。 （对齐方式的值见 Section 18.1.7.2, “Alignment Values”） backgroundColor — 页眉／页脚框的背景色。（颜色值见 Section 18.1.7.1, “Color Values”） borderColor — 页眉／页脚框的边框颜色。 个别边颜色可用 borderColorLeft、borderColorRight、borderColorTop 和 borderColorBottom设置。（颜色值见 Section 18.1.7.1, “Color Values”） borderWidth — 边的宽度。 个别边可以利用 borderWidthLeft、borderWidthRight、borderWidthTop 和 borderWidthBottom 来指定。   <p:facet name="header">   <p:font size="12">     <p:footer borderWidthTop="1" borderColorTop="blue"                borderWidthBottom="0" alignment="center">         Why Seam? [<p:pageNumber />]     </p:footer>   </p:font> </f:facet>

<p:pageNumber>

描述 使用 p:pageNumber 标签能够把当前页码放到页眉或者页脚的内部。 页码标签只能用在页眉或者页脚的上下文中，并且只能使用一次。 用法   <p:footer borderWidthTop="1" borderColorTop="blue"            borderWidthBottom="0" alignment="center">     Why Seam? [<p:pageNumber />] </p:footer>

 

18.1.4. 章节

<p:chapter> <p:section>

描述 如果产生的文档追求书/文章的结构，p:chapter 和 p:section标签能被用来提供必要的结构。 节只能用在章内，然而它们能任意深度地嵌套。大部分PDF阅读器在文档的章节间提供容易的导航 属性 alignment—页眉/页脚块节的对齐方式 (对齐值看章节 18.1.7.2, “对齐值”) number — 章号。 每章指派一个章号。 numberDepth — 节编号的深度。所有的节相对于它们围绕的章/节被编号。如果默认深度为3，第3章第1节第4部分应该是为3.1.4。忽略章号，会使用2为深度数。 在这种情况，节数显示为1.4. 用法 <p:document xmlns:p="http://jboss.com/products/seam/pdf"             title="Hello">    <p:chapter number="1">       <p:title><p:paragraph>Hello</p:paragraph></p:title>       <p:paragraph>Hello #{user.name}!</p:paragraph>    </p:chapter>    <p:chapter number="2">       <p:title><p:paragraph>Goodbye</p:paragraph></p:title>       <p:paragraph>Goodbye #{user.name}.</p:paragraph>    </p:chapter> </p:document>

<p:header>

描述 任何章或节可以包含一个p:title。 标题会紧挨着章/节数显示。标题的主体可以包含原始文本或是一个p:paragraph。

18.1.5. 列表

列表结构可以使用p:list 和 p:listItem 标签显示。列表里可以包含任意嵌套的子列表。列表项不能用在列表的外面。下面的文档使用ui:repeat标签显示取自一个Seam组件的值的列表。

 

<p:document xmlns:p="http://jboss.com/products/seam/pdf"

            xmlns:ui="http://java.sun.com/jsf/facelets"

            title="Hello">

   <p:list style="numbered">

      <ui:repeat value="#{documents}" var="doc">

         <p:listItem>#{doc.name}</p:listItem>

      </ui:repeat>

   </p:list>

</p:document>

<p:list>

属性 style —有序/无序列表的样式。 可选项：NUMBERED、LETTERED、 GREEK、ROMAN、 ZAPFDINGBATS、ZAPFDINGBATS_NUMBER。 如果不指定样式，列表项就以项目列表样式。 listSymbol — 针对项目列表，指定列表符号。 indent — 列表的缩进级。 lowerCase —对使用字母样式的列表，指明字母是否应该为小写。 charNumber —对ZAPFDINGBATS样式，指明无序字符的字符编码。 numberType —对ZAPFDINGBATS_NUMBER排序，指明编号样式。 用法 <p:list style="numbered">   <ui:repeat value="#{documents}" var="doc">     <p:listItem>#{doc.name}</p:listItem>   </ui:repeat> </p:list>

<p:listItem>

描述 p:listItem 支持以下属性： 属性 alignment — 页眉／页脚块节的对齐方式。 （对齐值看 章节 16.1.7.2  “对齐值”） alignment — 列表项目的对齐方式。 （可能值看章节 16.1.7.2  “对齐值” ） indentationLeft — 左缩进的数量。 indentationRight — 右缩进的数量。 listSymbol — 覆盖这个列表项目的默认列表符号。 用法 ...

18.1.6. 表格

使用p:table和 p:cell标签可以创建表结构。 不象其他表结构，没有明确的行声明。如果一个表有三列，那么每三个单元格会自动形成一行。页眉和页脚行可以声明，并且在活动的一个表结构横跨多个页面，它们会被重复。

<p:table>

描述 p:table 支持以下属性。 属性 columns — 组成一个表行的列（单元格）的数量。 widths — 每个列的相对宽度。每个列应该有一个值。 例如widths="2 1 1"表示这个表格有3列，第一列的宽度是第二列和第三列的两倍。 headerRows —初始行的数量， 这行被视为页眉或者页脚行，并且如果表格跨多个页面的时候，它应该被重复。 footerRows — 被视为是页脚行的数量。 这个值应该减去 headerRows 值。 如果文档有2行构成页眉行、1行构成页脚行，那么 headerRows 应该设置为3，footerRows 应该设置为1 widthPercentage — 表格占页面宽度的百分比。 horizontalAlignment — 表格的水平对齐方式。 （可能的值，见  Section 18.1.7.2, “对齐值”） skipFirstHeader 跳过第一个页眉 runDirection运行方向 lockedWidth 锁着宽度 splitRows 分离行 spacingBefore — 元素前要插入的空格。 spacingAfter — 元素后要插入的空格。 extendLastRow 扩展最后行 headersInEvent 页眉活动 splitLate 分离最近的 keepTogether 保持一起 用法   <p:table columns="3" headerRows="1">   <p:cell>name</p:cell>   <p:cell>owner</p:cell>   <p:cell>size</p:cell>   <ui:repeat value="#{documents}" var="doc">     <p:cell>#{doc.name}</p:cell>     <p:cell>#{doc.user.name}</p:cell>     <p:cell>#{doc.size}</p:cell>   </ui:repeat> </p:table>

<p:cell>

描述 p:cell 支持下面的属性。 属性 colspan — 通过声明 colspan 值大于1，单元格可以跨多个列。表格没有跨多行的能力。 horizontalAlignment — 单元格的水平对齐方式。 （可能的值，见  Section 18.1.7.2, “对齐值”） verticalAlignment — 单元格的垂直对齐方式。 （可能的值，见  Section 18.1.7.2, “对齐值”） padding —还可以使用： paddingLeft、paddingRight、 paddingTop 和 paddingBottom来指定填充某一边 。 useBorderPadding 使用边填充 leading 前导 multipliedLeading 多个前导 indent 缩进 verticalAlignment 垂直对齐 extraParagraphSpace 额外段落空间 fixedHeight 固定高度 noWrap 不围绕 minimumHeight 最小高度 followingIndent 底部缩进 rightIndent 右缩进 spaceCharRatio 字符间距比 runDirection 运行方向 arabicOptions 阿拉伯语选项 useAscender 使用递增 grayFill 灰色填充 rotation 旋转 用法 <p:cell>...</p:cell>

18.1.7. 文档常量

本节评述了在多数标签上的属性所共享的一些常量

18.1.7.1. 颜色值

Seam文档还不支持全彩色规格。目前，仅支持命名颜色。它们是： white, gray, lightgray, darkgray, black, red, pink（粉红）, yellow, green, magenta（洋红）, cyan（青色） 和 blue。

18.1.7.2. 对齐值

在对齐值使用的地方，Seam PDF 支持下面的水平对齐值： left, right, center, justify 和 justifyall。 垂直对齐值： top, middle, bottom, 和 baseline。

 

18.2. 图表

使用jboss-seam-pdf.jar也提供对图表的支持。图表可以使用在PDF文档中，或者作为一图象使用在HTML页面。图表需要JFreeChart库（jfreechart.jar 和 jcommon.jar）被添加到WEB-INF/lib库目录。目前支持三种类型的图表：pie charts（饼状图表）, bar charts（柱状图表）和 line charts（线状图表）。

 

<p:barchart>

描述 显示一个柱状图表。 属性 borderVisible — 控制是否或边界不在整个图表四周显示。 borderPaint — 边界颜色，如果可见。 borderBackgroundPaint —图表默认的背景色 borderStroke 边界笔触— domainAxisLabel —域坐标轴的文本标签。 domainAxisPaint —域坐标轴标签的颜色。 domainGridlinesVisible—控制是否在图表上显示域坐标上的网格。 domainGridlinePaint—域坐标上网格的颜色。如果可见。 domainGridlineStroke —域坐标轴上网格线的笔触样式。如果可见。 height — 图表的高度。 width — 图表的宽度。 is3D — 一个布尔值，指明图表应该用3D代替2D渲染。 legend —一个布尔值，指明是否或图表不包含一个图例。 legendItemPaint— 在图例中的文本标签的默认颜色。 legendItemBackgoundPaint— 图例的背景色，如果不同于图表背景色。 legendOutlinePaint— 图例四周的边界色。 orientation —绘图方向， vertical（默认）或horizontal之一。 plotBackgroundPaint—绘图背景的颜色。 plotBackgroundAlpha—绘图背景的alpha（透明度）级别。 它应该是0（完全透明）到1（完全不透明）之间的一个数字。 plotForegroundAlpha—绘图的alpha（透明度）级别。 它应该是0（完全透明）到1（完全不透明）之间的一个数字。 plotOutlinePaint— 区域网格的颜色，如果可见。 plotOutlineStroke —区域网格的的笔触样式，如果可见。 rangeAxisLabel — 区域坐标的文本标签。 rangeAxisPaint —区域坐标标签的颜色。 rangeGridlinesVisible— 控制是否或区域坐标的网格不显示在图表上。 rangeGridlinePaint— 区域网格的颜色，如果可见。 rangeGridlineStroke —区域网格的笔触样式，如果可见。 title — 图表标题文本。 titlePaint—图表标题文本的颜色。 titleBackgroundPaint— 图表标题四周的背景色 width — 图表的宽度。 用法   <p:barchart title="Bar Chart" legend="true"             width="500" height="500">     <p:series key="Last Year">         <p:data columnKey="Joe" value="100" />         <p:data columnKey="Bob" value="120" />     </p:series>        <p:series key="This Year">         <p:data columnKey="Joe" value="125" />         <p:data columnKey="Bob" value="115" />     </p:series> </p:barchart>

<p:linechart>

描述 显示一个线状图表。 属性 borderVisible — 控制是否或边界不在整个图表四周显示。 borderPaint — 边界颜色，如果可见。 borderBackgroundPaint —图表默认的背景色 borderStroke 边界笔触— domainAxisLabel —域坐标轴的文本标签。 domainAxisPaint —域坐标轴标签的颜色。 domainGridlinesVisible—控制是否在图表上显示域坐标上的网格。 domainGridlinePaint—域坐标上网格的颜色。如果可见。 domainGridlineStroke —域坐标轴上网格线的笔触样式。如果可见。 height — 图表的高度。 width — 图表的宽度。 is3D — 一个布尔值，指明图表应该用3D代替2D渲染。 legend —一个布尔值，指明是否或图表不包含一个图例。 legendItemPaint— 在图例中的文本标签的默认颜色。 legendItemBackgoundPaint— 图例的背景色，如果不同于图表背景色。 legendOutlinePaint— 图例四周的边界色。 orientation —绘图方向， vertical（默认）或horizontal之一。 plotBackgroundPaint—绘图背景的颜色。 plotBackgroundAlpha—绘图背景的alpha（透明度）级别。 它应该是0（完全透明）到1（完全不透明）之间的一个数字。 plotForegroundAlpha—绘图的alpha（透明度）级别。 它应该是0（完全透明）到1（完全不透明）之间的一个数字。 plotOutlinePaint— 区域网格的颜色，如果可见。 plotOutlineStroke —区域网格的的笔触样式，如果可见。 rangeAxisLabel — 区域坐标的文本标签。 rangeAxisPaint —区域坐标标签的颜色。 rangeGridlinesVisible— 控制是否或区域坐标的网格不显示在图表上。 rangeGridlinePaint— 区域网格的颜色，如果可见。 rangeGridlineStroke —区域网格的笔触样式，如果可见。 title — 图表标题文本。 titlePaint—图表标题文本的颜色。 titleBackgroundPaint— 图表标题四周的背景色 width — 图表的宽度。 用法 <p:linechart title="Line Chart"             width="500" height="500">     <p:series key="Prices">         <p:data columnKey="2003" value="7.36" />         <p:data columnKey="2004" value="11.50" />         <p:data columnKey="2005" value="34.625" />         <p:data columnKey="2006" value="76.30" />         <p:data column