ArcMap

arcpy.mapping 教程入门

复杂程度：
初级
数据要求：
使用自备的数据

本教程将引导您了解一些非常常见的 arcpy.mapping 工作流，同时还将介绍一些重要概念。目的是为 Python 脚本和 arcpy.mapping 的全新用户提供帮助。这些步骤是通用的，适用于任何数据和许可级别。

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

Python 窗口

要学习 arcpy.mapping，首先应从 Python 窗口着手。Python 窗口是 ArcMap 框架的一部分，它所提供的自动完成功能使您能够轻松读取函数参数的名称和顺序。以下步骤显示了如何设置 Python 窗口，以实现令人满意的最终用户体验并使其与本文档中的屏幕截图一致。

  1. 在 ArcMap 中打开一个新的空地图文档。
  2. 单击地理处理 > Python。

    3. 如果是第一次打开 Python 窗口，它在应用程序中将显示为漂浮状态。接下来的步骤介绍如何停靠 Python 窗口以及修改帮助的放置位置。

  3. 单击 Python 窗口的标题栏，并按住鼠标左键。
  4. 将 Python 窗口拖动至位于 ArcMap 应用程序底部的停靠锚点，然后释放鼠标键。
  5. 在 Python 窗口的代码窗格（具有 >>> 字符）中单击。您会看到一些帮助文本出现在右侧的帮助窗格中。
  6. 右键单击代码窗格并选择帮助放置 > 底部。帮助即会出现在代码窗格的下方。您可能需要调整两个窗格之间的分割器以便有足够的空间来输入代码和查看帮助。
  7. 现在输入以下语句（请注意，Python 区分大小写）：
    8. >>> arcpy.mapping.ExportToPDF(
    Python 窗口应如下图所示。第一个必需参数称为 map_document，处于高亮显示状态。如果输入一个逗号，则第二个参数会变为高亮显示。只有两个必需参数：map_document 和 out_pdf。可选参数使用大括号 {} 括起。
    ExportToPDF 语法的屏幕截图
  8. 右键单击代码窗格，然后单击全部清除以清除代码窗格。

引用现有地图文档

通常，通过 arcpy.mapping 脚本执行的首要操作之一即引用要处理的现有地图文档 (.mxd) 或图层文件 (.lyr)。在本节中，您将了解如何引用地图文档。

引用地图文档的方法有两种。第一种方法是通过提供 .mxd 文件的路径在磁盘上进行引用。如果要构建将在 ArcGIS 环境外部运行的脚本，则必须使用地图文档的路径对其进行引用。第二种方法是引用当前加载至 ArcMap 应用程序中的地图文档（在这种情况下，指的是 untitled.mxd）。在 ArcMap 内的 Python 窗口中进行操作时，引用当前加载的地图文档十分方便，因为在应用程序中可直接看到对地图文档执行的更改。以下步骤将介绍如何引用当前加载至 ArcMap 中的地图文档。

  1. 在 Python 窗口中输入以下内容，完成输入后按 ENTER：
    2. >>> mxd = arcpy.mapping.MapDocument("CURRENT")
    MapDocument 函数为称为 mxd 的变量返回一个 MapDocument 对象参考。字符串 CURRENT 是用于引用当前已加载地图文档的关键字。您也可以在此处提供地图文档的路径来代替 CURRENT。
  2. 在 Python 窗口中，输入以下内容：
    3. >>> mxd.
    输入点之后，您会看到对 MapDocument 对象可用的方法和属性的长列表。
  3. 在 Python 窗口中输入以下内容，完成输入后按 ENTER：
    4. >>> mxd.author = "YOUR NAME GOES HERE"
    将打开 MapDocument 对象具有一个称为 author 的属性。只需将其值设置为字符串即可。
  4. 在 ArcMap 中，单击文件 > 地图文档属性。
    5. 您会看到 author 属性已设置为您的字符串。您只需通过名为 mxd 的变量即可直接与 MapDocument 对象交互。MapDocument 对象还有许多其他方法和属性。现在将保存您的更改。
  5. 完成地图文档属性 对话框后，单击取消。
  6. 在 Python 窗口中输入以下内容，完成输入后按 ENTER：
    7. >>> mxd.save()
    由于该地图文档未保存，因此会出现一个对话框提示您提供路径和文件名。save() 方法不具有任何参数，但由于它是一个方法，因此仍必须加上左、右括号。事实上，您要处理的是已经存在的地图文档，并不需要处理弹出的保存对话框。要验证地图文档的保存位置，请尝试以下操作：
  7. 在 Python 窗口中输入以下内容，完成输入后按 ENTER：
    8. >>> print mxd.filePath
    您会看到代码窗格中会打印出路径：
    Python 窗口中 mxd.filePath 结果的屏幕截图

将图层文件添加到地图文档中

现在您已引用地图文档，接下来要做的是向地图文档中添加图层文件 (.lyr)。此操作可通过 arcpy.mapping AddLayer 函数完成。

  1. 在 Python 窗口中，输入以下内容：
    2. >>> arcpy.mapping.AddLayer(
    Python 窗口中 AddLayer 语法的屏幕捕获
    自动完成功能显示有两个必需参数。第一个参数是对地图文档中数据框的引用。第二个参数是对要添加的图层的引用。该图层可以是地图文档或图层文件中的图层。第三个参数是可选参数，用于控制内容列表中图层的放置。由于这是第一个也是仅有的一个图层，您可以忽略第三个参数并使用其默认值。
    添加该图层之前，您需要引用相应的对象。首先将引用数据框。
  2. 在 Python 窗口中，按 Backspace 移除 AddLayer 函数，输入以下内容，完成输入后按 ENTER：
    3. >>> df = arcpy.mapping.ListDataFrames(mxd, "Layers")[0]
    ListDataFrames 函数需要引用地图文档和通配符过滤器（可选）。您可以提供数据框的全名以进行搜索。还可以输入类似 "lay*" 的内容。
    所有 ArcPy 列表函数将返回 Python 列表对象。在列表中返回的这些项目从零开始，这表示列表中的第一个项目的索引值为 0，第二个项目为 1，依此类推，一直到 n-1。由于要让 df 变量引用 DataFrame 对象而不是 Python 列表对象，因此必须在函数后追加索引号。在函数末尾追加 [0] 会返回列表中的第一个数据框。对于您的情况，将返回列表中仅有的数据框。如果在地图文档中对数据框进行唯一命名并使用相应的通配符值分隔项目，应始终返回仅有一个项目的列表，而索引 [0] 将会起到作用。如果在地图文档中有两个数据框，并且您不想通过 wildcard 值引用第二个数据框，则需要在函数末尾加上 [1]，例如，df2 = arcpy.mapping.ListDataFrames(mxd)[1]。
    接下来您在使用 AddLayer 函数之前需要引用图层文件。引用图层文件的过程与通过提供 .mxd 完整路径引用图层文档的过程相同，所不同的是需使用 Layer 函数而非 MapDocument 函数。
  3. 在 Python 窗口中输入以下内容，完成输入后按 ENTER。您提供的路径很可能与以下示例不同。
    4. >>> lyrFile = arcpy.mapping.Layer(r"C:\Project\data\Rivers.lyr")
    在以上步骤中，创建了对现有图层文件的引用，该引用存储在名为 lyrFile 的变量中。
    请注意，路径字符串的前面有一个小写 r。这是 Python 中的特殊字符，代表 raw。这表示要按原样解释该字符串并忽略字符串中的其他任何特殊字符。之所以要使用小写的 r，是因为路径字符串中含有反斜线。在 Python 中，反斜线也是特殊字符。例如，字符串中的 \t 将转换为制表符，\n 将转换为新行。在以上示例中，您不想使用特殊字符，而想使用原始的文本字符串。还有其他两种等效的方法可用于在 Python 中输入相同的路径。第一种，使用正斜线（例如，“C:/Project/States.lyr”）。Python 不会尝试解释正斜线，而且它们是跨平台标准。第二种，使用双反斜线（例如，“C:\\Project\\Lakes.lyr”）。第一个反斜线抵消了第二个反斜线。记住小写 r 方法很重要，因为在 Windows 平台上复制系统路径时带有反斜线。
    所有必需的变量参考即已创建完毕。接下来将使用 AddLayer 函数将图层文件添加至当前地图文档。
  4. 在 Python 窗口中输入以下内容，完成输入后按 ENTER：
    5. >>> arcpy.mapping.AddLayer(df, lyrFile)
    您的图层应已添加到内容表和数据视图中，Python 窗口应如下图所示：
    Python 窗口中 AddLayer 结果的屏幕截图

将地图文档导出至 PDF

将地图文档导出至 PDF 极其容易，仅需要单行代码。您在教程开始处已看过 ExportToPDF 函数的语法。现在将完成该语法。

  1. 在 Python 窗口中输入以下内容，完成输入后按 ENTER。您提供的路径很可能与以下示例不同。
    2. >>> arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Doc1.pdf")
    有很多参数与 ArcMap 中的设置一致。仅有两个必需参数：map_document 和 out_pdf。
    已在指定位置创建了 PDF 文档，Python 窗口应如下图所示：
    Python 窗口中 ExportToPDF 结果的屏幕截图

使用 ListLayers 函数引用图层，并更改图层属性

有许多属性和方法可用于处理地图文档中的图层。您之前已将图层文件中的图层添加至地图文档。创建的名为 lyrFile 的变量即引用添加至地图文档的图层。使用此变量，可修改已添加图层的某些属性。

  1. 在 Python 窗口中，输入以下内容：
    2. >>> lyrFile.
    输入点之后，请注意 Layer 对象上的所有不同属性和方法。使用 lyrFile 变量，可更改地图文档中的这些属性，在调用 save() 方法时，会将这些更改保存至磁盘上的图层文件 (.lyr)。
    并非所有可能的图层属性都可用于 Layer 对象，只有那些对于地图自动化情景最常见的图层属性才可用。可通过创作图层文件中的属性以及使用 arcpy.mapping UpdateLayer 函数来修改更多属性。
    您不需要总是添加图层文件。大多数情况下，地图文档中已经具有图层。在以下这些步骤中，将假定图层已在地图文档中，再次对其进行引用。在地图文档中引用图层与引用数据框非常相似。
  2. 在 Python 窗口中，按 Backspace 删除当前文本，输入以下内容，然后按 ENTER：
    3. >>> lyr = arcpy.mapping.ListLayers(mxd)[0]
    ListLayers 函数需要您提供地图文档参考。该函数有两个附加参数：一个用于执行通配符搜索，另一个用于指定数据框。由于您只有一个图层和一个数据框，因此不必提供其他参数。同样，语句结尾仍需要加上 [0] 索引值，以便返回 Layer 对象而不是 Python 列表对象。
    使用新的 lyr 变量，可更新某些图层属性。
  3. 在 Python 窗口中输入以下两行，在每行后面按 ENTER：
    4. >>> lyr.name = "Some New Name"
>>> lyr.visible = False
    您不会立即看到更改。不是所有的属性更改或方法都会自动更新应用程序。这是有意设计成这样的，目的在于避免应用程序经常刷新。使用 CURRENT 引用 ArcMap 中当前加载的地图文档时，有时需要刷新内容列表或活动视图（数据视图或布局视图）。
  4. 在 Python 窗口中输入以下两行，在每行后面按 ENTER：
    5. >>> arcpy.RefreshTOC()
>>> arcpy.RefreshActiveView()
    内容列表和数据视图将刷新。
    Python 窗口应如下图所示：
    Python 窗口中刷新结果的屏幕截图

更改数据框范围

在本节中，您将更改数据框范围以使其与所选要素的范围相符。在脚本中，通常使用类似 SelectlayerByAttribute 的函数来完成此操作。为了简化操作，您将以图形的方式选择一些要素。首先需要使用 Python 再次开启图层可见性。

  1. 在 Python 窗口中输入以下三行，在每行后面按 ENTER：
    2. >>> lyr.visible = True
>>> arcpy.RefreshTOC()
>>> arcpy.RefreshActiveView()
  2. 在 ArcMap 中，以图形方式选择图层中的一个或多个要素。
    3. 然后，创建存储所选要素范围的变量，并将该范围应用于所引用的 DataFrame 对象的 extent 参数。
  3. 在 Python 窗口中输入以下两行，在每行后面按 ENTER：
    4. >>> lyrExtent = lyr.getSelectedExtent()
>>> df.extent = lyrExtent
    Python 窗口应如下图所示：
    Python 窗口中 df.extent 结果的屏幕截图

将地图文档（再次）导出至 PDF

将再次导出至 PDF。这次将另外创建一个 PDF 文档，该文档最终将与第一个文档一起追加到新文档中。

  1. 在 Python 窗口中输入以下内容，完成输入后按 ENTER。您提供的路径很可能与以下示例不同。
    2. >>> arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Doc2.pdf")
    Python 窗口应如下图所示：
    Python 窗口中 ExportToPDF 结果的屏幕截图

新建 PDF 文档并追加两页

arcpy.mapping 模块包含一些 PDF 文档管理函数，这对于创建多页文档十分理想。例如，完整的地图册除包含数据驱动页面生成的标准参考地图页面以外，往往还包含一些其他页面。arcpy.mapping 的使用对于构建完整地图册来说是必要的步骤。

教程本部分将模拟多页报告的创建过程。首先要新建一个 PDF 文档，然后追加在先前步骤中创建的 PDF。假设这些 PDF 文档只是构成地图册的单个文档。例如，Doc1.pdf 可以是表示标题页和内容列表等的多页 PDF。第二个 PDF 文档可以是将所有数据驱动页面地图页面导出至单个多页 PDF 的结果。

第一步是新建 PDF 文档。

  1. 在 Python 窗口中输入以下内容，完成输入后按 ENTER：
    2. >>> PDFdoc = arcpy.mapping.PDFDocumentCreate(r"C:\Project\Final.pdf")
    称为 PDFdoc 的变量引用内存中的 PDFDocument 对象。只有在保存并关闭文档后，该变量才会存在于磁盘中。
    下面的步骤将介绍如何追加相应页面。
  2. 在 Python 窗口中输入以下三行，在每行后面按 ENTER：
    3. >>> PDFdoc.appendPages(r"C:\Project\Doc1.pdf")
>>> PDFdoc.appendPages(r"C:\Project\Doc2.pdf")
>>> PDFdoc.saveAndClose()
    前两行分别将每个 PDF 追加至新建的 PDF 文档中。最后一行是提交更改并在磁盘上创建最终 PDF。
    已在指定位置创建了 PDF 文档，Python 窗口应如下图所示：
    Python 窗口中 saveAndClose 结果的屏幕截图

相关主题

arcpy.mapping 简介

arcpy.mapping 指导原则

至此，您已使用 arcpy.mapping 完成了一个十分简单但常用的工作流。接下来的步骤是将这些工作流应用于您自己的地图文档和图层。另外，建议您花费一些时间深入了解一下 arcpy.mapping 帮助主题。每个主题末尾提供了上百种小代码示例，可轻松将其复制并粘贴到 Python 窗口中。还可以在资源中心中搜索 arcpy.mapping，以查找更高级的 arcpy.mapping 应用程序。