教程：arcpy.mp 入门—ArcGIS Pro

本教程将引导您了解常见制图模块工作流并介绍一些重要概念。其目的在于帮助初识 Python 脚本和 arcpy.mp 模块但基本了解 ArcGIS Pro 的用户。本教程中的步骤适用于任何数据及所有许可级别。

在本教程中，您将学习如何执行以下操作：

引用工程，更改其默认地理数据库并保存。
引用地图并添加图层文件 (*.lyrx)。
引用布局并修改文本元素字符串。
在布局中引用地图框并将其范围更改为所添加图层的范围。
将布局导出为 PDF。
将代码保存到 Python 文件 (*.py)。

预计时间：60 分钟

注：

以下步骤从总体上概括了制图模块。在本教程中，提供了许多具体帮助主题的链接，对涉及到的概念给出了详细解释。而且，这些主题基本上都附有示例代码片段。

创建简单工程

要开始编写 arcpy.mp 代码，需要创建包含单一地图的简单工程以及包含地图框和文本元素的布局。

打开新的空白工程。
在插入选项卡的工程组中，单击新建地图下拉菜单，然后选择新建地图。
将新地图命名为教程地图。
稍后将在教程中引用使用此名称的地图以添加图层文件。
在插入选项卡上，单击新建布局并从图库中选择布局。
将新布局命名为教程布局。
稍后将在教程中引用使用此名称的布局以修改布局元素并将布局导出为 PDF。
在插入选项卡的地图框组中，选择地图框下拉菜单，然后选择包含范围和相关比例的地图框并将其添加到布局。
将新地图框元素命名为教程地图的地图框。
稍后将在教程中引用使用此名称的地图框以修改其范围。
在插入选项卡的图形与文本组中，选择工具库中的平直文本控件并在布局上插入文本元素。
原样保留默认字符串值和文本大小；稍后将通过代码对其进行修改。
将新文本元素命名为标题。
稍后将在教程中引用使用此名称的文本元素以修改其文本字符串。
在工程选项卡上，单击保存。
根据工程的创建方式，您可能需要将其保存到某个位置。

使用 Python 窗口

您可以在 Python 窗口中开始学习 arcpy.mp。这允许您执行基于 Python 的小型工作流，并且在大型脚本中进行细化之前可使您直接了解应用程序中的概念。 Python 窗口是 ArcGIS Pro 应用程序的一部分，它提供了自动完成和命令语法，以供您按正确顺序快速输入相应的参数信息。有关详细信息，请查看 Python 窗口帮助主题。

在视图选项卡上，单击 Python 窗口。
如果这是您首次打开 Python 窗口，则该窗口可能停靠在应用程序底部。将该窗口保持停靠在此位置或将其停靠在您更喜欢的位置。
Python 窗口包含提示和脚本部分。提示位于编写和输入代码的窗口的底部。脚本位于提示上方，用于记录之前输入的 Python 代码。
在提示部分中单击显示在此输入 Python 代码的位置。
随即将显示闪烁的指针，可在此处输入代码。

注：

本教程是根据通过单一命令提示符使用 Python 窗口的情况编写的。还可以使用应用程序中的 Python 笔记本选项，但要知道需要从单一单元运行代码才能模拟教程步骤。要打开 Python 笔记本，请选择分析选项卡，单击 Python 下拉菜单，然后选择 Python 笔记本。有关详细信息，请参阅 ArcGIS Pro 中的笔记本帮助主题。

引用现有工程

通常，通过 arcpy.mp 脚本执行的前几个操作之一是引用要处理的现有工程 (.aprx) 或图层文件（.lyrx 或 .lyr）。在此部分中，您将引用工程。

引用工程的方法有两种。第一种方法是通过提供 .aprx 文件的路径在磁盘上进行引用。如果要构建将在 ArcGIS 环境外部运行的脚本，则必须使用工程的完整系统路径才能对其进行引用。第二种方法是引用当前加载到 ArcGIS Pro 中的工程。在 Python 窗口中进行操作时，引用当前加载的工程十分方便，因为在应用程序中可直接看到对其执行的更改。以下步骤将介绍如何引用当前加载至 ArcGIS Pro 中的工程。

在 Python 窗口中，输入以下代码行，然后按 Enter 键。
```
aprx = arcpy.mp.ArcGISProject("CURRENT")
```
上述 ArcGISProject 函数为称为 aprx 的变量返回一个 ArcGISProject 对象参考。切记 Python 变量名称、函数和属性均区分大小写。 CURRENT 字符串是用于引用当前已加载工程的关键字。同样，如果您想要在应用程序外部运行脚本，则需要改为提供工程文本的完整路径。
在 Python 窗口中，输入以下内容：
```
aprx.
```
在输入点之后，即会显示适用于 ArcGISProject 对象的方法和属性的长列表。

注：

按照以下步骤找到可用于设置为默认地理数据库的现有地理数据库。

在 Python 窗口中，继续输入以下内容，然后按 Enter 键。提供现有地理数据库的专用路径。
```
aprx.defaultGeodatabase = r"path to a geodatabase"
```
例如，键入：
aprx.defaultGeodatabase = r"C:\Projects\YosemiteNP\Data\Yosemite.gdb"
在创建新工程时，其默认地理数据库将被设置为空地理数据库（名称与工程名称相同）且存放在同一文件夹位置中。 defaultGeodatabase 属性用于获取或设置默认地理数据库。在此示例中，该属性被修改为引用包含数据的地理数据库。
注：
请注意，路径字符串的前面有一个小写 r。这是 Python 中的特殊字符，代表 raw。这表示要按原样解释该字符串并忽略字符串中的其他任何特殊字符。之所以要使用小写的 r，是因为路径字符串中含有反斜线。 Python 中的反斜线是特殊的转义字符。例如，字符串中的 \t 将转换为制表符，且 \n 将转换为新行。在以上示例中，您不想解释特殊字符，因为它可能将路径呈现为无效；您想要原始的文本字符串。还有其他两种等效的方法可用于在 Python 中输入相同的路径。首先，使用正斜线（例如 "C:/Projects/YosemiteNP/Data/Yosemite.gdb"）。Python 非常适合于正斜线搭配使用；它们是跨平台标准。其次，使用双反斜线（例如，"C:\\Projects\\YosemiteNP\\Data\\Yosemite.gdb"）。第一个反斜线会转义第二个反斜线。切记小写 r 方法很重要，因为在 Windows 平台上使用复制为路径命令复制系统路径时，将包括反斜线以添加 r，而无需修改反斜线。
要查看对工程做出的更改，请单击工程选项卡，然后选择选项。
当前设置面板显示之前对默认地理数据库设置进行的更改。
单击取消。
另一种验证默认地理数据库的方式是在目录窗格中展开数据库连接。将列出新地理数据库，并且该数据库旁会显示主页按钮。
在 Python 窗口中，输入以下内容，然后按 Enter 键：
```
aprx.save()
```
save() 方法不含任何参数，但由于它是一种方法，因此必须包含括号。现在确认路径是否正确。检查工程文件上的时间戳是否更新为当前日期和时间。
注：
如果您不想将更改直接保存到当前工程，您可以使用 aprx.saveACopy(file_name) 方法将更改保存到新位置，但是您的 Python 变量将继续引用当前工程。
在 Python 窗口中，输入以下内容，然后按 Enter 键：
```
print(aprx.filePath)
```
将工程路径输出到脚本。

将图层文件添加到地图

此时，您已引用了工程，接下来需要可将图层文件（.lyr 或 .lyrx）添加到之前添加的地图。

注：

对于以下步骤，创建或找到仅包含一个图层的矢量图层文件。

在 Python 窗口中，输入以下内容，然后按 Enter 键：
```
m = aprx.listMaps("Tutorial Map")[0]
```
所有 arcpy 列表函数将返回 Python 列表对象。在列表中返回的这些项从零开始，这表示列表中的第一个项的索引值为 0，第二个项为 1，依此类推，一直到 n-1。由于要让 m 变量引用 Map 对象而不是 Python 列表对象，因此必须在函数后追加索引号。在函数末尾追加 [0] 会返回列表中的第一个地图。在此案例中，该地图应该是列表中的唯一地图，因为您同时提供了地图的唯一名称作为 wildcard 参数。如果您为工程中地图的命名是唯一的并且使用适当的 wildcard 值隔离项目，将显示仅包含一个项目的列表，索引 [0] 将生效。
在 Python 窗口中，输入以下内容：
```
m.
```
在输入点之后，这次会显示适用于 Map 对象的方法和属性的长列表。
在使用 Map 对象上的 addLayer 方法之前，必须引用一个图层文件。引用图层文件与引用工程的过程相同，但使用的是 LayerFile 方法。
在 Python 窗口中，按 Backspace 键移除 m. 或之前输入的所有其他内容，输入以下内容，然后按 Enter 键：
```
lyrFile = arcpy.mp.LayerFile(r"path to a layer file")
```
例如，键入：
lyrFile = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LYRS\Boundary.lyrx")
在以上步骤中，创建了对现有图层文件的引用，该引用存储在名为 lyrFile 的变量中。
在 Python 窗口中，输入以下内容：
```
lyr = m.addLayer(
```
“自动完成”显示需要一个名为 add_layer_or_layerfile 的必填参数和一个名为 add_position 的选填参数（以 { } 括号括起）。第一个参数可引用工程或图层文件中的现有图层。第二个参数是可选参数，用于控制内容窗格中图层的放置。
在 Python 窗口中，输入以下内容，然后按 Enter 键：
```
lyr = m.addLayer(lyrFile)[0]
```
图层随即添加到地图中并在 lyr 变量中引用，该图层使用默认 add_position。
图层文件可以包含一个或多个图层。因此，addLayer 方法会返回图层的 Python 列表，即使仅存在一个图层也是如此。要引用特定 Layer 对象，需要一个索引编号。索引值 [0] 将返回第一个图层。

修改现有布局元素

布局上的所有元素可以使用 Layout 对象上的 listElements 方法进行引用。属性和方法集合将有所不同，具体取决于元素类型。在此部分中，您将先更新与文本元素关联的字符串，然后根据之前添加的图层的范围更改地图框元素的范围。

在 Python 窗口中，输入以下内容，然后按 Enter 键：
```
lyt = aprx.listLayouts("Tutorial Layout")[0]
```
上述代码使用与引用地图相同的逻辑，但是使用 ArcGISProject 对象上的 listLayouts 方法。
在通过 lyt 变量引用 Layout 对象后，您可以在布局中引用这些元素。
在 Python 窗口中，输入以下内容，然后按 Enter 键：
```
title = lyt.listElements("TEXT_ELEMENT", "Title")[0]
```
同样，所有 arcpy 列表函数会返回 Python 列表对象，因此必须包含索引编号。 listElements 方法采用两个可选参数帮助过滤结果列表。第一个参数称为 element_type，它仅从常量列表获取值。在此情况下，该参数使用 TEXT_ELEMENT。第二个参数称为 wildcard，工作原理与先前列表函数相似。如果您之前以适当方式命名文本元素，您将正确引用该元素并且仅引用文本元素。
在通过 title 变量引用文本元素后，您可以修改其文本字符串并更改其文本大小。
在 Python 窗口中，输入以下内容，然后在每行后按 Enter 键：
```
title.text = "My first arcpy.mp title"
title.textSize = 36
```
需要在布局中更新文本。如果当前值不适用于字符串，则可以再次更改文本大小。
使用与上述类似的方法，您现在将在布局上引用地图框。
在 Python 窗口中，输入以下内容，然后按 Enter 键：
```
mf = lyt.listElements("MapFrame_Element", "*frame")[0]
```
上述代码还使用 listElements 函数，但是注意几个语法用例。首先，注意 element_type 字符串采用混合大小写。常量列表中的大多数 arcpy 关键字不区分大小写。其次，注意 wildcard 参数中使用的特殊通配符 "*"。如果使用了通配符，则整个字符串不区分大小写；否则，字符串必须与大小写完全匹配。在此示例中，mf 变量将正确引用名为 Tutorial Map MapFrame 的地图框，因为名称末尾为 frame。可通过各种方式使用通配符。
在引用图层和地图框元素后，可以使用基于图层的范围修改其范围。
在 Python 窗口中，输入以下代码，然后在每行后按 Enter 键：
```
ext = mf.getLayerExtent(layer = lyr, selection_only = False)
mf.camera.setExtent(ext)
mf.camera.scale = mf.camera.scale * 1.1
```
第一行使用 MapFrameElement 对象上的 getLayerExtent 方法。第一个参数为图层引用，第二个参数用于确定范围是基于所有要素还是仅基于选定要素。第二行用于将地图框范围设置为从第一行返回的范围对象。最后一行用于将比例修改 10%，以防要素紧挨着地图框的边。

将布局导出为 PDF

要将布局导出为 PDF，需要几行代码。必须创建要生成的导出格式，然后再将布局导出为该格式。要导出的布局已通过变量 lyt 引用。

在 Python 窗口中，输入以下内容，然后在每行后按 Enter 键：
```
pdf = arcpy.mp.CreateExportFormat("PDF", r"C:\Temp\Yosemite.pdf")
lyt.export(pdf)
```
CreateExportFormat 函数上的第一个参数称为 format，并且支持 11 种文件格式选项。第二个参数用于指定导出位置。
将在您所设置的位置生成文件。

将代码保存到 Python 文件

可以将在 Python 窗口脚本窗格中显示的所有内容保存到 Python 文件 (*.py)。如果您对之前尝试的代码满意并想要保存该代码，则这可能真的很有用。不足之处在于它用时包含所有拼写错误以及可能因错误而抛出错误的代码行。可能需要将这些行从结果中移除。

在 Python 窗口中，单击脚本窗格，右键单击并选择 Save Transcript。
浏览至某个位置将文件另存为 ArcPyMP_Tutorial.py。
可以在 Visual Studio Code、PyCharm、Notepad ++ 等集成开发环境 (IDE) 中打开 Python 文件。如果 Python 已随 ArcGIS Pro 安装，则您具有名为 IDLE 的 IDE。以下步骤假设可以在快捷菜单中找到 IDLE；否则，您必须使用 IDE 打开该文件。
在 File Explorer 中，右键单击该文件，然后在快捷菜单中选择使用 IDLE 编辑 (ArcGIS Pro)。

如果整个过程中没有出现错误，则 Python 文件的内容将如下所示。第一行是在导出至 Python 文件时自动插入的。

# coding: utf-8
aprx = arcpy.mp.ArcGISProject("CURRENT")
aprx.defaultGeodatabase = r"C:\Projects\YosemiteNP\Data\Yosemite.gdb"
aprx.save()
print(aprx.filePath)
# C:/Temp/Tutorial/Turorial.aprx
m = aprx.listMaps("Tutorial Map")[0]
lyrFile = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LYRS\Boundary.lyrx")
lyr = m.addLayer(lyrFile)[0]
lyt = aprx.listLayouts("Tutorial Layout")[0]
title = lyt.listElements("TEXT_ELEMENT", "Title")[0]
title.text = "My first arcpy.mp title"
mf = lyt.listElements("MapFrame_Element", "*frame")[0]
ext = mf.getLayerExtent(layer = lyr, selection_only = False)
mf.camera.setExtent(ext)
mf.camera.scale = mf.camera.scale * 1.1
pdf = arcpy.mp.CreateExportFormat("PDF", r"C:\Temp\Yosemite.pdf")
lyt.export(pdf)

本教程介绍了如何使用制图模块完成常见工作流。下一步是将这些基本工作流应用于工程、地图、图层等。 arcpy.mp 模块包含超过 60 个对象和类类型，每个类型具有一系列的唯一属性和方法。类帮助主题包含多个代码示例，用于帮助您编写提高工作效率的自动化脚本。

注：