Report

摘要

Report 对象将引用 ArcGIS Pro 工程 (.aprx) 文件中的报表。 它用于对常见属性和方法进行访问。

说明

ArcGIS Pro 工程可包含多个报表。 可以使用 createReport 方法创建报表,并使用 ArcGISProject 对象上的 listReports 方法访问报表。 listReports 方法返回 Report 对象的 Python 列表。 有必要确保每个报表均具有唯一名称,因为这样可以通过其 name 轻松引用特定报表。 所有报表都具有可以查看或修改的 metadata 属性。 可以使用 pageInfo 属性访问页面信息,包括页面单位、宽度、高度和边距。

使用 listReports 方法返回的 Report 对象还表示第一个 ReportSection。 可以使用 setReferenceDataSource 方法修改 referenceDataSource 属性。 可以将 definitionQuery 应用于第一个报表部分以过滤导出为 PDF 的行。 可使用 listSections 方法访问所有报表部分以及报表中的 ReportLayoutSection 对象。

可以使用 exportToPDF 方法将报表导出为 .pdf 文档。

属性

属性说明数据类型
definitionQuery
(可读写)

第一个 ReportSection 的定义查询。 使用此项可过滤导出至 PDF 的记录。

String
metadata
(可读写)

获取或设置报表的元数据类信息。 请注意,设置元数据取决于 isReadOnly 属性值。

Metadata
name
(可读写)

报表的名称。 有必要确保工程中的所有报表都具有唯一的名称,因为这样便可通过这些唯一名称轻松对其进行引用。

String
pageInfo
(只读)

报表页面宽度、高度、单位和边距。

字段的键定义如下:

  • height报表的高度(以页面单位计)。
  • width报表的宽度(以页面单位计)。
  • units报表的页面单位关键字。 受支持的值为 inchpointcentimetermillimeter
  • margins报表的边距关键字。 受支持的边距值为 NORMALMODERATEWIDENARROW
Dictionary
referenceDataSource
(只读)

第一个 ReportSection 的参考数据源连接信息。 字段的键定义如下:

  • dataset数据集名称。
  • workspace_factory工作空间工厂类型。
  • connection_info用于表示工作空间路径的字符串
Dictionary

方法概述

方法说明
exportToPDF (out_pdf, {page_range_type}, {page_range}, {starting_page_number}, {total_page_number}, {resolution}, {image_quality}, {compress_vector_graphics}, {image_compression}, {embed_fonts}, {jpeg_compression_quality})

用于将报表导出为便携式文档格式 (PDF) 文件。

getDefinition (cim_version)

获取报表的 CIM 定义。

listSections ({wildcard})

返回报表中 ReportSectionReportLayoutSection 对象的 Python 列表。

openView ()

在应用程序中打开并激活一个新的报表视图窗格。

setDefinition (definition_object)

设置报表的 CIM 定义。

setReferenceDataSource (data_source)

设置报表的参考数据源。

updatePageInfo (pageInfo)

更新报表页面信息。

方法

exportToPDF (out_pdf, {page_range_type}, {page_range}, {starting_page_number}, {total_page_number}, {resolution}, {image_quality}, {compress_vector_graphics}, {image_compression}, {embed_fonts}, {jpeg_compression_quality})
参数说明数据类型
out_pdf

用于表示输出导出文件的路径和文件名的字符串。

String
page_range_type

用于定义要导出的页面范围类型的字符串。默认值为 ALL。

  • ALL导出报表的所有页面。
  • LAST导出报表的最后一页。
  • EVEN导出报表的偶数页面。
  • ODD导出报表的奇数页面。
  • RANGE导出 page_range 参数中列出的页面。

(默认值为 ALL)

String
page_range

如果使用 page_range_type 参数中的 RANGE 选项,用于标识要导出的页面的字符串(例如:1、3、5-12)。如果使用任何其他 page_range_type 值,则将忽略 page_range 值。

String
starting_page_number

将偏移应用于页面编号以在报表开始处添加附加页面。默认偏移为 1。

(默认值为 1)

Integer
total_page_number

要标注的总页面数,例如,如果报表显示第 X 页,共 Y 页。这在将多个报表合并为一个报表时将非常有用。默认值为 -1,表示没有覆盖。

(默认值为 None)

Integer
resolution

用于定义导出文件分辨率的整数值,单位为每英寸点数 (dpi)。

(默认值为 96)

Integer
image_quality

定义输出图像质量的字符串。

  • BEST输出图像质量的重采样比为 1
  • BETTER输出图像质量的重采样比为 2
  • NORMAL输出图像质量的重采样比为 3
  • FASTER输出图像质量的重采样比为 4
  • FASTEST输出图像质量的重采样比为 5

(默认值为 BEST)

String
compress_vector_graphics

用于控制输出文件的矢量和文本部分压缩的布尔值。图像压缩单独定义。

(默认值为 True)

Boolean
image_compression

用于定义在输出文件中压缩图像或栅格数据时使用的压缩方案的字符串。

  • ADAPTIVE自动为页面中的每个图像选择最佳压缩类型。JPEG 适用于包含许多唯一颜色的较大图像。DEFLATE 适用于所有其它图像。
  • JPEG有损数据压缩。
  • DEFLATE无损数据压缩
  • LZWLempel-Ziv-Welch,无损数据压缩
  • NONE不应用压缩。
  • RLE游程编码压缩

(默认值为 ADAPTIVE)

String
embed_fonts

用于控制导出文件中的字体嵌入的布尔值。当在未安装所需字体的计算机上查看文档时,可通过字体嵌入正确显示文本和字符标记。

(默认值为 True)

Boolean
jpeg_compression_quality

image_compression 设置为 ADAPTIVE 或 JPEG 时,用于控制压缩质量值的数字。有效范围为 1 到 100。jpeg_compression_quality 为 100 时可提供最佳图像质量,但会创建较大的导出文件。推荐范围为 70 到 90。

(默认值为 80)

Integer

PDF 文件可在整个平台上实现一致的查看和打印效果。它们通常用于在 Web 上分发文档,并且此格式现在为内容传送的标准交换格式。PDF 文件在许多图形应用程序中均可编辑,并且它还保留了地图图层的注记、标注和属性数据。PDF 导出支持字体嵌入,即使在用户尚未安装 Esri 字体时,也可以正确显示符号系统。

getDefinition (cim_version)
参数说明数据类型
cim_version

A string that represents the major version of the CIM.

String

ArcGIS Pro 2.4 中引入了对其他对象属性的 CIM 级别访问权限。 在 ArcGIS Pro 3.1 中引入了对报表的 CIM 级别访问权限。 要返回对象的 CIM 定义,必须指定 cim_version。 Esri 遵循语义版本规范。 这意味着在主要版本(例如 3.0)中允许突破性 API 更改。 如果可能在新版本中引入突破性更改,Python 脚本作者可通过该值控制脚本运行期间使用的 CIM 版本。 如果您正在为 ArcGIS Pro 2.x 创作脚本,可将 cim_version 指定为 'V2'。 如果您正在为 ArcGIS Pro 3.x 创作脚本,可将 cim_version 指定为 'V3'。 使用 cim_version 'V2' 创作的脚本可继续在 ArcGIS Pro 3.x 中使用。

有关使用 CIM 和示例的详细信息,请参阅 Python CIM 访问

listSections ({wildcard})
参数说明数据类型
wildcard

A wildcard is based on the section name and is not case sensitive. A combination of asterisks (*) and characters can be used to help limit the resulting list.

(默认值为 None)

String
返回值
数据类型说明
List

报表中 ReportSectionReportLayoutSection 对象的 Python 列表。

返回报表中 ReportSectionReportLayoutSection 对象的 Python 列表。

openView ()

如果报表视图尚未打开,或者应用程序中的另一个视图处于活动状态,则此方法将非常有用。 该方法将创建一个缩放至其全图范围的报表视图并将其激活。 在打开新视图之前,要关闭其他现有视图,请使用 ArcGISProject closeViews 方法。

注:

此方法旨在使用脚本工具、Notebook 或 Python 窗口在应用程序中运行。 如果在应用程序之外运行该方法,则其将无效。

setDefinition (definition_object)
参数说明数据类型
definition_object

A modified CIM definition object originally retrieved using getDefinition.

Object

有关使用 CIM 和示例的详细信息,请参阅 Python CIM 访问

setReferenceDataSource (data_source)
参数说明数据类型
data_source

支持报表的数据参考。此参数可以为 Layer 对象、Table 对象或表示外部数据源路径的字符串。

(默认值为 None)

Object

setReferenceDataSource 方法可以使用 Layer 对象、Table 对象或表示外部数据源路径的字符串来设置报表参考的数据源。

updatePageInfo (pageInfo)
参数说明数据类型
pageInfo

The keys for the dictionary are defined as follows:

  • heightThe report's height in page units.
  • widthThe report's width in page units.
  • unitsThe report's page unit keyword. The supported values are inch, point, centimeter, and millimeter.
  • marginsThe report's margins keyword. The supported margin values are NORMAL, MODERATE, WIDE, and NARROW.
Dictionary

页面 widthheight 值基于字典中指定 units 内容。 如果更改单位,您可能也想更改相应的 widthheight 值。

代码示例

报表示例 1

以下脚本用于使用页面范围将报表导出为 PDF:

aprx = arcpy.mp.ArcGISProject(r"C:\DemoData\USA_States.aprx")
report = aprx.listReports("Cities Report")[0] # Find report by name
report.exportToPDF(r"C:\DemoData\CitiesReport.pdf", page_range="2-10")
报表示例 2

以下脚本用于更改报表的元数据:

aprx = arcpy.mp.ArcGISProject(r"C:\DemoData\USA_States.aprx")
report = aprx.listReports("States Report")[1] # Find second report by name
md = report.metadata # Get report metadata
md.title = "Modified States Report"
md.save()
报表示例 3

以下脚本用于设置报表中第一个报表部分的参考数据源:

aprx = arcpy.mp.ArcGISProject(r"C:\DemoData\USA_States.aprx")
report = aprx.listReports("Counties Report")[0] # Find report by name, this also returns the first report section
report.setReferenceDataSource(r"C:\DemoData\USA_States.gdb\Counties")
print(report.referenceDataSource)
#{'dataset':'counties', 'workspace_factory':'File Geodatabase',
# 'connection_info':{'database':'C:\\DemoData\\USA_States.gdb'}}
报表示例 4

以下脚本用于修改报表中第一个报表部分的定义查询:

aprx = arcpy.mp.ArcGISProject(r"C:\DemoData\USA_States.aprx")
report = aprx.listReports()[2] # Find the third report in the project
print(report.name)
# State Population Report
report.definitionQuery = "STATE_NAME = 'California'"
print(report.definitionQuery)
# STATE_NAME = 'California'
报表示例 5

以下脚本使用 listSections 获取所有报表和报表布局部分对象:

aprx = arcpy.mp.ArcGISProject('current') # Run this from the Python window in Pro
report = aprx.listReports("Complete Report")[0] # Find report by name
sections = report.listSections() # Get all report and report layout sections in a report
for s in sections:
	print(f"Section Name: {s.name} Section Type: {s.type}")
# Section Name: Cover Page Section Type: REPORT_LAYOUT_SECTION
# Section Name: Cities Section Type: REPORT_SECTION
# Section Name: States Section Type: REPORT_SECTION
报表示例 6

以下脚本更改文本元素的报表定义:

aprx = arcpy.mp.ArcGISProject(r'C:\projects\WaterSupply.aprx')
report = aprx.listReports('Suppliers')[0] # Find the report by name
df = report.getDefinition('V3') # Get the current CIM definition of the report

report_section = df.elements[0] # Find the first report section in the CIM
report_header = report_section.elements[4] # Find the report header subsection
title_text = report_header.elements[3] # Find the title text element

symbol = title_text.graphic.symbol.symbol # Get the text symbol
symbol.fontFamilyName = "Arial" # Change the font 

report.setDefinition(df) # Set the new CIM definition
报表示例 7

以下脚本创建一个报表并打开一个新视图:

aprx = arcpy.mp.ArcGISProject('current') # This must be run in the application
map = aprx.listMaps('TaxLots')[0] # Find the map by name

# Define report properties
ds = map.listTables('Owners')[0] # Find the data source table by name
pi = {'width': 297, 'height': 420, 'units': 'MILLIMETER', 'margins': 'WIDE'} # Define page info
f = [{'fieldName': 'Name', 'sortInfo': 'DESC', 'groupField': False},
        {'fieldName': 'Address', 'sortInfo': 'ASC', 'groupField': False},
        {'fieldName': 'Status', 'sortInfo': 'None', 'groupField': False}] # Define fields
s = [] # Pass no statistics

report = aprx.createReport(
            page_info = pi,
            data_source = ds,
            fields = f,
            statistics = s,
            name = 'Owners') # Create the report

report_view = report.openView() # Open a new report view
报表示例 8

以下脚本获取报表的页面信息:

aprx = arcpy.mp.ArcGISProject('current') # This must be run in the application
map = aprx.listMaps('TaxLots')[0] # Find the map by name

# Define report properties
ds = map.listTables('Owners')[0] # Find the data source table by name
pi = {'width': 297, 'height': 420, 'units': 'MILLIMETER', 'margins': 'WIDE'} # Define page info
f = [{'fieldName': 'Name', 'sortInfo': 'DESC', 'groupField': False},
        {'fieldName': 'Address', 'sortInfo': 'ASC', 'groupField': False},
        {'fieldName': 'Status', 'sortInfo': 'None', 'groupField': False}] # Define fields
s = [] # Pass no statistics

report = aprx.createReport(
            page_info = pi,
            data_source = ds,
            fields = f,
            statistics = s,
            name = 'Owners') # Create the report

report_view = report.openView() # Open a new report view