MapSeries—ArcGIS Pro

摘要

提供对 ArcGIS Pro 工程中布局的空间地图系列的访问权限。

说明

必须先在 ArcGIS Pro 工程的布局中创作和启用地图系列，然后才能在 arcpy.mp 中进行引用。

注：

无法使用 arcpy.mp 创建地图系列。

除了为布局中的地图系列提供方法和属性外，MapSeries 类还可用于访问地图系列中的各个页面。例如，您可能遇见以下情况，即需要使用自定义逻辑格式化或基于多个字段构造文本元素的字符串信息。在此情况中，可在启用地图系列的情况下创作布局，arcpy.mp 可在处理每个页面时处理自定义文本元素字符串需求。

可以使用 exportToPDF 方法将地图系列中的页面导出为 PDF。导出地图系列时，将支持与地图系列关联的所有动态元素。例如，文本元素、图例、表格框、图表框等。要创建完整的地图册，可使用 PDFDocument 类将输出 PDF 文件插入其他 PDF 文件（例如，标题页面或报表）。

有时，需要将地图系列导出为 PDF 以外的其他输出格式，例如 PNG。请参阅下面的第二个代码样本，其中展示了如何循环遍历地图系列中的每个页面并导出为 .png 文件。

ArcGIS Pro 支持两种类型的地图系列：空间地图和书签。MapSeries 类仅支持与空间地图系列搭配使用。如果针对布局启用了书签地图系列，mapSeries 属性将返回 NoneType。要模拟书签地图系列的行为，请参阅下面的代码示例 4。

属性

属性	说明	数据类型
currentPageNumber (可读写)	表示已启动地图系列的布局的活动页面或当前页面。注：如果使用字符串定义的字段来设置页码，则可以将 currentPageNumber 设置为字符串，例如 currentPageNumber ='iv'。	Long
enabled (可读写)	表示地图系列的启动状态。提示：在更改地图系列属性之前，应检查已启用是否设置为 True。	Boolean
indexLayer (只读)	返回对启用了地图系列的布局中索引图层的引用。	Layer
mapFrame (只读)	返回对索引图层所在的地图框的引用。	MapFrame
pageCount (只读)	返回已启用地图系列的布局的总页数。这与索引图层中的要素数量相对应。	Long
pageNameField (只读)	返回字段对象，它表示设置地图系列时在索引要素类中使用的字段。	Field
pageRow (只读)	返回提供当前索引要素属性的访问权限的行对象。要返回属性值，请输入一个点，后跟字段名称。例如，value = lyt.mapSeries.pageRow.FIELD_NAME。	Row
selectedIndexFeatures (只读)	返回排序页码的 Python 列表，它们表示启用了地图系列的布局中选定的索引图层要素。	List

方法概述

方法	说明
exportToPDF (out_pdf, {page_range_type}, {page_range_string}, {multiple_files}, {resolution}, {image_quality}, {compress_vector_graphics}, {image_compression}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality}, {clip_to_elements}, {show_selection_symbology}, {output_as_image}, {embed_color_profile}, {pdf_accessibility})	将启用了地图系列的布局的一组指定页面导出为便携式文档格式 (PDF) 文件。
getPageNumberFromName (page_name)	基于页面名称返回“地图系列”页码。
refresh ()	刷新现有地图系列

方法

exportToPDF (out_pdf, {page_range_type}, {page_range_string}, {multiple_files}, {resolution}, {image_quality}, {compress_vector_graphics}, {image_compression}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality}, {clip_to_elements}, {show_selection_symbology}, {output_as_image}, {embed_color_profile}, {pdf_accessibility})

参数	说明	数据类型
out_pdf	A string that represents the path and file name of the output export file.	String
page_range_type	The string value that designates how the pages will be printed. ALL—All pages are exported. CURRENT—The active or current page is exported. RANGE—Only pages listed in the page_range_string parameter are exported. SELECTED—Selected index layer features/pages are exported. (默认值为 ALL)	String
page_range_string	A string that identifies the pages to be exported if the RANGE option in the page_range_type parameter is used (for example, 1, 3, 5-12). If any other page_range_type value is used, the page_range_string value will be ignored.	String
multiple_files	A string that controls how the output PDF file is created. By default, all pages are exported into a single, multipage document. The default is PDF_SINGLE_FILE. PDF_MULTIPLE_FILES_PAGE_NAME—Export each map series page to an individual file and append the page name to the file name. For example, Output.PDF will become Output_LakeErie.PDF PDF_MULTIPLE_FILES_PAGE_NUMBER—Export each map series page to an individual file and append the page number to the file name. For example, Output.PDF will become Output_1.PDF PDF_SINGLE_FILE—Export into a multipage, single file document. (默认值为 PDF_SINGLE_FILE)	String
resolution	An integer that defines the resolution of the export file in dots per inch (dpi). (默认值为 96)	Integer
image_quality	A string that defines output image quality. BEST—An output image quality resample ratio of 1 BETTER—An output image quality resample ratio of 2 NORMAL—An output image quality resample ratio of 3 FASTER—An output image quality resample ratio of 4 FASTEST—An output image quality resample ratio of 5 (默认值为 BEST)	String
compress_vector_graphics	A Boolean that controls the compression of vector and text portions of the output file. Image compression is defined separately. (默认值为 True)	Boolean
image_compression	A string that defines the compression scheme used to compress image or raster data in the output file. ADAPTIVE—Automatically selects the best compression type for each image on the page. JPEG will be used for large images with many unique colors. DEFLATE will be used for all other images. JPEG—A lossy data compression. DEFLATE—A lossless data compression. LZW—Lempel-Ziv-Welch, a lossless data compression. NONE—Compression is not applied. RLE—Run-length encoded compression. (默认值为 ADAPTIVE)	String
embed_fonts	A Boolean that controls the embedding of fonts in an export file. Font embedding allows text and character markers to be displayed correctly when the document is viewed on a computer that does not have the necessary fonts installed. (默认值为 True)	Boolean
layers_attributes	A string that controls the inclusion of PDF layers and PDF object data (attributes) in the export file. LAYERS_ONLY—Export PDF layers only. LAYERS_AND_ATTRIBUTES—Export PDF layers and feature attributes. NONE—No setting is applied. (默认值为 LAYERS_ONLY)	String
georef_info	A Boolean that enables the export of coordinate system information for each map frame into the output PDF file. (默认值为 True)	Boolean
jpeg_compression_quality	A number that controls the compression quality value when image_compression is set to ADAPTIVE or JPEG. The valid range is 1 through 100. A jpeg_compression_quality of 100 provides the best quality images but creates large export files. The recommended range is 70 through 90. (默认值为 80)	Integer
clip_to_elements	If set to True, the layout is clipped to the smallest bounding box that includes all layout elements. (默认值为 False)	Boolean
show_selection_symbology	A Boolean that controls whether the selection symbology should be displayed in the output. (默认值为 False)	Boolean
output_as_image	If set to True, vector content can be saved as an image. Selecting this option for maps or layouts that contain vector layers with a high density of vertices can reduce the output file size. When exporting to PDF and this option is set to True, you cannot view PDF layers in the output. (默认值为 False)	Boolean
embed_color_profile	If set to True, color profile information is embedded in the image's metadata. (默认值为 True)	Boolean
pdf_accessibility	Output a tagged PDF file where text can be read by screen readers or other assistive technology. A tagged PDF file can include alt text—a text description of a graphic element that a screen reader uses to describe the element—for map frames, pictures, and chart frames. Alt text is added in the Element Pane for each element. (默认值为 False)	Boolean

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

getPageNumberFromName (page_name)

参数	说明	数据类型
page_name	与用于设置“地图系列”的 Name 字段对应的索引图层中的页码。	String

许多“地图系列”属性和方法都使用页码值，而不使用用于创建索引图层的页面文字名称。getPageNumberFromName 方法提供了一种用于获取给定页面名称的页码的机制。

ms = layout.mapSeries
pageNumber = ms.getPageNumberFromName("HarborView")
ms.currentPageNumber = pageNumber

refresh ()

如果发生以下任何一种情况，请使用 refresh 方法：

在索引图层中添加了或删除了要素。
对索引字段值进行了更新。
数据框范围因缩放、平移或更改地图比例而发生了变化。

地图系列将保留原始设置，直到执行了 refresh 方法，或工程被保存并重新打开。

代码示例

MapSeries 示例 1

下面的脚本将检查是否存在地图系列，然后将其中的两个页面导出为 PDF。

import arcpy
import os
import sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(relpath + "\\MapSeries\\US_States.aprx")
l = p.listLayouts()[0]
if not l.mapSeries is None:
    ms = l.mapSeries
    if ms.enabled:
        ms.currentPageNumber = ms.getPageNumberFromName("Rhode Island") 
        ms.exportToPDF(relpath + "\\Output\\Ex1_RI.pdf", "CURRENT", resolution=300)
        ms.currentPageNumber = ms.getPageNumberFromName("Washington") 
        ms.exportToPDF(relpath + "\\Output\\Ex1_WA.pdf", "CURRENT")

MapSeries 示例 2

以下脚本将地图系列的每一页导出到单个 PNG 文件中，并将索引要素的页面名称作为输出文件名的一部分使用：

import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(relpath + "\\MapSeries\\US_States.aprx")
l = p.listLayouts()[0]
if not l.mapSeries is None:
  ms = l.mapSeries
  if ms.enabled:
    for pageNum in range(1, ms.pageCount + 1):
      ms.currentPageNumber = pageNum
      print("Exporting {0}".format(ms.pageRow.STATE_NAME))
      pageName = ms.pageRow.STATE_NAME
      l.exportToPNG(os.path.join(relpath, "Output", f"Ex2_{ms.pageRow.STATE_NAME}.png"))

MapSeries 示例 3

以下脚本只会将所选页面导出为单独的多页 PDF 文件：

import arcpy
import os
import sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(relpath + "\\MapSeries\\US_States.aprx")
l = p.listLayouts()[0]

if not l.mapSeries is None:
    ms = l.mapSeries
    if ms.enabled:
        ms = l.mapSeries
        indexLyr = ms.indexLayer
        arcpy.management.SelectLayerByAttribute(indexLyr, "NEW_SELECTION", "SUB_REGION = 'New England'")
        ms.exportToPDF(relpath + "\\Output\\Ex3_SelectedFeatures.pdf", "SELECTED")

MapSeries 示例 4（书签地图系列）

如前所述，MapSeries 类仅支持空间地图系列。但是，使用以下代码示例，无需使用 MapSeries 类即可模拟书签地图系列。首先，需要使用 listBookmarks 方法引用地图的书签。其次，可使用 zoomToBookmark 方法设置 MapFrame 的照相机信息。最后，需要使用其众多导出功能之一导出布局。将针对最终输出所需的每个页面重复此过程。

import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(os.path.join(relpath, "Bookmarks.aprx"))
m = p.listMaps('Great Lakes')[0]
lyt = p.listLayouts('GreatLakes')[0]
mf = lyt.listElements('MAPFRAME_ELEMENT')[0]
for bk in m.listBookmarks():
    mf.zoomToBookmark(bk)
    lyt.exportToPNG(os.path.join(relpath, f'{bk.name}.png'))

有关此主题的反馈?

摘要

说明

注：

属性

注：

提示：

方法概述

方法

代码示例

在本主题中