ExportReport
摘要
使用来自地图文档中图层或单独表格的数据以及在报表图层文件 (.rlf) 中提供的报表模板信息导出格式化的表格报表。
讨论
ExportReport 函数提供了一种机制，用于自动生成最初使用 ArcMap 中提供的报表工具在地图文档 (.mxd) 中创作的报表。ArcMap 中编写的报表布局文件是一个模板，用于存储报表内容和其中项目放置位置的信息。将报表布局文件与地图文档中的数据结合使用才能创建输出报表。源数据还可以具有报表中使用的关联连接和相关表的信息。
注:ExportReport 函数的可用性依赖于 ArcMap 安装。因此，ExportReport 只可在安装了 ArcMap 的计算机上执行。ExportReport 不会使用独立安装的 ArcGIS Engine 或 ArcGIS for Server 运行 。此外，ExportReport 不会用作地理处理服务。
要使 ExportReport 正确执行，地图文档 (.mxd) 或图层文件 (.lyr) 中必须存在源数据，并且数据集字段名称必须与报表布局文件中的字段相匹配。如果不同数据源的数据集字段名称相同，则报表布局文件可以与这些数据源配合使用。如果数据相似但数据源字段名称不同，则可以使用 field_map 参数将报表布局文件字段重新映射到源数据集中不同的字段名。
在 ArcMap 的报表布局文件中编写的多个元素无法直接通过 ExportReport 函数处理。因此可能需要编写一系列特定模板，以针对不同情景生成和导出报表。
ArcMap 用户界面中的报表工具包含名为数据集选项的按钮。这使得作者只能在处理记录的四种方法中选择一种：全部、所选组、可见范围和定义查询。dataset_option 参数也用于相同的目的并使用关键字。关键字为 ALL 或 SELECTED 的 dataset_option 只会处理相应的记录。如果 dataset_option 设置为 DEFINITION_QUERY，则需要为 report_definition_query 参数提供有效的字符串。如果 dataset_option 设置为 EXTENT，则需要为 extent 参数提供有效的范围对象。
与用户界面相似，一次只能使用一个 dataset_option 关键字。例如，在用户界面中，无法同时处理仅位于选定的一组记录和仅位于可见范围中的记录。同样的规则适用于 ExportReport 函数；一次只能设置一个参数。如果设置了多个参数，则它们会彼此覆盖。然而，可以将标准 ArcPy 属性和/或空间查询函数加以组合并与 dataset_option 参数的 SELECTED 值相结合，从而生成所需的最终报表。以下提供了一个示例。
page_range 参数用于只为页面子集生成报表。它可以是一组连续的页 (5-12)，或者是一组不连续的页 (3,7)。在这些情况下，当生成报表且 starting_page_number 设置为 1 时，输出的页码将与您输入的内容相匹配（第 3 页、第 7 页）。此种方式针对的是只需重新输出选定编号的页面并将其插入至现有报表的情景。如果要求输出页码是连续页码（例如第 1 页、第 2 页），则您必须将 starting_page_number 设置为与所需页码相同，并将 page_range 设置为单个页面。这意味着，需要每页执行一次 ExportReport。例如，一次 starting_page_number = 3 且 page_range="3"，下次 starting_page_number = 7 且 page_range="7"。
只有在数据集字段名称在 source_data 和用于构建报表布局文件的字段名称之间有所不同时，才需要 field_map 参数。创建 field_map 时，只有在报表中使用的字段才需要添加到字典。如果从字段映射字典中删除字段，这些字段也会被从报表中删除。映射的字段必须具有相同的数据类型，且 field_map 中的字段名称区分大小写。
可以使用 arcpy.mapping 创建报表以便在报表中放置地图。报表中的图片具有名为源影像的属性。除非源影像值正指向磁盘路径，否则 Arcpy.mapping 无权访问此值；arcpy.mapping 可以通过导出操作更新磁盘上的文件，随后，报表引擎将使用当前可用的影像。在数据驱动页面示例中，可以根据当前范围更改图片，例如，在调用下一页面之前使用 arcpy.mapping 更改图片。以下提供了一个示例。
有关 ArcGIS 中报表过程的详细信息，请参阅以下专题介绍：
语法
| 参数 | 说明 | 数据类型 |
report_source | Object | |
report_layout_file |
A string that represents the path and file name of the report layout file (.rlf). | String |
output_file |
A string that represents the path and file name of the output file. The specified file extension controls the output format. The following extensions/formats are supported: .htm, .html, .pdf, .rtf, .tif, .tiff, .txt, and .xls. | String |
dataset_option |
A keyword that specifies which dataset rows will be processed in the output report. This value will override the Dataset Options value stored in the report layout file which is found in the Report Properties dialog box. If the dataset_option parameter is not set, it will default to the value stored in the report layout file. If the dataset_option is set to DEFINITION_QUERY, then a valid string needs to be provided for the report_definition_query parameter. If the dataset_option is set to EXTENT, then a valid Extent object needs to be provided for the extent parameter. Because the dataset_option keyword controls which additional parameter to use, only one of these parameters can be set at a time, just like in the user interface.
(默认值为 USE_RLF) | String |
report_title |
A string that represents the report's title which appears in the report layout file header section. | String |
starting_page_number |
A number that represents the printed page number for the first page of the output report. This value is useful for offsetting page numbers for reports that get appended to the end of existing documents. (默认值为 1) | Long |
page_range |
A string that identifies the report pages to be exported to file (for example, 1, 3, 5–12). | String |
report_definition_query |
A string that represents a valid definition query that controls which rows will be exported to the output report. This parameter can only be set if the dataset_option parameter is set to DEFINITION_QUERY.This value will overwrite any settings stored in the report layout file. If the report_source layer or table has an existing definition query, then the report_definition_query will be applied to the existing subset of records. | String |
extent |
A geoprocessing Extent object. This parameter can only be set if the dataset_option parameter is set to EXTENT. When an extent object is passed into this parameter, the rows will be based on those features that intersect the extent. | Extent |
field_map |
This parameter allows you to use a report layout file with a data source that has similar data types but different field names. A dictionary of mapped field names is used to remap the fields used in the report layout file with the new fields in the data source. The following shows an example of the field_map dictionary structure: | Dictionary |
代码实例
以下脚本将使用地图文档中图层的所选要素将报表导出到 PDF 文件。由于省略了其他可选参数，因此显式输入 extent 参数名称。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
lyr = arcpy.mapping.ListLayers(mxd, "Accidents", df)[0]
arcpy.mapping.ExportReport(lyr,
r"C:\Project\Project.rlf",
r"C:\Project\Output\ProjectReport.pdf",
"EXTENT",
extent=df.extent)
del mxd
下面的脚本对上述示例进行了扩展，演示如何将空间选择和属性选择加以组合以生成所需报表。由于一次只能使用一个 dataset_option，因此需要进行组合。所得结果将合并到单一选择中，并且 dataset_option 参数使用值 SELECTED。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
lyr = arcpy.mapping.ListLayers(mxd, "Accidents", df)[0]
#The DataFrame extent object is converted into a polygon feature so it can be used with the SelectLayerByLocation function.
dfAsFeature = arcpy.Polygon(arcpy.Array([df.extent.lowerLeft, df.extent.lowerRight, df.extent.upperRight, df.extent.upperLeft]),
df.spatialReference)
arcpy.SelectLayerByLocation_management(lyr, "INTERSECT", dfAsFeature, "", "NEW_SELECTION")
arcpy.SelectLayerByAttribute_management(lyr, "SUBSET_SELECTION", "\"Accidents\" > 3")
arcpy.mapping.ExportReport(lyr,
r"C:\Project\Project.rlf",
r"C:\Project\Output\ProjectReport.pdf",
"SELECTED")
del mxd
下列脚本将现有的报表布局文件与具有不同字段名称的另一数据集结合使用。使用新标题覆盖报表布局文件的标题，并使用 field_map 参数重新映射字段。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
lyr = arcpy.mapping.ListLayers(mxd, "Traffic Lights", df)[0]
arcpy.mapping.ExportReport(lyr,
r"C:\Project\Project.rlf",
r"C:\Project\Output\ProjectReport.pdf",
report_title="Traffic Light Coordinates",
field_map={'Accidents':'LightID','X':'Longitude','Y':'Latitude'})
del mxd
以下脚本演示了在报表中插入地图的方法。将生成多页面报表。每页都具有大图片和报表，其中，大图片显示当前数据框范围，而报表提供此范围内要素的信息。更改各数据框范围之后，将数据框导出到 .emf 文件中并使用 ExportReport 创建单独 PDF。将所有页面合并为一个最终 PDF。
import arcpy, os
path = os.getcwd() #a relative path allowing for easy packaging
#Create PDF and remove if it already exists
pdfPath = path + r"\States_SubRegions.pdf"
if os.path.exists(pdfPath):
os.remove(pdfPath)
pdfDoc = arcpy.mapping.PDFDocumentCreate(pdfPath)
subRegionList = ["East North Central", "East South Central", "Middle Atlantic",
"Mountain", "New England", "Pacific", "South Atlantic",
"West North Central", "West South Central"]
mxd = arcpy.mapping.MapDocument(path + r"\States_SubRegions.mxd")
df = arcpy.mapping.ListDataFrames(mxd)[0]
lyr = arcpy.mapping.ListLayers(mxd, "States")[0]
pageCount = 1
for region in subRegionList:
#Generate image for each sub region
whereClause = "\"SUB_REGION\" = '" + region + "'"
lyr.definitionQuery = whereClause
arcpy.SelectLayerByAttribute_management(lyr, "NEW_SELECTION", whereClause)
df.extent = lyr.getSelectedExtent()
arcpy.SelectLayerByAttribute_management(lyr, "CLEAR_SELECTION")
arcpy.mapping.ExportToEMF(mxd, path + "\RegionalPicture.emf", df) #single file
#Generate report
arcpy.mapping.ExportReport(report_source=lyr,
report_layout_file=path + r"\States_SubRegions.rlf",
output_file=path + r"\temp" + str(pageCount) + ".pdf",
starting_page_number=pageCount)
#Append pages into final output
pdfDoc.appendPages(path + r"\temp" + str(pageCount) + ".pdf")
os.remove(path + r"\temp.pdf")
pageCount = pageCount + 1
pdfDoc.saveAndClose()
del mxd