描述
用于访问地图文档 (.mxd) 的属性和方法。大多数地图脚本操作都需要引用此对象。
说明
MapDocument 对象通常是最先引用的对象（这些对象是在地图自动化脚本中创建的）之一，因为它是许多 arcpy.mapping 函数的必需参数。通过 MapDocument 对象，基本可以访问地图文档（例如数据框、图层和页面布局要素）中的其他所有对象。通过 MapDocument 对象，可以访问 ArcMap 的地图文档属性对话框（文件 > 地图文档属性）中出现的大多数地图文档属性。此对象还包含了地图文档缩略图的管理方法和地图文档的保存方法，这些方法都位于 ArcMap 的“文件”菜单中。
可以通过两种方法使用 MapDocument 函数创建 MapDocument 对象。第一种，也是首推方法，即提供磁盘上地图文档 (.mxd) 位置的系统路径。该方法最为常用，因为随后可在 ArcGIS 应用程序外部运行脚本。引用磁盘上的特定地图文档这种方法可对脚本执行方式予以更多控制，因为给定脚本在某些地图文档上可能无法正常运行。
第二种方法是将 CURRENT 关键字作为 MapDocument 函数的输入参数。该方法仅适用于 ArcMap 应用程序内部，因为 MapDocument 对象引用当前加载到 ArcMap 应用程序中的地图文档。想要快速测试和了解 Python 窗口内的脚本功能和命令语法时，使用 CURRENT 会很有帮助。您可以从了解 Python 窗口中的语法入手，然后将那些代码行粘贴到保存在磁盘上的更永久的脚本中。
使用 CURRENT 关键字的脚本工具必须在 ArcMap 内运行（从自定义菜单或“目录”窗口）。如果在 ArcCatalog 应用程序内运行使用 CURRENT 的脚本工具，将无法正确执行。出于同样的原因，如果脚本工具含有带 CURRENT 参考的验证脚本，当您尝试从 ArcCatalog 编辑验证脚本时，可能出现错误。确保在 ArcMap 目录窗口内编辑脚本工具的验证代码。
要使用脚本工具中的 CURRENT 关键字，必须禁用后台处理。后台处理会按照在 ArcGIS 外部运行独立脚本的方式运行所有脚本。为此，启用后台处理时，CURRENT 将不可用。有一个新的脚本工具选项称为始终在前台中运行，可确保脚本工具在前台中运行，即使启用了后台处理也是如此。
了解变量如何在脚本环境中引用 MapDocument 对象非常重要，特别是将在新文件中保存结果时。您必须了解，在最初创建引用 MapDocument 对象的变量时，该变量通常指向在硬盘上或目前在内存中（通过 CURRENT）的原始地图文档。在 ArcMap 应用程序中，如果在新文件位置中执行 SaveAs 方法，所有后续更改都直接反映到新文件中。这在脚本环境中并不可行，所以没有提供 saveAs 方法。MapDocument 类具有用于管理地图文档修改的 save 和 saveACopy 方法。
如果在使用 CURRENT 地图文档时通过脚本修改某些地图文档要素的外观（例如，更改图层名称、数据框范围等），地图可能不会随着每行已执行代码自动更新。要刷新地图文档以反映所作更改，请使用 RefreshActiveView 或者 RefreshTOC 函数。这些函数将分别刷新地图显示或页面布局以及内容列表。仅当希望查看更新的应用程序时，才需要使用刷新函数。Arcpy.mapping 导出、保存及打印函数将生成预计更新结果，而无需使用这些函数。
由于用户名和密码信息未保存在图层文件内或地图文档内，所以地图文档或图层文件内的一些图层可能受密码保护。打开包含这些图层的地图文档时将会提示用户输入相应的信息。默认情况下，arcpy.mapping 脚本环境将在执行过程中禁止使用这些对话框，但这意味着这些图层的数据源将被视为已经损坏。换言之，受保护的图层将不会在任何输出中进行渲染。如果希望适当地渲染这些图层，则应采取如下做法。首先，将用户名和密码信息随图层一同保存。其次，CreateDatabaseConnection 地理处理函数允许您创建在内存中持久的连接。如果在使用 MapDocument 函数打开地图文档 (.mxd) 或使用 Layer 函数打开图层文件之前执行此命令，将渲染 SDE 图层。目前尚没有针对受保护的 Web 服务的操作方法。
引用 MapDocument 对象的变量将锁定地图文档文件。最好在脚本结尾或在 try/except 语句中使用 Python del 命令移除地图文档对象的引用。
通常我们需要更改地图文档中的数据源。而 MapDocument 对象中的两种方法可以实现此目的。findAndReplaceWorkspacePaths 方法用于替换图层或表的部分或全部工作空间路径。replaceWorkspaces 方法用于更改路径和工作空间类型。有关详细说明、参数信息、案例和编码示例，请参阅使用 arcpy.mapping 更新和修复数据源帮助主题。
语法
MapDocument (mxd_path)
| 参数 | 说明 | 数据类型 |
mxd_path | 包含现有地图文档 (.mxd) 的完整系统路径和文件名的字符串或包含关键字 CURRENT 的字符串。 | String |
属性
| 属性 | 说明 | 数据类型 |
| activeDataFrame （只读） | 返回表示地图文档 (.mxd) 中当前活动数据框的 DataFrame 对象。即使地图文档处于页面布局视图，activeDataFrame 属性也会将返回相应的数据框。如果要设置活动数据框，则使用 activeView 属性。 | DataFrame |
| activeView （可读写） | 用于获取地图文档的活动视图，或将其设置为单一数据框或页面布局。此属性使用表示活动数据框名称的字符串或 PAGE_LAYOUT 关键字。 如果 activeView 设置为 PAGE_LAYOUT 并且保存地图文档，则下一次打开地图文档时，将以布局模式打开。如果 activeView 设置为数据框名称并且保存地图文档，则下一次打开地图文档时，以数据视图方式打开，并且该特定数据框将成为活动数据框。 | String |
| author （可读写） | 用于获取或设置地图文档的作者信息。 | String |
| credits （可读写） | 用于获取或设置地图文档的制作者名单或版权信息。 | String |
| dataDrivenPages （只读） | 返回可用于在启用了数据驱动页面的地图文档中管理页面的 DataDrivenPages 对象。 | DataDrivenPages |
| dateExported （只读） | 返回报告地图文档最后一次导出日期的 Python datetime 对象。仅当在导出地图后保存了地图文档，此值才是当前值。 | DateTime |
| datePrinted （只读） | 返回报告地图文档最后一次打印日期的 Python datetime 对象。仅当在打印地图后保存了地图文档，此值才是当前值。 | DateTime |
| dateSaved （只读） | 返回报告地图文档最后一次保存日期的 Python datetime 对象。 | DateTime |
| description （可读写） | 用于获取或设置地图文档的描述信息。 | String |
| filePath （只读） | 返回报告完全限定的地图文档路径和文件名的字符串值。 | String |
| hyperlinkBase （可读写） | 用于获取或设置基本路径或 URL，其用于基于字段的文档或 URL 的超链接。 | String |
| isDDPEnabled （只读） | 如果地图文档启用了数据驱动页面，则将返回 True。 | Boolean |
| pageSize （只读） | 用于获取布局的页面大小。返回具有 width 和 height 属性的特定元组。 以下脚本演示了输出地图文档的页面宽度和高度的多种不同方法。 | tuple |
| relativePaths （可读写） | 用于控制地图文档是否存储数据源相对路径。True 值设置相对路径；False 值设置数据源的完整路径。 | Boolean |
| summary （可读写） | 用于获取或设置地图文档的摘要信息。 | String |
| tags （可读写） | 用于获取或设置地图文档的标签信息。用单个逗号 (,) 分隔标签。 | String |
| title （可读写） | 用于获取或设置地图文档的标题信息。 | String |
方法概述
| 方法 | 说明 |
| deleteThumbnail () | 删除地图文档 (.mxd) 的缩略图 |
| findAndReplaceWorkspacePaths (find_workspace_path, replace_workspace_path, {validate}) | Finds old workspace paths and replaces them with new paths for all layers and tables in a map document (.mxd) |
| makeThumbnail () | 创建地图文档 (.mxd) 的缩略图 |
| replaceWorkspaces (old_workspace_path, old_workspace_type, new_workspace_path, new_workspace_type, {validate}) | 对于地图文档 (.mxd) 中的所有图层和表格，将旧的工作空间替换为新的工作空间；同时提供切换工作空间类型的功能（例如，将文件地理数据库数据源替换为 SDE 数据源）。 |
| save () | 保存地图文档 (.mxd) |
| saveACopy (file_name, {version}) | 可选择将地图文档 (.mxd) 保存为新文件或较早版本。 |
方法
deleteThumbnail ()
这将执行与在 ArcMap 中单击文件 > 地图文档属性对话框上的删除缩略图按钮相同的操作。
findAndReplaceWorkspacePaths (find_workspace_path, replace_workspace_path, {validate})| 参数 | 说明 | 数据类型 |
find_workspace_path | A string that represents the workspace path or connection file you want to find. If an empty string is passed, then all workspace paths will be replaced with the replace_workspace_path, depending on the value of the validate parameter. | String |
replace_workspace_path | A string that represents the workspace path or connection file you want to use to replace. | String |
validate | If set to True, a workspace will only be updated if the replace_workspace_path value is a valid workspace. If it is not valid, the workspace will not be replaced. If set to False, the method will set all workspaces to match the replace_workspace_path, regardless of a valid match. In this case, if a match does not exist, then the layer and table's data sources would be broken. (默认值为 True) | Boolean |
For more detailed discussion, parameter information, scenarios, and code samples, please refer to the Updating and Fixing Data Sources with arcpy.mapping help topic.
makeThumbnail ()
这将执行与在 ArcMap 中单击文件 > 地图文档属性对话框上的创建缩略图按钮相同的操作。
replaceWorkspaces (old_workspace_path, old_workspace_type, new_workspace_path, new_workspace_type, {validate})| 参数 | 说明 | 数据类型 |
old_workspace_path | 用于表示要查找的工作空间路径或连接文件的字符串。如果传递了空字符串，则将根据 validate 参数的值将所有工作空间路径替换为 new_workspace_path。 | String |
old_workspace_type | 用于表示要替换的旧数据的工作空间类型的字符串关键字。如果传递了空字符串，则将多个工作空间重定向到一个工作空间中。
| String |
new_workspace_path | 用于表示新工作空间路径或连接文件的字符串。 | String |
new_workspace_type | 用于表示将替换 old_workspace_type 的工作空间类型的字符串关键字。
| String |
validate | 如果设置为 True，则仅在 new_workspace_path 值为有效工作空间时，才会更新工作空间。如果为无效工作空间，则不会替换该工作空间。如果设置为 False，则无论匹配是否有效，此方法都会将所有工作空间设置为匹配 new_workspace_path。在这种情况下，如果匹配不存在，则将损坏数据源。 (默认值为 True) | Boolean |
有关详细说明、参数信息、案例和编码示例，请参阅使用 arcpy.mapping 更新和修复数据源帮助主题。
save ()
此函数的作用与 ArcMap 中的文件 > 保存操作结果相同。
saveACopy (file_name, {version})| 参数 | 说明 | 数据类型 |
file_name | 包含输出地图文档 (.mxd) 的位置和名称的字符串。 | String |
version | 用于设置输出版本号的字符串。默认值将使用当前版本。
(默认值为 None) | String |
此函数的作用与 ArcMap 中的文件 > 保存副本操作结果相同。早期版本的软件中不支持的功能将从新保存的地图文档中移除。在独立脚本中调用 saveACopy 时，将不会移除文档冗余。这是因为如果从应用程序中运行独立 Python 脚本，则该脚本将采用不同方式来访问地图文档。
代码示例
MapDocument 示例 1
以下脚本为地图文档中的每个数据框分别创建 MXD 文件。输出地图文档将采用数据查看的模式保存，这样，在打开每个地图文档时，相应数据框将成为活动数据框。此脚本也设置了各输出地图文档的标题属性。由于此脚本使用地图文档的系统路径，它可以在 ArcMap 应用程序外运行。注意：Python 字符串不能以反斜线结尾，即使字符串前面是 r。必须使用双反斜线。在文件夹路径中追加动态文件名时，此点尤为重要。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for df in arcpy.mapping.ListDataFrames(mxd):
mxd.activeView = df.name
mxd.title = df.name
mxd.saveACopy(r"C:\Project\Output\\" + df.name + ".mxd")
del mxd
MapDocument 示例 2
以下脚本演示了如何在 Python 窗口中使用 CURRENT 关键字。此示例将更新首个数据框的名称并刷新内容列表，这样，可以在应用程序中看到更新。将以下代码粘贴到 Python 窗口中的新 ArcMap 文档中。
mxd = arcpy.mapping.MapDocument("CURRENT")
arcpy.mapping.ListDataFrames(mxd)[0].name = "New Data Frame Name"
arcpy.RefreshTOC()
del mxd
>>> mxd = arcpy.mapping.MapDocument("CURRENT")
... arcpy.mapping.ListDataFrames(mxd)[0].name = "New Data Frame Name"
... arcpy.RefreshTOC()
... del mxd
...
MapDocument 示例 3
以下是演示如何在 Python 窗口中使用 CURRENT 关键字的另一简单脚本。各图层名称都将在 Python 窗口中输出。如果缩进正确，也可能发生循环。与上例相似，将以下代码粘贴到 Python 窗口中。
mxd = arcpy.mapping.MapDocument("CURRENT")
for lyr in arcpy.mapping.ListLayers(mxd):
print lyr.name
del mxd
>>> mxd = arcpy.mapping.MapDocument("CURRENT")
... for lyr in arcpy.mapping.ListLayers(mxd):
... print lyr.name
... del mxd
...
MapDocument 示例 4
以下脚本将在打开需要输入密码的地图文档前，通过在内存中创建 SDE 连接确保适当地渲染受保护图层。此脚本仅定义了连接信息，然后将地图文档导出为 PDF 文件。最好在关闭脚本前从内存中删除此引用。
import arcpy, os
#Remove temporary connection file if it already exists
sdeFile = r"C:\Project\Output\TempSDEConnectionFile.sde"
if os.path.exists(sdeFile):
os.remove(sdeFile)
#Create temporary connection file in memory
arcpy.CreateArcSDEConnectionFile_management(r"C:\Project\Output", "TempConnection", "myServerName", "5151", "myDatabase", "DATABASE_AUTH", "myUserName", "myPassword", "SAVE_USERNAME", "myUser.DEFAULT", "SAVE_VERSION")
#Export a map document to verify that secured layers are present
mxd = arcpy.mapping.MapDocument(r"C:\Project\SDEdata.mxd")
arcpy.mapping.ExportToPDF(mxd, r"C:\Project\output\SDEdata.pdf")
os.remove(sdeFile)
del mxd