SuperMap iServer Web 打印服务利用布局模板来输出可打印的地图文档。iServer 支持加载 SuperMap iDesktop/iDesktopX 和 Jaspersoft Studio 软件制作的布局模板。其中，SuperMap iDesktop/iDesktopX 生成的布局模板可导出为 ult 文件进行分发使用；由第三方软件 Jaspersoft Studio 生成的模板则可导出为 jrxml 文件进行分发，下载地址为： https://community.jaspersoft.com/project/jaspersoft-studio；。

使用默认布局模板

iServer 产品包中内置了通过 SuperMap iDesktop/iDesktopX 和 Jaspersoft Studio 制作的布局模板，位于【iServer 根目录】/webapps/iserver/templates/webprinting-layouts 目录中，每个布局模板存放在以布局模板名称命名的文件夹中。

SuperMap iDesktop/iDesktopX 默认布局模板

 对于 SuperMap iDesktop/iDesktopX 软件制作的布局模板，SuperMap iServer 中内置了名为 UGCLayoutTemplate 的模板文件，同名文件夹中包含如下内容：

• expected_output：该文件夹中存放模板输出的示例效果图
• UGCLayoutTemplate.ult：SuperMap iDesktop/iDesktopX 中定义的布局模板文件
• requestData.json：请求体示例

Jaspersoft Studio 默认布局模板

 对于 Jaspersoft Studio 软件制作的布局模板，以 A4_landscape（A4 横板）为例，同名文件夹中包含如下文件：

• expected_output：该文件夹中存放模板输出的示例效果图
• config.yaml：布局模板的配置文件
• legend.jrxml：图例的布局模板文件
• A4_landscape.jrxml：A4横板的布局模板文件

此外，布局模板文件夹中还提供了多个 *.json 的请求体示例，在创建打印任务时，输入的请求体可参考这些请求示例。

您还可以通过 layoutTemplates 资源的 GET 请求或直接访问 iSrever 的布局列表资源页面（iserver/services/webprinting/rest/v1/webprinting/layouts）查看所有内置布局模板的信息。在创建打印任务时，请求体中的 layoutOptions 对象中的 templateName 参数指定内置的布局模板文件夹名称即可。

如果 iServer 内置的布局模板无法满足您的使用需求，您可以通过传参方式更改布局元素内容，也可以根据您的使用需求自定义布局模板。

通过传参方式更改布局元素内容

创建打印任务时，您可以在请求体中通过传参方式更新布局元素内容，主要是对请求体中 layoutOptions 对象中的各个参数进行修改，具体请参阅 打印任务列表资源的 POST 请求。支持修改以下布局元素内容：

• 地图标题（title）：支持修改地图的主标题内容。
• 地图副标题（subTitle）：支持修改地图的副标题内容。
• 指北针（northArrowOptions）：指北针是一个图片，支持更换指北针的图片，可传入 Base64 位的图片，也可传入图片的 url 地址。
• 图例（legendOptions）：支持修改图例名称和内容。图例内容支持以下两种修改方式：（优先级：picAsBase64 > picAsUrl > customItems，三者必选其一）

• 传入一个图例的图片，可传入Base64 位的图片，也可以传图例图片。图片中需包含图例名称。
• 传入一个 JSON 字符串，包含一组图例元素的名称和图片，元素的图片可以是一个 url，也可以是一个Base64 位的图片。
• 比例尺（scaleBarOptions）：支持修改比例尺条的样式、段数、单位制，还可以添加比例尺的文本信息，例如：1:100000。
• 地图作者信息（author）：支持修改地图的作者文本内容。
• 地图版权信息（copyright）：支持修改地图的版权文本内容。
• 小地图（littleMapOptions）：输出的地图文档中除了包含一个主地图，还可以添加一个小地图。例如南海区域的小地图，可以通过修改小地图的比例尺、中心点、指定 WebMap 中的图层名称，来渲染小地图。当然，小地图也可以是一个 layers 图层。
• 分幅参数（standardMarginOptions）：设置布局模板中用于打印国家标准分幅地图的属性，包括分幅图框、邻接图表、图幅编号等。当您选择使用分幅参数设置指北针、比例尺、地图标题等布局元素，不建议通过指北针（northArrowOptions）、比例尺（scaleBarOptions）、地图标题（title）等 layoutOptions 参数再行设置。

自定义布局模板

如果通过以上传参方式更改布局元素内容仍然无法满足您的使用需求，您还可以自定义布局模板，如调整布局元素位置、删除或添加布局元素等。

通过 SuperMap iDesktop/iDesktopX 软件自定义布局模板

您可以直接对 iServer 内置的 SuperMap iDesktop/iDesktopX 生成的布局模板进行修改，也可以生成一个新的布局模板。iServer 内置模板中的打印元素对应 SuperMap iDesktop/iDesktopX 软件布局功能中的地图、地图比例尺、指北针、图例和文本对象，请参考 SuperMap iDesktop/iDesktopX 帮助文档进行操作修改。

若您选择生成新的布局模板，请在 iServer 产品包 Web 打印布局文件夹下新建一个与布局模板文件同名的文件夹，并将布局模板（*.ult）导出至该文件夹中，即【iServer根目录】/webapps/iserver/templates/webprinting-layouts/【布局模板文件名】。上述步骤完成后，iServer 将自动检测模板变化并加载，使新的模板生效。

请注意：

1、对于地图标题、副标题、作者信息、版权信息等文本内容，在 SuperMap iDesktop/iDesktopX 中通过文本对象定义，定义时文本内容需要以“$”开头，并与布局信息（layoutOptions）中的参数对应，如“$title”。若您需要指定默认值，则可定义为如“$title:世界地图”。当您需要输入多行文本时，可在模板中预定义文本框并输入本文内容，输入文本时按需键入换行并可对文字设置对齐方式，若不设置则默认居中对齐；您也可以通过传参的方式在请求体中输入多行文本，但需预定义能够覆盖文本元素范围的文本框，请求体中参数写法详见：layoutOptions。

2、对于在 SuperMap iDesktop/iDesktopX 中定义的文字型比例尺，如 "1:1000000"，需要在布局信息（layoutOptions）设置中将 scaleBarVisible 参数设置为 false，并将 scaleText 参数设置为相应的字符串值，如 1:1000000，才可在打印时生效。

3、当您需要在地图中加入图片，如指定的 logo 图片，您需要通过 SuperMap iDesktop/iDesktopX 在模板中添加矩形面对象，并在其中导入指定的 logo 图片。

4、当您制作用于打印国家标准分幅地图的布局模板时，建议模板中只包含地图元素（图例元素可选）。由于分幅参数（standardMarginOptions）中有地图标题、比例尺、指北针等元素的相关设置，并且在分幅打印模式下能够根据国家标准更为专业地生成地图打印结果。因此，若在布局模板中存在其他布局元素，可能导致打印元素重复、打印效果不佳等问题。

通过 Jaspersoft Studio 软件自定义布局模板

您可以直接对 iServer 内置的 Jaspersoft Studio 布局模板进行修改，修改完成后，iServer 将自动检测模板变化并加载使新的模板生效。以 A4_landscape（A4 横板）为例，需要修改以下三个文件：

1. A4_landscape.jrxml 文件：布局模板文件，包含地图标题、指北针、图例、比例尺、地图作者信息、地图版权信息以及小地图等布局元素，可以在 Jaspersoft Studio 软件中进行调整。
2. legend.jrxml 文件：图例的模板文件，可以在 Jaspersoft Studio 软件中对图例进行调整。图例包括两种方式，一种是直接传入图片方式，该方式中图例图片的大小要与 A4_landscape.jrxml 文件中图例大小保持一致；另一种是 key-value形式，即传入图例的元素图片和元素名称，legend.jrxml 文件中定义了图例元素图片的大小，以及图例元素图片+名称所在行的宽度，还有图例元素的列数。
3. config.yaml 文件：布局模板的配置文件，如果新增或删除某个布局元素，配置文件对应部分内容要做同步修改。

具体操作步骤如下：

1. 通过 Jaspersoft Studio 软件自定义布局模板
2. 修改 config.yaml 文件（如果在 Jaspersoft Studio 软件中新增或删除了某个布局元素）

Jaspersoft Studio 软件自定义布局模板

首先简单介绍一下 Jaspersoft Studio 软件中各个主要部分，如下图所示：

1. 布局模板的编辑区域，已添加的布局元素可以通过拖拽的方式调整其位置和大小。提供了 Design（设计视图）、Source（源码视图）和 Preview（预览视图）选项卡，iServer 插入的地图元素不支持预览选项卡。
2. 可插入布局模板中的元素，iServer 内置的布局模板用到的元素包括：Text Field（文本）、Image（图片）、Subreport（子报告，用于添加地图、小地图、图例元素）。
3. 布局模板中每个元素对应的参数、变量等。
4. 所选布局元素的属性窗口，可以设置布局元素的样式、关联参数的表达式等。
5. 预先配置字段的快捷方式。
6. 数据连接（不适用于 iServer 布局模板）。
7. 信息和错误的控制台。

如以上2号窗体所示，iServer 内置布局模板中的元素对应Jaspersoft Studio 软件中的三种元素：Text Field（文本）、Image（图片）、Subreport（子报告，用于添加地图、小地图、图例元素），下面分别介绍如何进行添加或删除。

Text Field（文本）

iServer 内置布局模板中的地图主标题、副标题、作者信息、版权信息都属于Text Field（文本），添加方式一样，具体步骤如下：

1. 添加元素：在2号窗体中选择 Text Field，在1号区域绘制一个文本元素
2. 新建参数：在3号区域右键点击 Parameters，选择 Create Parameter，新建一个参数，在4号区域修改Name（参数名称），Class（类型）选择 java.lang.String。您也可以直接在 Source（源码视图）中添加参数，代码如下：

<parameter name="title" class="java.lang.String"/>

3. 添加的元素与参数通过表达式进行关联：在1号区域点击添加的布局元素，然后在4号区域选择 Text Field，单击 Expression 后面的按钮，在弹出的对话框中，选择左侧的 Parameters，在列出的参数列表中，双击选择刚刚添加的参数，点击 Finish。您也可以直接在 Source（源码视图）中，在添加的元素标签中添加表达式，代码如下：

<textField>

    ......

    <textFieldExpression><![CDATA[$P{subTitle}]]></textFieldExpression>

</textField>

通过以上三步，一个文本元素就添加完成了，你还可以调整文本框的大小、字体、字号等等。

Image（图片）

iServer 内置布局模板中的指北针、比例尺都属于Image（图片），添加方式一样，具体步骤如下：

1. 添加元素：在2号窗体中选择 Image，在1号区域绘制一个图片元素
2. 新建参数：在3号区域右键点击 Parameters，选择 Create Parameter，新建一个参数，在4号区域修改Name（参数名称），Class（类型）选择 java.lang.String。您也可以直接在 Source（源码视图）中添加参数，代码如下：

<parameter name="northArrowGraphic" class="java.lang.String"/>

3. 添加的元素与参数通过表达式进行关联：可以直接在 Source（源码视图）中，在添加的元素标签中添加表达式，代码如下：

<image>

    ......

    <imageExpression><![CDATA[net.sf.jasperreports.renderers.BatikRenderer.getInstance(new java.io.File(new java.net.URI($P{northArrowGraphic})))]]></imageExpression>

</image>

通过以上三步，一个图片元素就添加完成了，你还可以调整图片框的大小、位置等等。

Subreport（子报告）

iServer 内置布局模板中的地图、小地图、图例都需要通过 Subreport（子报告）来添加，添加方式一样，具体步骤如下：

1. 添加元素：在2号窗体中选择 Subreport，在1号区域绘制一个子报告元素
2. 新建参数：在3号区域右键点击 Parameters，选择 Create Parameter，新建一个参数，在4号区域修改Name（参数名称），Class（类型）选择 java.lang.String。您也可以直接在 Source（源码视图）中添加参数，代码如下：

<parameter name="mapSubReport1" class="java.lang.String"/>

3. 添加的元素与参数通过表达式进行关联：可以直接在 Source（源码视图）中，在添加的元素标签中添加表达式，代码如下：

<subreport>

    ......

    <subreportExpression><![CDATA[$P{mapSubReport1}]]></subreportExpression>

</subreport>

通过以上三步，一个子报告元素就添加完成了，你还可以调整子报告的大小、位置等等。

如果要删除以上添加的元素，需要在 1 号区域将元素删除，还需要在3号区域，将对应的参数删除。

修改 config.yaml 文件

通过 Jaspersoft Studio 软件自定义的布局模板，如果新增或删除了某个布局元素，还需在 config.yaml 文件中新增或删除相关内容。以下是A4_landscape（A4 横板）的config.yaml 文件内容和注释：

templates:

  #===========================================================================

  A4 landscape: !template

  #===========================================================================

    reportTemplate: A4_landscape.jrxml     //布局模板名称

    attributes:                                            //属性信息

      map: !map                                         //地图

        maxDpi: 400                                    //地图的最大 dpi

        width: 800                                       //地图框的宽

        height: 410                                      //地图框的高

      littleMap: !map                                  //小地图

        width: 150                                       //小地图框的宽

        height: 200                                      //小地图框的高

        maxDpi: 400                                    //小地图的最大 dpi

      title: !string {}                                     //地图的主标题

      subTitle: !string {}                               //地图的副标题

      copyright: !string {}                            //地图的版权信息

      author: !string {}                                //地图的作者信息

      legendOptions: !legend                                  //图例

        default:

          columnnumber: 3                          //图例元素的列数，默认3列

      northArrowOptions: !northArrow             //指北针

        size: 40                                            //指北针的图框

        createSubReport: false

        default:

          picAsUrl: "file://NorthArrow.svg"    //指北针的图片

          backgroundColor: "rgba(214, 214, 214, 0)"        //指北针的图框背景色，默认透明

      scaleBarOptions: !scalebar                                                 //比例尺条

        width: 240                                                           //比例尺条的宽

        height: 50                                                           //比例尺条的高

        createSubReport: false

        default:

          backgroundColor: "rgba(214, 214, 214, 0)"       //比例尺条的背景色，默认透明

          font: "黑体"                                                      //比例尺文本的字体

          fontSize: 12                                                     //比例尺文本的字体大小

          fontColor: "black"                                           //比例尺文本的字体颜色

          scaleBarVisible: true                                        //是否显示比例尺条，默认值:true，显示比例尺条

          align: "center"                                                 //比例尺的位置

    processors:                                                            //操作

    - !reportBuilder # compile all reports in current directory

      directory: '.'

    - !createMap                                                        //新建地图

      inputMapper:                                                     //地图的输入

        map: map                                                        //地图的类型

      outputMapper:                                                  //地图的输出

        mapSubReport: mapSubReport1                     //对应 Jaspersoft Studio 软件中地图子报告名称

        mapContext: mapContext1

    - !createMap                                                       //新建小地图

      inputMapper:                                                    //小地图的输入

        littleMap: map                                                 //小地图的类型

      outputMapper:                                                 //小地图的输出

        mapSubReport: mapSubReport2                     //对应 Jaspersoft Studio 软件中小地图子报告名称

        mapContext: mapContext2

    - !createScalebar                                                 //新建比例尺

        inputMapper:                                                  //比例尺的输入

            mapContext1: mapContext                        //比例尺指定的地图

    - !createNorthArrow                                          //新建指北针

        inputMapper:                                                 //指北针的输入

            northArrowDef: northArrow                       //指北针的类型

            map: map                                                  //指北针指定的地图

    - !prepareLegend # create a datasource for the report with the 'legend' attribute

        template: legend.jrxml                                    //关联的图例模板名称

您通过 Jaspersoft Studio 软件自定义的布局模板如果新增或删除了某个布局元素，需要在以上 config.yaml 文件中 attributes 和 processors 两部分内容中新增或删除对应的元素内容。

示例1：去掉默认布局模板中的小地图

1. 下载并安装 Jaspersoft Studio 软件。
2. 双击打开布局模板文件（位于【iServer根目录】/webapps/iserver/templates/webprinting-layouts 目录中），以 A3_landscape.jrxml 为例，在 Jaspersoft Studio 软件中打开，将下图中1所示的小地图的两个框删掉，将图中2所示的小地图参数删掉。

3. 将 config.yaml 中小地图部分的代码删掉，如下图所示，红框中的内容去掉：

4. 创建打印任务时，发送的请求体中无需再传 "littleMapOptions" 参数，如下图红框中的内容去掉：

完成以上1、2、3步修改后，重启 iServer，然后将4步不带小地图的请求体发送给iServer Web打印服务后，输出的地图文档就没有小地图了。

示例2：添加地图的四个角标

针对一些实际的项目需求，iServer 默认提供了一个带四个角标的A3横版布局模板（位于【iServer根目录】/webapps/iserver/templates/webprinting-layouts/A3_mapcornermarks 文件夹中），您在创建打印任务时，可以直接使用该模板，效果如下图所示。

当然，您也可以通过以下方式，在已有的默认布局模板中手动添加四个角标。需要注意的是，添加四个角标的功能暂不支持有小地图的布局模板，如果您使用的布局模板里有小地图，需要参考上面的示例1去掉小地图。

1. 下载并安装 Jaspersoft Studio 软件。
2. 双击打开布局模板文件（位于【iServer根目录】/webapps/iserver/templates/webprinting-layouts 目录中），以 A4_landscape.jrxml 为例，在 Jaspersoft Studio 软件中打开
3. 建议添加两个 StaticText 作为四个角标的框
4. 添加一个变量，名字叫：mapCornerMarks，类型为：java.lang.String
5. 四个角标一共需要添加 24 个 textField，每个 textField 的大小建议：宽 15px，高 12px，字体大小建议 6，每个 textField 的Expression 内容和角标实际意义对应如下表所示：

textFieldExpression	角标实际意义
($P{mapCornerMarks}.split(","))[0]	左上经度的度
($P{mapCornerMarks}.split(","))[1]	左上经度的分
($P{mapCornerMarks}.split(","))[2]	左上经度的秒
($P{mapCornerMarks}.split(","))[3]	左上经度的度
($P{mapCornerMarks}.split(","))[4]	左上经度的分
($P{mapCornerMarks}.split(","))[5]	左上经度的秒
($P{mapCornerMarks}.split(","))[6]	左上经度的度
($P{mapCornerMarks}.split(","))[7]	左上经度的分
($P{mapCornerMarks}.split(","))[8]	左上经度的秒
($P{mapCornerMarks}.split(","))[9]	左上经度的度
($P{mapCornerMarks}.split(","))[10]	左上经度的分
($P{mapCornerMarks}.split(","))[11]	左上经度的秒
($P{mapCornerMarks}.split(","))[12]	左上经度的度
($P{mapCornerMarks}.split(","))[13]	左上经度的分
($P{mapCornerMarks}.split(","))[14]	左上经度的秒
($P{mapCornerMarks}.split(","))[15]	左上经度的度
($P{mapCornerMarks}.split(","))[16]	左上经度的分
($P{mapCornerMarks}.split(","))[17]	左上经度的秒
($P{mapCornerMarks}.split(","))[18]	左上经度的度
($P{mapCornerMarks}.split(","))[19]	左上经度的分
($P{mapCornerMarks}.split(","))[20]	左上经度的秒
($P{mapCornerMarks}.split(","))[21]	左上经度的度
($P{mapCornerMarks}.split(","))[22]	左上经度的分
($P{mapCornerMarks}.split(","))[23]	左上经度的秒

6. 在 config.yaml 中添加如下内容，如粗体所示：

      ......

      author: !string {}

      mapCornerMarks: !string

        default: ""

      legendOptions: !legend

      ......

7. 完成以上步骤后，重启 iServer，然后将使用四个角标的布局模板的请求体发送给 iServer 的 Web 打印服务后，输出的地图文档就带四个角标了。