摘要
ArcGISProject 对象用于访问 ArcGIS Pro 工程方法和属性。 大多数地图自动化工作流都需要引用此对象。
说明
ArcGISProject 对象用于访问 ArcGIS Pro 应用程序中找到的众多工程属性和方法。 ArcGISProject 对象通常是最先引用的对象（这些对象是在地图自动化脚本中创建的）之一，因为它是访问几乎所有其他 ArcGIS 工程对象的主要入口点。
具有对 ArcGISProject 对象的引用后，可以使用列表函数导航至许多对象。 例如，可以使用 listMaps 方法访问地图。 当具有对地图的引用时，可以使用列表函数引用图层或表对象。 通过这些对象，可以获取对 LabelClass 等其他对象的进一步访问权限。 还可以使用 listLayouts 方法深化到布局中。 在引用布局后，可访问布局元素，例如 GraphicElement、LegendElement、MapFrame、MapSurroundElement、pictureElement 和 TextElement。 ArcGISProject 对象还可以用于管理工程设置，如 defaultGeodatabase 和 defaultToolbox。
下图演示了用于导航和引用工程或图层文件内的对象的列表函数实用程序。 该图仅为示例，不显示完整对象集。 例如，不会显示 listReports 用于访问报表对象的组件。
importDocument 方法允许您将地图文档 (.mxd)、globe 文档 (.3dd) 和 scene 文档 (.sxd) 导入到工程中。 此操作提供了用于将这些文档类型自动转换为 ArcGIS Pro 工程的机制。 importDocument 方法还允许您将地图文件 (.mapx)、布局文件 (.pagx) 或报表文件 (.rptx) 导入到现有工程中。
有几个方法和属性仅适用于在应用程序内部运行的脚本，例如在 Python 窗格中运行的脚本或与脚本工具关联的脚本。 它们是 activeMap 属性、activeView 属性和 closeViews() 方法。 activeMap 属性将返回与活动布局视图上活动地图视图或活动地图框关联的地图。 如果不满足上述条件，则将返回 NoneType。 如果地图视图处于活动状态，则 activeView 属性将返回 MapView 对象，如果布局视图处于活动状态，则其将返回 Layout 对象。 如果没有活动视图，则两种属性都将返回 None。 当脚本在应用程序外部运行时，这些属性将始终返回 None 值，因为视图仅在应用程序打开时才会相关。 从 activeView 属性返回的 MapView 是更改与地图视图相关联的范围的唯一方法。 MapView 类提供多个函数，允许您更改范围，例如 camera 属性、panToExtent、ZoomToAllLayers 和 ZoomToBookmarks。 closeViews 函数可用于关闭应用程序内的特定视图类型。 要关注特定视图，建议关闭所有视图并在 Layout、Map 或 Report 类上使用 openView 方法。
ArcGISProject 类还支持多种内容管理方法。 它们为 createMap、copyItem 和 deleteItem。 createMap 方法可用于创建默认地图。 copyItem 和 deleteItem 方法仅限于 Layout、Map 和 Report 类。
属性
| 属性 | 说明 | 数据类型 |
| activeMap (只读) | 返回与应用程序内部焦点视图相关联的地图对象。 如果布局视图处于活动状态，则其将返回与活动地图框相关联的地图。 注：该属性旨在通过使用脚本工具或 Python 窗口内的应用程序来运行。 如果脚本在应用程序外部运行，则将始终返回 None。 | Map |
| activeView (只读) | 将返回 MapView 或 Layout，具体取决于当前视图。 如果 ArcGIS Pro 工程未打开视图，或者活动视图为地图视图或布局视图之外的其他内容（例如，图表、表格、Model Builder 视图等），则将返回 None。 注：该属性旨在通过使用脚本工具或 Python 窗口内的应用程序来运行。 如果脚本在应用程序外部运行，则将始终返回 None。 | Object |
| dateSaved (只读) | 返回报告上次工程保存日期的 Python datetime 对象。 | DateTime |
| defaultGeodatabase (可读写) | 工程的默认地理数据库位置。 字符串必须包含地理数据库的完整路径和文件名。 注：此属性可由管理员设置为只读，因此无法修改。 | String |
| defaultToolbox (可读写) | 工程的默认工具箱位置。 字符串必须包含工具箱的完整路径和文件名。 注：此属性可由管理员设置为只读，因此无法修改。 | String |
| documentVersion (只读) | 根据上次保存文档的时间返回文档版本。 运行 save 或 saveACopy 将更新文档版本，以匹配应用程序版本。 | String |
| filePath (只读) | 返回报告完全限定的工程路径和文件名的字符串值。 | String |
| folderConnections (只读) | 返回 Python 字典列表，每个字典表示工程中各个文件夹连接的属性。 此为只读属性。 检查 updateFolderConnections 方法获取有关字典的详细信息以及如何修改连接属性列表。 | List |
| homeFolder (可读写) | 工程的主目录文件夹位置。 字符串必须包含所需位置的完整路径。 注：此属性可由管理员设置为只读，因此无法修改。 | String |
| isReadOnly (只读) | 如果工程已在应用程序的另一个实例中打开或由另一个脚本参考，返回 True。 已知当前状态可确定您是否可以save工程或是否需要调用 saveACopy 等。 | Boolean |
| metadata (可读写) | 获取或设置工程的元数据类信息。 注：设置元数据取决于 isReadOnly 属性值。 | Metadata |
方法概述
| 方法 | 说明 |
| closeViews ({view_type}) | 用于关闭当前在 ArcGIS Pro 中打开的视图窗格。 |
| copyItem (project_item, {new_name}) | |
| createMap ({name}, {map_type}) | 此方法会创建一个地图，以自动添加至目录窗格。 |
| deleteItem (project_item) | |
| importDocument (document_path, {include_layout}, {reuse_existing_maps}) | 将地图文档 (.mxd)、globe 文档 (.3dd) 和场景文档 (.sxd) 导入到 ArcGIS Pro 工程中。 还可以用于导入地图文件 (.mapx)、布局文件 (.pagx) 和报表文件 (.rptx) 的内容。 |
| listBrokenDataSources () | |
| listColorRamps ({wildcard}) | listColorRamps 方法将引用工程中的可用色带。 |
| listLayouts ({wildcard}) | 返回 ArcGIS 工程 (.aprx) 中的 Layout 对象的 Python 列表。 |
| listMaps ({wildcard}) | 返回 ArcGIS 工程 (.aprx) 中的 Map 对象的 Python 列表。 |
| listReports ({wildcard}) | 返回 ArcGIS 工程 (.aprx) 中的报表对象的 Python 列表。 |
| save () |
将更改保存至 ArcGISProject (.aprx)。 |
| saveACopy (file_name) | 将 ArcGISProject (.aprx) 保存到新文件路径或另存为新文件名。 |
| updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case}) | updateConnectionProperties 方法使用工作空间字典或路径替换连接属性。 |
| updateFolderConnections (folder_connections, {validate}) | 使用描述每个连接的字典列表替换工程文件夹连接。 |
方法
closeViews ({view_type})| 参数 | 说明 | 数据类型 |
view_type | A constant that determines the type of views to be closed in the application.
(默认值为 MAPS_AND_LAYOUTS) | String |
copyItem (project_item, {new_name})| 参数 | 说明 | 数据类型 |
project_item | An object that represents a supported project item to be copied. | Object |
new_name | A string that represents the name of the new project item. If a name is not provided, the default name will follow the sequencing nomenclature, for example, Map, Map1, Map2. | String |
| 数据类型 | 说明 |
| Object |
createMap ({name}, {map_type})| 参数 | 说明 | 数据类型 |
name | A string that represents the name of the new map. If a name is not provided, the default name will follow the sequencing nomenclature, for example, Map, Map1, Map2. | String |
map_type | The type of map to be created and are defined by the keywords below.
(默认值为 Map) | String |
| 数据类型 | 说明 |
| Map | 如果指定了变量参考，将表示受支持的 map_type 对象之一。 |
此方法会返回对新地图类的参考。 如果脚本在应用程序内运行，则将应用在工程设置中指定的底图。 如果脚本独立运行，则将自动添加地形底图。
deleteItem (project_item)
| 参数 | 说明 | 数据类型 |
project_item | An object that represents a supported project item to be deleted. | Object |
项目将从工程中永久删除。 删除项目可能影响其他项目。 例如，如果删除在布局中使用的地图，参考地图的地图框将失去对地图的参考，map 属性将设置为 None。
importDocument (document_path, {include_layout}, {reuse_existing_maps})| 参数 | 说明 | 数据类型 |
document_path | A string that includes the system path and name of a document (.mxd, .3dd, or .sxd) or a map file (.mapx), layout file ( .pagx), or report file (.rptx). | String |
include_layout | A Boolean parameter indicating whether the layout from a map document (.mxd) is imported. If set to True, the layout and all data frames are imported. If set to False, only the data frames are imported. This parameter is ignored for other file types. (默认值为 True) | Boolean |
reuse_existing_maps | A Boolean parameter to prevent the creation of duplicate maps in the project. If reuse_existing_maps is set to True, it checks the project for the maps referenced in the imported file and only copies maps that don't already exist in the project. There may be cases in which maps have the same name in different imported sources, so you may want to set this value to False. (默认值为 False) | Boolean |
| 数据类型 | 说明 |
| Map | 导入地图文档 (.mxd) 时，如果 include_layout 为 True，则将返回对布局的引用。 如果 include_layout 为 False，将返回地图文档中的第一个地图。 将返回 globe (.3dd) 或场景 (.sxd) 文档中的唯一一张地图。 对应的布局随 .pagx 文件返回，报表随 .rptx 文件返回。 |
此方法一次导入一个文档。 要导入多个文档，对每个文档运行一次该方法。 地图文档 (.mxd) 始终具有布局。 迁移地图文档时，如果不想导入布局，则设置 include_layout=False。
listBrokenDataSources ()
| 数据类型 | 说明 |
| List |
listBrokenDataSources 方法始终返回 Python 列表对象，即使返回一个损坏的图层或表。
listColorRamps ({wildcard})| 参数 | 说明 | 数据类型 |
wildcard | 通配符将基于色带名称显示在应用程序中。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None) | String |
| 数据类型 | 说明 |
| List | 将返回 ColorRamp 对象列表。 |
在一个工程中，可能会有多个色带使用相同的名称。创作工程时，采用可通过唯一名称轻松进行搜索的色带名称非常重要。索引编号可用于返回一个特定的色带。例如，以下行可以返回列表中的第一个色带对象：cr = aprx.listColorRamps("Black*")[0]。
listLayouts ({wildcard})| 参数 | 说明 | 数据类型 |
wildcard | 通配符基于布局名称且不区分大小写。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None) | String |
| 数据类型 | 说明 |
| List | ArcGIS 工程中的 Layout 对象的 Python 列表。 |
返回 ArcGIS 工程 (.aprx) 中的 Layout 对象的 Python 列表。
listMaps ({wildcard})| 参数 | 说明 | 数据类型 |
wildcard | 通配符基于地图名称且不区分大小写。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None) | String |
| 数据类型 | 说明 |
| List | ArcGIS 工程中的 Map 对象的 Python 列表。 |
返回 ArcGIS 工程 (.aprx) 中的 Map 对象的 Python 列表。
listReports ({wildcard})| 参数 | 说明 | 数据类型 |
wildcard | 通配符基于报表名称且不区分大小写。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None) | String |
| 数据类型 | 说明 |
| List | ArcGIS 工程中的报表对象的 Python 列表。 |
返回 ArcGIS 工程 (.aprx) 中的报表对象的 Python 列表。
save ()
将更改保存至 ArcGISProject (.aprx)。已保存此项目，同时项目变量继续引用原始 ArcGISProject 对象。
saveACopy (file_name)
| 参数 | 说明 | 数据类型 |
file_name | 用来将 ArcGISProject (.aprx) 保存到新文件路径或另存为新文件名的字符串。 | String |
该方法会创建新输出工程文件，但工程变量继续引用原始 ArcGISProject 对象。并不会复制工程文件夹中的所有内容。
updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case})| 参数 | 说明 | 数据类型 |
current_connection_info | A string that represents the workspace path or a Python dictionary that contains connection properties to the source you want to update. If an empty string or None is used in current_connection_info, all connection properties will be replaced with the new_workspace_info, depending on the value of the validate parameter. | String |
new_connection_info | A string that represents the workspace path or a Python dictionary that contains connection properties with the new source information. | String |
auto_update_joins_and_relates | If set to True, the updateConnectionProperties method will also update the connections for associated joins or relates. (默认值为 True) | Boolean |
validate | If set to True, the connection properties will only be updated if the new_connection_info value is a valid connection. If it is not valid, the connection will not be replaced. If set to False, the method will set all connections to match the new_connection_info value, regardless of a valid match. In this case, if a match does not exist, the data sources would be broken. (默认值为 True) | Boolean |
ignore_case | Determines whether searches will be case sensitive. By default, queries are case sensitive. To perform queries that are not case sensitive, set ignore_case to True. (默认值为 False) | Boolean |
有关更详细的说明、参数信息、情景和代码示例，请参阅更新和修复数据源。
updateFolderConnections (folder_connections, {validate})| 参数 | 说明 | 数据类型 |
folder_connections [folder_connections,...] | A list of Python dictionaries that each contain connection properties to an individual folder. The dictionary keys are defined below.
| List |
validate | If set to True, the folder will only be added if the connectionString is a valid path. If it is not valid, the folder will not be added and the function will return the dictionary as an invalid folder. If set to False, the method will set all connections to match the connectionString, regardless of a valid match. In this case, if a match does not exist, the folder will be added but will appear as broken. (默认值为 True) | Boolean |
| 数据类型 | 说明 |
| List | 没有有效连接的文件夹列表。 |
要更新工程的文件夹连接，必须同时设置整个连接列表。 不能一次添加、移除或更新单一文件夹连接。 可以从头开始构建新列表，或可以修改 folderConnections 属性返回的列表，然后使用 updateFolderConnections 方法将整个列表重新推送回工程。
代码示例
下面的脚本演示了如何将文档导入到现有 ArcGIS Pro 工程。 同时还设置了一些默认工程设置并将结果保存到新文件。
import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\blank.aprx")
aprx.importDocument(r"C:\Projects\YosemiteNP\Documents\Yosemite.mxd")
aprx.importDocument(r"C:\Projects\YosemiteNP\Documents\Yosemite_ScenicViews.3dd")
aprx.defaultGeodatabase = r"C:\Projects\YosemiteNP\Data_Vector\YosemiteData.gdb"
aprx.defaultToolbox = r"C:\Projects\YosemiteNP\Analysis\AnalysisTools.tbx"
aprx.saveACopy(r"C:\Projects\YosemiteNP\Yosemite.aprx")下面的脚本使用了关键字 current，因此可从 Python 窗口运行此脚本。 此脚本打印了工程及其图层中每个地图的名称，以及每个布局的名称及其页面大小。
aprx = arcpy.mp.ArcGISProject("CURRENT")
for m in aprx.listMaps():
print("Map: " + m.name)
for lyr in m.listLayers():
print(" " + lyr.name)
print("Layouts:")
for lyt in aprx.listLayouts():
print(f" {lyt.name} ({lyt.pageHeight} x {lyt.pageWidth} {lyt.pageUnits})")下面的脚本使用了关键字 current，因此可从 Python 窗口运行此脚本。 该脚本将复制现有地图、向其添加新图层、设置控制新打开的视图范围的地图默认照相机属性、将地图视图导出为 PDF 并从工程中移除新创建的地图。
aprx = arcpy.mp.ArcGISProject("CURRENT")
#Create a copy of an existing map
existingMap = aprx.listMaps("Yosemite National Park")[0]
rangerMap = aprx.copyItem(existingMap, new_name="Ranger Stations")
#Add ranger stations layer file
lyrx = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LayerFiles\Ranger Stations.lyrx")
rangerMap.addLayer(lyrx)
#Close any current layout or map views
aprx.closeViews("MAPS_AND_LAYOUTS")
#Set the default map camera to the extent of the park boundary before opening the new view
#default camera only affects newly opened views
lyr = rangerMap.listLayers("*Park Boundary")[1]
rangerMap.defaultCamera.setExtent(arcpy.Describe(lyr).extent)
rangerMap.openView()
#export the newly opened active view to PDF, then delete the new map
mv = aprx.activeView
mv.exportToPDF(r"C:\Temp\RangerStations.pdf", width=700, height=500, resolution=96)
aprx.deleteItem(rangerMap)