摘要
通过 BookmarkMapSeries 对象，可以访问用于管理书签地图系列的属性和方法。
说明
arcpy.mp 模块支持两种类型的地图系列：空间和书签。 如果存在空间地图系列，则 Layout 对象的 mapSeries 属性将返回 mapSeries 对象；如果存在书签地图系列，则将返回 BookmarkMapSeries 对象；如果地图系列不存在或者未启用，则将返回 NoneType 值。 BookmarkMapSeries 类可用于在导出期间自定义单个地图系列页面。 一个示例为对开页面，其中偶数页面与奇数页面的偏移量不同，以适应装订空间。
可以使用 createBookmarkMapSeries 方法，通过传入 MapFrame 对象以及（可选）用于创建书签地图系列的每个页面的 Bookmark 对象列表来创建新的书签地图系列。 如果您未传入书签列表，则会默认使用与 MapFrame 对象关联的 Map 对象中的书签。 bookmarks 属性代表地图系列中的书签列表。 可以通过多种方式修改书签列表并将其设置回书签地图系列，以控制应用程序中或者导出期间显示的页面顺序。
与应用程序类似，可以使用 export 方法将地图系列导出为 JPEG、PDF、PNG 和 TIFF 文件格式。 如果需要非默认值，也可以使用 MapSeriesExportOptions 对象进一步配置这些格式。 当导出地图系列时，将支持与地图系列关联的所有动态元素。 例如，动态文本元素（如页面名称、页码、书签名称等）将自动更新。 如果图例、表格框和图表框等地图整饰要素已设置为使用地图系列约束，则这些元素也会动态更新。
注：
地图系列导出可能仅限于以上列出的格式，并且可以使用 MapSeriesExportOptions 进行进一步配置，但这并不意味着您无法模拟地图系列导出为其他格式。 该过程需要使用当前地图系列页面更新布局，并导出布局，而非地图系列。 以下第二个代码示例演示了此操作方法。
通过 getDefinition 和 setDefinition 方法可以访问未向 BookmarkMapSeries 对象暴露的 CIM 属性。 有关详细信息和代码示例，请参阅 Python CIM 访问帮助主题。
属性
| 属性 | 说明 | 数据类型 |
| bookmarks (可读写) | 将用于书签地图系列的书签列表。 注：如果您通过设置一列新书签修改了书签列表，您需要调用 refresh 方法，以在应用程序中更新书签地图系列页面。 | List |
| currentBookmark (只读) | 返回地图系列中显示的当前书签。 | Bookmark |
| currentPageNumber (可读写) | 地图系列中显示的书签页面对应的当前页码。 您将通过此方式设置适用的书签页面。 如果您不确定页码，则可以使用 getPageNumberFromName 方法根据书签名称获取页码。 以下是使用书签 name 值设置 currentPageNumber 属性的示例。 | Long |
| enabled (可读写) | 指定是否启用地图系列。 提示：更改地图系列属性之前，请确认此属性已设置为 True。 | Boolean |
| mapFrame (可读写) | 与地图系列关联的 MapFrame 对象。 如果您更改了地图框，原始书签保持不变，则还应使用 refresh 方法。 | MapFrame |
| pageCount (只读) | 已启用地图系列的布局的总页数。 此值对应于书签总数。 | Long |
方法概述
| 方法 | 说明 |
| export (export_format, {mapseries_export_options}, {display_options}) |
export 方法可使用指定 export_format 导出 BookmarkMapSeries，还可以选择性地使用不同的 mapseries_export_options 或 display_options。 |
| 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}, {output_as_image}, {embed_color_profile}, {pdf_accessibility}, {show_export_count}, {keep_layout_background}, {convert_markers}, {simulate_overprint}) | 将启用了地图系列的布局的一组指定页面导出为便携式文档格式 (PDF) 文件。 旧版本：此方法在 ArcGIS AllSource 3.4 中已被 export 取代，保留此方法仅供旧版脚本使用。 所有增强功能和未来开发将仅针对导出方法。 |
| getDefinition (cim_version) | 返回书签地图系列的 CIM 定义。 |
| getPageNumberFromName (page_name) | 返回当前显示的书签地图系列页面对应的页码。 |
| refresh () | 用于刷新现有书签地图系列。 |
| setDefinition (definition_object) | 设置书签地图系列的 CIM 定义。 |
方法
export (export_format, {mapseries_export_options}, {display_options})| 参数 | 说明 | 数据类型 |
export_format | The supported export_format objects are JPEGFormat, PDFFormat, PNGFormat, and TIFFFormat. | Object |
mapseries_export_options | The MapSeriesExportOptions object is only needed if there are changes to its default property values. | Object |
display_options | The DisplayOptions object that includes changes to the default antialiasing property values. | Object |
有关更多详细信息和代码示例，请参阅 MapSeriesExportOptions 和 DisplayOptions 帮助主题。
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}, {output_as_image}, {embed_color_profile}, {pdf_accessibility}, {show_export_count}, {keep_layout_background}, {convert_markers}, {simulate_overprint})| 参数 | 说明 | 数据类型 |
out_pdf | 用于表示输出导出文件的路径和文件名的字符串。 | String |
page_range_type | 指定页面将如何打印的字符串值。
(默认值为 ALL) | String |
page_range_string | 如果使用 page_range_type 参数中的 RANGE 选项，用于标识要导出的页面的字符串（例如：1、3、5-12）。 如果使用任何其他 page_range_type 值，则将忽略 page_range_string 值。 | String |
multiple_files | 用于控制如何创建输出 PDF 文件的字符串。 默认情况下，所有页面都将导出为单个多页文档。
(默认值为 PDF_SINGLE_FILE) | String |
resolution | 用于定义导出文件分辨率的整数值，单位为每英寸点数 (dpi)。 (默认值为 96) | Integer |
image_quality | 定义输出图像质量的字符串。
(默认值为 BEST) | String |
compress_vector_graphics | 用于控制输出文件的矢量和文本部分压缩的布尔值。 图像压缩单独定义。 (默认值为 True) | Boolean |
image_compression | 用于定义在输出文件中压缩图像或栅格数据时使用的压缩方案的字符串。
(默认值为 ADAPTIVE) | String |
embed_fonts | 用于控制导出文件中的字体嵌入的布尔值。 当在未安装所需字体的计算机上查看文档时，可通过字体嵌入正确显示文本和字符标记。 (默认值为 True) | Boolean |
layers_attributes | 用于控制导出文件中包含的 PDF 图层和 PDF 对象数据（属性）的字符串。
(默认值为 LAYERS_ONLY) | String |
georef_info | 用于将每个地图框的坐标系信息导出到输出 PDF 文件中的布尔值。 (默认值为 True) | Boolean |
jpeg_compression_quality | 当 image_compression 设置为 ADAPTIVE 或 JPEG 时，用于控制压缩质量值的数字。 有效范围为 1 到 100。 jpeg_compression_quality 为 100 时可提供最佳图像质量，但会创建较大的导出文件。 推荐范围为 70 到 90。 (默认值为 80) | Integer |
clip_to_elements | 如果设置为 True，则布局将被裁剪为包含所有布局元素的最小边界框。 (默认值为 False) | Boolean |
output_as_image | 如果设置为 True，则矢量内容可以另存为图像。 如果地图或布局包含具有高密度顶点的矢量图层，则选择此选项可减小输出文件的大小。 如果导出为 PDF 并将此选项设置为 True，则无法在输出中查看 PDF 图层。 (默认值为 False) | Boolean |
embed_color_profile | 如果设置为 True，则颜色配置文件信息将嵌入在图像的元数据中。 (默认值为 True) | Boolean |
pdf_accessibility | 输出标记 PDF 文件，以供屏幕读取器或其他辅助技术读取文本。 标记 PDF 文件可包含地图框、图片和图表框的替代文本，即屏幕读取器用于描述元素的图片元素的文本描述。 替代文本会添加到每个元素的元素窗格中。
(默认值为 False) | Boolean |
show_export_count | 如果设置为 True，您将看到每个正在导出页面的状态显示在 Python shell 中。 (默认值为 False) | Boolean |
keep_layout_background | 如果设置为 True，白色背景将包含在导出中。 (默认值为 True) | Boolean |
convert_markers | 用于控制将基于字符的标记符号转换为面的布尔值。 如果符号字体不可用或无法嵌入，则可用于正确显示符号。 但是，将此参数设置为 True 将禁用所有基于字符的标记符号的字体嵌入，由此会导致其外观发生变化。 (默认值为 False) | Boolean |
simulate_overprint | 模拟叠印（也称被为软打样）用于表示在页面上打印时油墨重叠区域的显示方式。 您将在符号图层上设置叠印。 (默认值为 False) | Boolean |
PDF 文件可跨不同平台实现一致的查看和打印效果。 它们通常用于在 Web 上分发文档，并且此格式现在为内容传送的标准交换格式。 PDF 文件在许多图形应用程序中均可编辑，并且它还保留了地图图层的注记、标注和属性数据。 PDF 导出支持字体嵌入，即使在用户尚未安装 Esri 字体时，也可以正确显示符号系统。
旧版本：
此方法在 ArcGIS AllSource 3.4 中已被 export 取代，保留此方法仅供旧版脚本使用。 所有增强功能和未来开发将仅针对导出方法。
getDefinition (cim_version)
| 参数 | 说明 | 数据类型 |
cim_version | A string that represents the major version of the CIM that will be used.
| String |
| 数据类型 | 说明 |
| Object | 返回 BookmarkMapSeries 的 CIM 定义。 |
有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。
getPageNumberFromName (page_name)
| 参数 | 说明 | 数据类型 |
page_name | The name of the Bookmark based on the Name field that was used to set up the map series. | String |
许多地图系列属性和方法使用页码值而非页面的文本名称。 getPageNumberFromName 方法提供了一种用于根据页面名称获取页码的机制。
bms = layout.mapSeries
pageNumber = ms.getPageNumberFromName("HarborView")
bms.currentPageNumber = pageNumberrefresh ()
如果对任何书签进行更改或者修改其顺序，请使用 refresh 方法刷新应用程序中的书签地图系列页面。
setDefinition (definition_object)
| 参数 | 说明 | 数据类型 |
definition_object | A modified CIM definition object originally retrieved using getDefinition. | Object |
有关使用 CIM 和代码示例的详细信息，请参阅 Python CIM 访问。
代码示例
以下脚本可检查是否存在书签地图系列，然后根据书签名称将其中的两个页面导出至 PDF。 由于其一次导出一个 PDF，因此需要配置 MapSeriesExportOptions 类以导出 CURRENT 页面。 仅需创建一次 PDFFormat 对象，因为 filePath 属性在导出之间会更改。
import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])
p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
lyt = p.listLayouts('Layout_BMS')[0]
bms = lyt.mapSeries
#Create a new PDF format and change the resolution from its default value of 96
pdf = arcpy.mp.CreateExportFormat('PDF')
pdf.resolution = 300
#Modify map series export options to export only the current page
msOpt = arcpy.mp.CreateExportOptions('MAPSERIES')
msOpt.setExportPages('CURRENT')
if isinstance(bms, arcpy._mp.BookmarkMapSeries):
if bms.enabled:
bms.currentPageNumber = bms.getPageNumberFromName("Lake Superior")
pdf.filePath = os.path.join(relpath, 'Output', 'Ex1_LakeSuperior.pdf')
bms.export(pdf, msOpt)
bms.currentPageNumber = bms.getPageNumberFromName("Lake Huron")
pdf.filePath = os.path.join(relpath, 'Output', 'Ex1_LakeHuron.pdf')
bms.export(pdf, msOpt)以下脚本将地图系列的每一页导出为单个 .bmp 文件，并将书签名称用作输出文件名的一部分。
import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])
p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
lyt = p.listLayouts('Layout_BMS')[0]
bms = lyt.mapSeries
#Create a new PNG format that uses only defaults
bmp = arcpy.mp.CreateExportFormat('BMP')
if ((type(bms).__name__ == 'BookmarkMapSeries')):
if bms.enabled:
for pageNum in range(1, bms.pageCount + 1): #All pages, zero based index
bms.currentPageNumber = pageNum
bkmkName = bms.currentBookmark.name
print(f"Exporting {bkmkName}")
bmp.filePath =os.path.join(relpath,'Output', f'Ex2_{bkmkName}.bmp')
lyt.export(bmp)以下脚本可创建一个 Map 对象、一个 Layout 对象和一个 MapFrame 对象。 接下来，它将图层文件添加至地图并遍历每个要素，以使用要素几何设置书签范围来创建书签列表。 接下来，它将创建一个书签地图系列，并使用 Python CIM 访问修改未向 BookmarkMapSeries 对象暴露的一些 CIM 属性。 例如设置起始页码和比例的舍入。 最后，脚本会将地图系列导出至单个 PDF。
import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])
#Function used to create a rectangle where the anchor point is lower left corner
def MakeRec_LL(llx, lly, w, h):
xyRecList = [[llx, lly], [llx, lly+h], [llx+w,lly+h], [llx+w,lly], [llx,lly]]
array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
rec = arcpy.Polygon(array)
return rec
p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
#Create a new map, layout, and map frame
m = p.createMap('New Map', 'MAP')
lyt = p.createLayout(8.5, 11, 'INCH', 'New Layout')
mf = lyt.createMapFrame(MakeRec_LL(0.5,5.5,7.5,5), m, "New Map Frame")
#Add a layer file and zoom to each feature and create a bookmark and add to list
lyrFile = arcpy.mp.LayerFile(os.path.join(relpath, 'GreatLakes', 'GreatLakes.lyrx'))
lyr = m.addLayer(lyrFile)[0]
bkmkList = []
for row in arcpy.da.SearchCursor(lyr, ['SHAPE@', 'NAME']):
mf.camera.setExtent(row[0].extent)
mf.camera.scale = mf.camera.scale * 1.1 #add a slight buffer
bkmkList.append(mf.createBookmark(row[1]))
#Create and export a bookmark map series
bms = lyt.createBookmarkMapSeries(mf, bkmkList)
#Modify CIM properties
bms_cim = bms.getDefinition('V3')
bms_cim.startingPageNumber = 2
bms.scaleRounding = 10000
bms.setDefinition(bms_cim)
#Export to PDF
pdf = arcpy.mp.CreateExportFormat('PDF', os.path.join(relpath, 'Output', 'Ex3_NewBMS.pdf'))
bms.export(pdf)以下脚本可在引用现有书签地图系列后对地图的书签进行排序。 必须调用刷新方法以确认书签页面在应用程序中已重新排序。
import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])
p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
lyt = p.listLayouts('Layout_BMS')[0]
bms = lyt.mapSeries
if isinstance(bms, arcpy._mp.BookmarkMapSeries):
if bms.enabled:
bms_cim = bms.getDefinition('V3')
sortList = sorted(bms_cim.pages, key=lambda CIMBookmarkMapSeriesPage: CIMBookmarkMapSeriesPage.bookmarkName)
bms_cim.pages = sortList
bms.setDefinition(bms_cim)
pdf = arcpy.mp.CreateExportFormat('PDF', os.path.join(relpath, 'Output', 'Ex4_Sorted.pdf'))
bms.export(pdf)以下脚本将空间地图系列中的所有页面导出为单个 PDF，将书签地图系列中的所有页面导出为另一个 PDF，然后将生成的两个 PDF 组合成单个新创建的 PDF。
import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])
arcpy.env.overwriteOutput = True
p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
#Export spatial map series
sms_lyt = p.listLayouts('Layout_MS')[0]
sms = sms_lyt.mapSeries
if ((type(sms).__name__ == 'MapSeries')):
if sms.enabled:
pdf = arcpy.mp.CreateExportFormat('PDF', os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
sms.export(pdf)
#Export bookmark map series
bms_lyt = p.listLayouts('Layout_BMS')[0]
bms = bms_lyt.mapSeries
if ((type(bms).__name__ == 'BookmarkMapSeries')):
if bms.enabled:
pdf = arcpy.mp.CreateExportFormat('PDF', os.path.join(relpath, 'Output', 'Temp_bms.pdf'))
bms.export(pdf)
#Combine PDFs and remove temporary files
comboPDF = arcpy.mp.PDFDocumentCreate(os.path.join(relpath, 'Output', 'Ex5_Combo.pdf'))
comboPDF.appendPages(os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
comboPDF.appendPages(os.path.join(relpath, 'Output', 'Temp_bms.pdf'))
comboPDF.saveAndClose()
os.remove(os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
os.remove(os.path.join(relpath, 'Output', 'Temp_bms.pdf'))