Map

摘要

Map 是引用和管理 ArcGIS Pro 工程中的图层和表的主要对象。

说明

ArcGIS Pro 的 Map 用于表示表格与符号化地理图层的集合，同时用于保留坐标系、默认数据视图和其他各种元数据的信息。对地图内容进行可视化的唯一方式是在地图视图（即在具有自己的内容表的应用程序中作为选项卡）或在页面布局上的地图框中进行。可在多个地图视图或地图框中显示同一地图。如果已将图层添加到地图，则所有引用此地图的地图视图和地图框将显示已添加的图层。如果您希望在其他视图中显示其他图层或表集合，则您需要构建并使用其他地图。

可从 ArcGISProject 对象使用 listMaps 函数访问地图，这将返回 Map 对象的 Python 列表。有必要确保每个地图均具有唯一名称，因为这样可以使用 name 属性轻松引用特定地图。同时还可以使用 map 属性从 MapFrame 对象访问地图。注：arcpy.mp 不可用于访问应用程序内的地图视图；仅可用于访问地图框。

Map 对象上提供了多种用于管理表格与符号化地理图层集合的方法。可在现有图层和表的列表内添加图层和表（addLayer、addLayerToGroup、addTable 或 insertLayer）、移除图层和表（removeLayer 或 removeTable）或重新排列图层和表（moveLayer）。listLayers 和 listTables 方法是引用地图中的 Layers 和 Tables 的方法。

每个地图均具有 mapType 属性。如果具有 MAP 值，则表示 2D 地图，如果具有 SCENE 值，则表示 3D 地图。例如，如果您想要设置 defaultCamera 属性，则需要了解 mapType 属性。无法将 3D Camera 对象应用到 2D 地图，反之亦然。因此，您应该提前检查 mapType 值。

属性

属性	说明	数据类型
defaultCamera (可读写)	用于获取或设置地图的默认照相机设置。 注： 修改 defaultCamera 将不会影响现有视图。仅当打开新的 MapView 或将新的 MapFrame 插入布局中时，才会应用此属性。	Camera
defaultView (只读)	与 Web 地图打印 Web 工具中的 ConvertWebMapToArcGISProject 一起使用，以返回要打印或导出的地图视图。	MapView
mapType (只读)	返回用于报告 Map 对象类型信息的字符串值。如果 Map 是 2D，则返回 MAP。如果 Map 是 3D，则返回 SCENE。	String
mapUnits (只读)	返回用于表示为 Map 设置的地图单位的字符串值。	String
metadata (可读写)	获取或设置地图的元数据类信息。请注意：设置元数据取决于 isReadOnly 属性值。	Metadata
name (可读写)	用于在 Map 对象出现在内容列表中时获取或设置其名称，同时还用于获取或设置布局内的实际元素名称。	String
referenceScale (可读写)	用于获取或设置 Map 的参考比例。要清除最小比例，请将值设置为 0.0	Double
spatialReference (可读写)	用于获取或设置与地图相关联的 SpatialReference。	SpatialReference

方法概述

方法	说明
addBasemap (basemap_name)	addBasemap 可用于在地图内添加或替换底图图层。
addDataFromPath (data_path)	addDataFromPath 可通过提供本地路径或 URL 向工程中的地图 (.aprx) 添加图层。
addLayer (add_layer_or_layerfile, {add_position})	用于使用基本放置选项向工程 (.aprx) 内的地图添加 Layer 或 LayerFile。
addLayerToGroup (target_group_layer, add_layer_or_layerfile, {add_position})	用于使用基本放置选项向工程 (.aprx) 内地图中的现有图层组添加 Layer 或 LayerFile 内容。
addTable (add_table)	用于向工程 (.aprx) 内的地图中添加 Table。
clearSelection ()	清除地图中所有图层和表的选择。
exportToMAPX (out_mapx)	用于将 Map 导出至地图文件。
getDefinition (cim_version)	获取地图的 CIM 定义。
getWebLayerSharingDraft (server_type, service_type, service_name, {layers_and_tables})	在可配置并共享到 ArcGIS Enterprise 或 ArcGIS Online 的地图中创建共享草稿。
insertLayer (reference_layer, insert_layer_or_layerfile, {insert_position})	用于通过指定特定位置向工程 (.aprx) 内的地图添加 Layer 或 LayerFile。
listBookmarks ({wildcard})	返回 Map 中的 bookmark 对象的 Python 列表。
listBrokenDataSources ()	返回地图中到原始源数据的连接存在断开情况的 Layer 或 Table 对象的 Python 列表。
listLayers ({wildcard})	返回存在于地图中的 Layer 对象的 Python 列表。
listTables ({wildcard})	返回存在于地图中的 Table 对象的 Python 列表。
moveLayer (reference_layer, move_layer, {insert_position})	用于在图层堆叠中将地图中的图层或图层组移动到特定位置。
removeLayer (remove_layer)	用于从工程内的地图中移除图层。
removeTable (remove_table)	用于从工程内的地图中移除表。
setDefinition (definition_object)	设置地图的 CIM 定义。
updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case})	使用工作空间字典或路径替换连接属性。

方法

addBasemap (basemap_name)

参数	说明	数据类型
basemap_name	底图名称显示在底图库中。	String

addBasemap 方法的工作方式与地图功能区上底图控制的工作方式相同。如果底图不存在，则将添加一个新底图。如果已存在一个或多个底图，它们则会被正在添加的底图替代。

如果要向地图添加多个底图，请将底图保存为图层文件，然后使用 LayerFile 和 addLayer 方法进行添加。

addDataFromPath (data_path)

参数	说明	数据类型
data_path	表示本地路径或 URL 的字符串。 (默认值为 None)	String

返回值

数据类型	说明
Layer	一个图层对象。

addDataFromPath 方法提供了一种向地图添加图层的方法，这与从路径添加数据按钮在应用程序中的工作方式相似，即根据图层权重规则和几何类型放置图层。有关更精确的图层放置控制，请参阅 moveLayer 方法。

addLayer (add_layer_or_layerfile, {add_position})

参数	说明	数据类型
add_layer_or_layerfile	对 Layer 或 LayerFile 对象（表示要添加的单个或多个图层）的引用。	Layer
add_position	此常数用于确定在地图中添加的单个或多个图层的放置位置。 AUTO_ARRANGE —基于图层权重规则和几何来自动放置单个或多个图层。 BOTTOM —在 TOC 图层堆叠底部放置单个或多个图层。 TOP —在 TOC 图层堆叠顶部放置单个或多个图层。 (默认值为 AUTO_ARRANGE)	String

返回值

数据类型	说明
List	Layer 对象的 Python 列表。

addLayer 方法用于向地图添加图层或图层集合。默认 add_position 可以使用自动排列逻辑添加图层，将图层放置在地图中，这与添加数据按钮在应用程序中的工作方式相似；add_position 根据图层权重规则和几何类型放置图层。其他放置选择为放置在图层堆叠的 TOP 或 BOTTOM。有关更精确的图层放置控制，请参阅 insertLayer 方法。

已添加的图层可以引用同一工程或单独工程中的现有图层，或引用磁盘上的图层文件（.lyr 或 .lyrx）。图层可以引用单个图层、含有多个子图层的图层组，或根级别的图层或图层组的集合（如果引用 .lyrx 文件）。有关图层文件的详细信息，请参阅 LayerFile。

添加图层后，图层在内容列表 (TOC) 中的显示方式取决于源图层及其显示方式。例如，在 TOC 中，有些图层完全折叠且不显示其符号。此设置内置在图层中。如果图层折叠且保存在图层文件中，然后被添加到地图中，则通过 addLayer 添加该图层时，图层在新地图中将显示为折叠状态。

addLayerToGroup (target_group_layer, add_layer_or_layerfile, {add_position})

参数	说明	数据类型
target_group_layer	对现有 Layer 对象组的引用。	Layer
add_layer_or_layerfile	对 Layer 或 LayerFile 对象（表示要添加的单个或多个图层）的引用。	Layer
add_position	此常数用于确定在 target_group_layer 中添加的单个或多个图层的放置位置。 AUTO_ARRANGE —基于图层权重规则和几何来自动放置图层。 BOTTOM —在 TOC 图层堆叠底部放置图层。 TOP —在 TOC 图层堆叠顶部放置图层。 (默认值为 AUTO_ARRANGE)	String

addLayerToGroup 方法仅会向地图中现有的空图层组添加图层或图层集合。默认 add_position 可以使用自动排列逻辑添加图层，将图层放置在地图中，这与添加数据按钮在应用程序中的工作方式相似；add_position 根据图层权重规则和几何类型放置图层。其他放置选择为放置在图层堆叠的 TOP 或 BOTTOM。有关更精确的图层放置控制，请参阅 insertLayer 方法。

已添加的图层可以引用同一工程或单独工程中的现有图层，或引用磁盘上的图层文件（.lyr 或 .lyrx）。图层可以引用单个图层、含有多个子图层的图层组，或根级别的图层或图层组的集合（如果引用 .lyrx 文件）。有关图层文件的详细信息，请参阅 LayerFile。

添加图层后，图层在内容列表 (TOC) 中的显示方式取决于源图层及其显示方式。例如，在 TOC 中，有些图层完全折叠且不显示其符号。此设置内置在图层中。如果图层折叠且保存在图层文件中，然后被添加到地图中，则通过 addLayerToGroup 添加该图层时，图层在新地图中将显示为折叠状态。

addTable (add_table)

参数	说明	数据类型
add_table	对 Table 对象（表示要添加的表）的引用。	Table

返回值

数据类型	说明
Table	引用 Table 对象。

addTable 方法用于将表添加到地图中。想要使用 Map 对象上的 listTables 方法添加的表可以是现有地图中的表，也可以是磁盘或通过 Table 函数引用的数据集中的表。

clearSelection ()

清除地图中所有图层和表的选择。

exportToMAPX (out_mapx)

参数	说明	数据类型
out_mapx	用于将 Map 保存至地图文件 (.mapx) 的字符串。	String

如果您希望将地图保存至地图文件，以供日后使用 ArcGISProject importDocument 方法将其导入到工程中，则此方法将非常有用。

getDefinition (cim_version)

参数	说明	数据类型
cim_version	用于表示 CIM 的主要版本的字符串。	String

在版本 2.4 中引入了对其他对象属性的 CIM 级别访问权限。Esri 遵循语义版本规范。这意味着，在允许突破性 API 更改的下一个主要版本（例如，3.0）之前，与 cim_version 搭配使用的值为 V2。发布 3.0 之后，新 V3 选项将可用。如果可能在新版本中引入突破性更改，Python 脚本作者可通过该选项控制执行期间将使用的 CIM 版本。

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

getWebLayerSharingDraft (server_type, service_type, service_name, {layers_and_tables})

参数	说明	数据类型
server_type	表示服务器类型的字符串。支持的服务器类型如下： HOSTING_SERVER —支持将 web 要素图层或 web 切片图层发布到 ArcGIS Enterprise 或 ArcGIS Online。在 service_type 参数中指定 FEATURE 或 TILE 时，可使用该选项。 FEDERATED_SERVER —支持将地图图像图层发布到 ArcGIS Enterprise 门户联合服务器。在 service_type 参数中指定 MAP_IMAGE 时，可使用该选项。 提示： getWebLayerSharingDraft 函数不支持将地图服务发布到 ArcGIS Server。应使用 arcpy.sharing.CreateSharingDraft 函数。	String
service_type	表示服务类型的字符串。支持的服务类型如下： FEATURE — 为 web 要素图层创建 FeatureSharingDraft。 TILE — 为 web 切片图层创建 TileSharingDraft。 MAP_IMAGE — 为地图图像图层创建 MapImageSharingDraft。	String
service_name	用于表示服务名称的字符串。用户可以看到该名称并使用该名称来识别服务。名称只能包含字母数字字符和下划线。不允许使用空格或特殊字符。名称长度不能超过 120 个字符。	String
layers_and_tables	地图中的图层和表格列表。如果留空，则将发布整个地图。该参数允许您从地图中选择图层和表格的子集进行发布。图层和表格必须来自正在发布的同一地图。	List

返回值

数据类型	说明
Object	返回 FeatureSharingDraft、TileSharingDraft 或 MapImageSharingDraft 类对象。

getWebLayerSharingDraft 函数可基于 ArcGIS Pro 工程中的地图创建共享草稿。共享草稿是适用于 web 图层的可配置属性集。共享草稿配置完成后，可以使用 FeatureSharingDraft、TileSharingDraft 或 MapImageSharingDraft 类中的 exportToSDDraft 函数将其保存到服务定义草稿 (.sddraft) 文件。随后即可使用过渡服务和上传服务定义工具将其过渡和共享给 ArcGIS Enterprise 或 ArcGIS Online。有关详细信息，请参阅共享模块简介。

insertLayer (reference_layer, insert_layer_or_layerfile, {insert_position})

参数	说明	数据类型
reference_layer	表示可确定新图层插入位置的现有图层的 Layer 对象。	Layer
insert_layer_or_layerfile	对 Layer 或 LayerFile 对象（表示要添加的单个或多个图层）的引用。	Layer
insert_position	此常数用于确定相对于 reference_layer 的单个或多个图层的放置位置。 AFTER —在参考图层之后或下方插入新图层。 BEFORE —在参考图层之前或上方插入新图层。 (默认值为 BEFORE)	String

因使用了 reference_layer 来指定准确位置，insertLayer 方法可在地图或图层组中更为精确地定位图层。可将该图层添加到 reference_layer 的 before 或 after。

如果 reference_layer 引用的是地图根级别的图层，则所插入的图层会添加到根级别。如果 reference_layer 引用的是图层组中的图层，则所插入的图层将添加到该图层组中。因为 reference_layer 为必需参数，所以无法使用 insert_layer 将图层添加到空地图或空图层组中。使用 addLayer 或 addLayerToGroup 方法将图层或图层集合分别添加到空地图或空图层组中。

已插入的图层可以引用同一工程或单独工程中的现有图层，或引用磁盘上的图层文件（.lyr 或 .lyrx）。图层可以引用单个图层、含有多个子图层的图层组，或根级别的图层或图层组的集合（如果引用 .lyrx 文件）。有关图层文件的详细信息，请参阅 LayerFile。

添加图层后，图层在内容列表 (TOC) 中的显示方式取决于源图层及其显示方式。例如，在 TOC 中，有些图层完全折叠且不显示其符号。此设置内置在图层中。如果图层折叠且保存在图层文件中，然后被添加到地图中，则通过 insertLayer 添加该图层时，图层在新地图中将显示为折叠状态。

listBookmarks ({wildcard})

参数	说明	数据类型
wildcard	通配符基于书签名称且不区分大小写。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None)	String

返回值

数据类型	说明
List	listBookmarks 方法始终返回 Python 列表对象，即使仅返回一个已损坏图层或表。

返回 Map 中的 bookmark 对象的 Python 列表。

listBrokenDataSources ()

返回值

数据类型	说明
List	Layer 或 Table 对象的 Python 列表。

listBrokenDataSources 方法始终返回 Python 列表对象，即使仅返回一个已损坏图层或表。

listLayers ({wildcard})

参数	说明	数据类型
wildcard	通配符基于图层名称且不区分大小写。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None)	String

返回值

数据类型	说明
List	返回地图中的 Layer 对象的 Python 列表。

返回存在于地图中的 Layer 对象的 Python 列表。ListLayers 始终返回列表对象，即使仅返回一个表。

地图中可以存在名称相同的图层。在这种情况下，可能需要使用其他属性来隔离特定图层。例如，图层的 datasource 或 definitionQuery 属性可用来执行此操作。理想状态为地图中的所有图层名称均唯一。

listTables ({wildcard})

参数	说明	数据类型
wildcard	通配符基于图层名称且不区分大小写。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None)	String

返回值

数据类型	说明
List	地图中的 Table 对象的 Python 列表。

返回存在于地图中的 Table 对象的 Python 列表。ListTables 始终返回列表对象，即使仅返回一个表。

地图中可以存在名称相同的表。在这种情况下，可能需要使用其他属性来隔离特定图层。例如，表的 datasource 或 definitionQuery 属性可用来执行此操作。理想状态为地图中的所有表名称均唯一。

moveLayer (reference_layer, move_layer, {insert_position})

参数	说明	数据类型
reference_layer	表示可确定新图层移动位置的现有图层的 Layer 对象。	Layer
move_layer	对 Layer 对象（表示要移动的图层）的引用。	Layer
insert_position	此常数用于确定移动的图层相对于参考图层的放置位置。 AFTER —将图层移动到参考图层的后面或下方。 BEFORE —将图层移动到参考图层的前面或上方。 (默认值为 BEFORE)	String

moveLayer 方法将用于移动地图中的图层，同时还可以用于在同一地图内将图层移入或移出图层组。move_layer 和 reference_layer 必须位于同一地图内。不能将图层从一个地图移动到另一个地图中，即使在同一工程中也不可以。使用 addLayer、addLayerToGroup 或 insertLayer 代替。

removeLayer (remove_layer)

参数	说明	数据类型
remove_layer	引用表示要移除的图层的 Layer 对象。	Layer

RemoveLayer 将从特定地图中移除单个图层或图层组。如果有多个图层满足条件，则仅移除第一个图层，除非脚本会遍历返回列表中的每个图层。

removeTable (remove_table)

参数	说明	数据类型
remove_table	A reference to a Table object representing the layer to be removed.	Table

RemoveTable 将从特定地图中移除单个表。如果有多个表满足条件，则仅移除第一个表，除非脚本会遍历返回列表中的每个表。

setDefinition (definition_object)

参数	说明	数据类型
definition_object	使用 getDefinition 最初检索的已修改 CIM 定义对象。	Object

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

updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case})

参数	说明	数据类型
current_connection_info	用于表示工作空间路径或 Python 字典（包含要更新的源的连接属性）的字符串。	String
new_connection_info	用于表示包含连接属性与新源信息的工作空间路径或 Python 字典的字符串。	String
auto_update_joins_and_relates	如果设置为 True，则 updateConnectionProperties 方法还将更新相关连接或关联的连接。 (默认值为 True)	Boolean
validate	如果设置为 True，则仅在 new_connection_info 值为有效连接时，才会更新连接属性。如果为无效连接，则不会替换连接。如果设置为 False，则无论匹配是否有效，此方法都会将所有连接设置为匹配 new_connection_info。在这种情况下，如果匹配不存在，则将损坏数据源。 (默认值为 True)	Boolean
ignore_case	确定搜索是否区分大小写。默认情况下，查询区分大小写。要执行不区分大小写的查询，请将 ignore_case 设置为 True。 (默认值为 False)	Boolean

有关详细说明、参数信息、案例和代码示例，请参阅更新和修复数据源帮助主题。

代码示例

地图示例 1

下面的脚本引用了图层文件并将图层插入到地图中某一现有图层的上方。

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
insertLyr = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LayerFiles\Ranger Stations.lyrx")
m = aprx.listMaps("Yosemite National Park")[0]
refLyr = m.listLayers("Points of Interest")[0]
m.insertLayer(refLyr, insertLyr, "BEFORE")
aprx.saveACopy(r"C:\Projects\YosemiteNP\Yosemite_updated.aprx")

地图示例 2

下面的脚本将为项目中的当前所有地图和场景设置 defaultCamera 属性。将从具有所需查看器设置的现有地图框中复制照相机属性。将从 2D 地图框中复制所有地图，同时将从 3D 地图框中复制所有场景查看器设置。

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Main Attractions*")[0]
mpFrm2D = lyt.listElements("mapframe_element", "Yose*")[0]
mpFrm3D = lyt.listElements("mapframe_element", "Inset1")[0]
for m in aprx.listMaps():
    if m.mapType == "MAP":
        m.defaultMapViewer = mpFrm2D.mapViewer
    elif m.mapType == "SCENE":
        m.defaultMapViewer = mpFrm3D.mapViewer
aprx.save()
del aprx