Layer (arcpy.mapping)
摘要
用于对图层的属性和方法进行访问。它可以引用地图文档 (.mxd) 或图层 (.lyr) 文件中的图层。
讨论
对于管理地图文档 (.mxd) 或图层 (.lyr) 文件中的图层来说，图层对象是必不可少的。图层对象提供了对 ArcMap 图层属性对话框中出现的众多常用图层属性的访问，同时也提供了用于保存图层文件的各种方法。Legend 对象中的 Layer 函数、ListLayers 函数和 listLegendItemLayers 方法都提供了引用 Layer 对象的方法。
图层类型千差万别，所支持的属性集也并不都一样。例如，要素图层支持定义查询，而栅格图层不支持，但栅格目录支持。supports 一种方法可用于帮助识别图层类型与图层属性之间的支持关系，从而无需在各种不同的图层对象中查找所有可能的图层类型与属性的组合。如果不知道图层类型是否支持该属性，在试图获取或设置其属性值之前，supports 方法可用于测试该图层是否支持这一属性，从而可减少不必要的错误信息。
地图文档中存在三大类图层：要素图层、图层组和栅格图层。通过 isFeatureLayer、isGroupLayer 和 isRasterLayer 属性，您可以标识或分离出主要的图层类型，但并非全部。还有少数专题图层和数据集并不属于这三种类别：注记子类、尺寸要素、网络数据集、terrain 数据集、拓扑数据集等。这种情况下，对所关注的图层执行操作前，您需要先测试其他属性以分离该图层。
并非所有的图层属性都可通过 Layer 对象进行访问。ArcMap 图层属性对话框中所列属性中有许多并未提供给 arcpy 脚本环境（例如，显示属性、字段别名、选择内容的符号系统等）。通过 UpdateLayer 函数，您可以使用包含自定义信息的图层文件 (.lyr) 替换 ArcMap 图层属性对话框中列出的所有图层属性。
图层组和其他子图层（例如，注记类）将被视为普通图层。ListLayers 函数将返回按图层在内容列表中的显示顺序或在图层 (.lyr) 文件中的显示顺序从上至下生成的索引值。以上规则也适用于嵌套的图层组。例如，如果地图文档中包含一个内含三个子图层的图层组，则它将返回一个包含四个图层名的列表，图层组的名称作为第一项，子图层的名称依次为第二、第三、第四项。有两种方式用于确定某个图层是否为图层组。第一种方式，可以查看该图层是否支持 isGroupLayer 属性。第二种方式，可以评估 longName 属性。图层的 longName 属性值除了图层名称外还包括组名称。例如，在一个名称为 Group1 的图层组中，名称为 Layer1 的图层的 longName 值是 Group1\Layer1。如果 name 值与 longName 的值相同，则表示该图层不是图层组或该图层不在图层组内。
由于用户名和密码信息未保存在图层文件内或地图文档内，所以地图文档或图层文件内的一些图层可能受密码保护。打开包含这些图层的地图文档时将会提示用户输入相应的信息。默认情况下，arcpy.mapping 脚本环境将在执行过程中禁止使用这些对话框，但这意味着这些图层的数据源将被视为已经损坏。换言之，受保护的图层将不会在任何输出中进行渲染。如果希望适当地渲染这些图层，则应采取如下做法。首先，将用户名和密码信息随图层一同保存。其次，使用 CreateArcSDEConnectionFile 地理处理函数创建一个同样保留在内存中的连接文件。如果在使用 MapDocument 函数打开地图文档 (.mxd) 或使用 Layer 函数打开图层文件之前执行此函数，那么 SDE 图层将得到渲染。目前尚没有针对受保护 Web 服务的操作方法。
引用磁盘上的图层文件 (.lyr) 的变量将锁定该文件。最好在脚本结尾或在 Python try/except 语句中使用 Python del 命令移除对象引用。
通常会需要您更改图层的数据源。Layer 对象中有两种方法可以实现此目的。findAndReplaceWorkspacePath 方法用于替换部分或全部的图层工作空间路径。replaceDataSource 方法用于更改图层的工作空间或源数据集。有关详细说明、参数信息、案例和编码示例，请参阅使用 arcpy.mapping 更新和修复数据源帮助主题。
根据符号系统的类型，您可以修改图层的符号系统。只有极少数受支持的符号系统类型，其属性和方法可供使用。最好先测试图层的 symbologyType 属性。如果返回 OTHER 值，则不可以修改图层的符号系统。如果返回值不是 OTHER，则图层的 symbology 属性将返回以下某个符号系统类，每个符号系统类都包含一组特有的方法和属性：GraduatedColorsSymbology、GraduatedSymbolsSymbology、RasterClassifiedSymbology 和 UniqueValuesSymbology。
可以对启用时间的图层执行时间管理操作。并非所有的图层类型都支持时间属性。因此，最好首先使用 supports 方法测试图层是否支持时间。如果图层支持时间，则可从 LayerTime 类访问时间属性。
语法
| 参数 | 说明 | 数据类型 |
lyr_file_path |
A string that includes the full path and file name of an existing layer (.lyr) file. | String |
属性
| 属性 | 说明 | 数据类型 |
| brightness (读写) |
用于获取或设置亮度值。默认的正常亮度是 0%。输入 +100% 和 -100% 之间的任意值。在值的左侧输入正号或负号来指定值是大于 0 还是小于 0。并非所有图层都支持 brightness 属性（例如，图层组和要素图层），因此较好的做法是使用 supports 方法预先进行测试。 | Integer |
| contrast (读写) |
用于获取或设置对比度值。默认的中性对比度是 0%。输入 +100% 和 -100% 之间的任意值。在值的左侧输入正号或负号来指定值是大于 0 还是小于 0。并非所有图层都支持 contrast 属性（例如，注记图层和结构图层），因此较好的做法是使用 supports 方法预先进行测试。 | Integer |
| credits (读写) |
用于获取或设置图层的制作者名单或版权信息。 | String |
| datasetName (只读) |
以图层数据集在工作空间（非 TOC）中显示的方式返回其名称。并非所有图层都支持 datasetName 属性（例如，Web 服务），因此较好的做法是使用 supports 方法预先进行测试。 | String |
| dataSource (只读) |
返回图层数据源的完整路径。包括 workspacePath 和 datasetName 属性的组合。并非所有图层都支持 dataSource 属性（例如，注记类和 Web 服务），因此较好的做法是使用 supports 方法预先进行测试。 | String |
| definitionQuery (读写) |
用于获取或设置图层的定义查询。并非所有图层都支持 definitionQuery 属性（例如，栅格图层和图层组），因此较好的做法是使用 supports 方法预先进行测试。 | String |
| description (读写) |
用于获取或设置图层的描述信息。并非所有图层都支持 description 属性（例如，拓扑图层），因此较好的做法是使用 supports 方法预先进行测试。 | String |
| isBroken (只读) | 如果图层的数据源损坏，则返回 True。 | Boolean |
| isFeatureLayer (只读) | 如果图层是要素图层，则返回 True。 | Boolean |
| isGroupLayer (只读) | 如果图层是图层组，则返回 True。 | Boolean |
| isNetworkAnalystLayer (只读) | 如果图层是 ArcGIS Network Analyst 扩展模块 图层类型，则返回 True。 | Boolean |
| isRasterizingLayer (只读) | 如果当打印或导出地图时，图层导致数据框中其他矢量图层的栅格化，则返回 True。输出过程中的矢量图层栅格化在使用了图层透明度时最易于发生，但当图层具有基于栅格的图片符号或基于字段的透明度时也可发生此现象。 | Boolean |
| isRasterLayer (只读) | 如果图层是栅格图层，则返回 True。 | Boolean |
| isServiceLayer (只读) | 如果图层是 GIS 服务图层，则返回 True。GIS 服务是自动化的地理信息服务，可以使用标准技术和协议在 Web 上对其进行发布和访问。 | Boolean |
| labelClasses (读写) |
通过返回 LabelClass 对象的列表，提供对图层的标注类属性的访问。各个 LabelClass 对象属性可被读取和修改以及写回到图层。并非所有图层都支持 labelClasses 属性（例如，栅格图层和注记图层），因此较好的做法是使用 supports 方法预先进行测试。 | LabelClass |
| longName (只读) |
当试图确定图层是否属于图层组时，此属性是十分有用。如果图层不属于图层组，则长名称等于图层名称。如果图层属于图层组，则图层组结构将包含在长名称中。例如，与另一图层组一同嵌套在某个图层组中的图层名称可能为 Group1\Group2\LayerName。所有图层类型都支持此属性。 | String |
| maxScale (读写) |
用于设置或获取图层的最大比例阈值。 | Double |
| minScale (读写) |
用于设置或获取图层的最小比例阈值。 | Double |
| name (读写) |
用于以图层在 ArcMap 内容列表中显示的方式设置或获取图层名称。可包含空格。所有图层类型都支持此属性。 | String |
| serviceProperties (只读) |
提供对 ArcSDE 和 web 服务图层的连接信息的访问。返回的结果是字典键值对。根据图层类型，会返回两种不同的字典。第一种针对 ArcSDE 连接，第二种针对所有 Web 服务图层类型。Web 服务字典包含可用于所有服务图层类型的键，也包含仅用于特定 Web 服务类型（例如，WMS 具有称作 WMSTitle 的键）的特定键。既可在评估特定键之前用脚本检查 ServiceType 键，也可使用 get 方法绕过不可用的键。并非所有图层都支持 serviceProperties 属性（例如，除 ArcSDE 或 Web 服务图层以外的图层），因此较好的做法是使用 supports 方法预先进行测试。 ArcSDE 字典的键
Web 服务字典的键
| Dictionary |
| showLabels (读写) |
控制图层标注的显示。如果设置为 True，则显示标注；如果设置为 False，则不会绘制标注。并非所有图层都支持 showLabels 属性（例如，栅格图层和注记图层），因此较好的做法是使用 supports 方法预先进行测试。支持 showLabels 属性的图层类型也支持 labelClasses 属性。 | Boolean |
| symbology (只读) | 返回对图层符号系统类的引用。每个受支持的图层符号系统类有自己唯一的属性集。在尝试修改符号系统类属性前，最好首先确定图层的 symbologyType。 | Object |
| symbologyType (只读) | 返回表示图层的符号系统类类型的字符串。并非所有图层符号系统类类型均受支持，对于那些不受支持的类型，返回关键字 OTHER。以下是可能值列表：
| Object |
| time (只读) |
返回 LayerTime 类，此类用于访问已启用时间的图层的时间属性。 | Object |
| transparency (读写) |
用于获取或设置透明度值。这使您可以透过一个图层看到下方的图层。如果不想使图层透明，则输入 0。大于 90% 的透明度值经常导致图层几乎未被绘制。并非所有图层都支持 transparency 属性（例如，结构图层组和 Web 服务子图层），因此较好的做法是使用 supports 方法预先进行测试。 | Integer |
| visible (读写) |
控制图层的显示。这与选中 ArcMap 的内容列表中图层旁边的复选框具有相同的效果。如果设置为 True，则绘制图层；如果设置为 False，则不绘制图层。并非所有图层都支持 visible 属性（例如，被限制的 Web 服务图层），因此较好的做法是使用 supports 方法预先进行测试。 | Boolean |
| workspacePath (只读) |
返回图层的工作空间或连接文件的路径。并非所有图层都支持 workspacePath 属性（例如，Web 服务），因此较好的做法是使用 supports 方法预先进行测试。 | String |
方法概述
| 方法 | 说明 |
| findAndReplaceWorkspacePath (find_workspace_path, replace_workspace_path, {validate}) |
查找图层的工作空间路径并替换为新工作空间路径。 |
| getExtent ({symbolized_extent}) |
Returns a layer's geometric or symbolized extent. |
| getSelectedExtent ({symbolized_extent}) |
Returns a layer's geometric or symbolized extent for selected features. |
| replaceDataSource (workspace_path, workspace_type, {dataset_name}, {validate}) |
为地图文档 (.mxd) 或图层 (.lyr) 文件中的图层替换数据源。其提供转换工作空间类型的能力（例如，用 SDE 数据源替换文件地理数据库数据源）。 |
| save () |
Saves a layer (.lyr) file. |
| saveACopy (file_name, {version}) |
将图层 (.lyr) 文件另存为其他文件名称，或较早版本。 |
| supports (layer_property) |
并非所有图层都支持相同的属性集。supports 属性可用来测试图层支持的属性。 |
方法
| 参数 | 说明 | 数据类型 |
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 parameter 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 replace. | String |
validate | If set to True, the 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 the workspace to match the replace_workspace_path, regardless of a valid match. In this case, if a match does not exist, then the layer's data source would be broken. (默认值为 True) | Boolean |
有关详细说明、参数信息、案例和编码示例，请参阅使用 arcpy.mapping 更新和修复数据源帮助主题。
| 参数 | 说明 | 数据类型 |
symbolized_extent |
A value of True will return the layer's symbolized extent; otherwise, it will return the geometric extent. The symbolized extent takes into account the area the symbology covers so that it does not get cut off by the data frame's boundary. (默认值为 True) | Boolean |
| 数据类型 | 说明 |
| Extent |
The getExtent method will honor a layer's definition query so if a subset of features are queried, getExtent will return the extent for only those features.
A symbolized extent takes into account the area of the feature's symbol when building the extent rectangle. Returning a symbolized extent may be best for cartographic results because symbols won't be cut off at the data frame's edges. A geometric extent may be best for analysis.
| 参数 | 说明 | 数据类型 |
symbolized_extent |
A value of True will return the layer's symbolized extent; otherwise, it will return the geometric extent. The symbolized extent takes into account the area the symbology covers so that it does not get cut off by the data frame's boundary. (默认值为 True) | Boolean |
| 数据类型 | 说明 |
| Extent |
A symbolized extent takes into account the area of the feature's symbol when building the extent rectangle. Returning a symbolized extent may be best for cartographic results because symbols won't be cut off at the data frame's edges. A geometric extent may be best for analysis.
| 参数 | 说明 | 数据类型 |
workspace_path |
A string that includes the workspace path to the new data or connection file. | String |
workspace_type | A string keyword that represents the workspace type of the new data.
| String |
dataset_name | A string that represents the name of the dataset the way it appears in the new workspace (not the name of the layer in the TOC). If dataset_name is not provided, the replaceDataSource method will attempt to replace the dataset by finding a table with a the same name as the layer's current dataset property. | String |
validate | If set to True, a workspace will only be updated if the 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 the source to match the workspace_path, regardless of a valid match. In this case, if a match does not exist, then the data source would be broken. (默认值为 True) | Boolean |
有关详细论述、参数信息、案例和编码示例，请参阅使用 arcpy.mapping 更新和修复数据源帮助主题。
There is a subtle difference between a layer (.lyr) file and a map layer (a layer in a map document). The save method only works when a variable references a layer file and will not work with a map layer. When a layer is loaded from a layer file it will remember the file name and use that when the save method is called. If a map layer is being referenced, a file name is not initially set, so you will need to use the saveACopy method instead.
| 参数 | 说明 | 数据类型 |
file_name |
A string that includes the location and name of the output layer (.lyr) file. | String |
version |
A string that sets the output version number. The default value will use the current version.
(默认值为 None) | String |
可选择将图层 (.lyr) 文件另存为其他文件名称，或较早版本。较早版本的软件中不支持的功能将从新保存的图层中移除。
| 参数 | 说明 | 数据类型 |
layer_property |
The name of a particular layer property that will be tested.
(默认值为 name) | String |
| 数据类型 | 说明 |
| Boolean |
图层类型多种多样，并且不是所有图层类型都支持相同的属性。例如，要素图层支持定义查询，而栅格图层不支持，但栅格目录支持。support 方法主要用于协助识别哪些图层类型支持哪些属性，而不是创建所有可能图层类型和属性组合的各个图层对象。如果您不知道图层类型是否支持此属性，在获得或设置属性值前，您可以使用 support 方法对其进行测试。如果图层支持此属性，则 supports 属性将返回 true。
代码实例
以下脚本将引用图层 (.lyr) 文件，查找名为 Highways 的所有图层，打开标注，然后将结果保存到新图层文件中。
import arcpy
lyrFile = arcpy.mapping.Layer(r"C:\Project\Data\Streets.lyr")
for lyr in arcpy.mapping.ListLayers(lyrFile):
if lyr.name.lower() == "highways":
lyr.showLabels = True
lyr.saveACopy(r"C:\Project\Data\StreetsWithLabels.lyr")
del lyrFile
#Or with one less line using a wild card:
import arcpy
lyrFile = arcpy.mapping.Layer(r"C:\Project\Data\Streets.lyr")
for lyr in arcpy.mapping.ListLayers(lyrFile, "Highways"):
lyr.showLabels = True
lyr.saveACopy(r"C:\Project\Data\StreetsWithLabels.lyr")
del lyrFile
以下脚本将在打开需要输入密码的地图文档前，通过在内存中创建 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
以下脚本将会打印每个 SDE 或 Web 服务图层的名称以及相应的服务信息。与以上示例类似，由于某些 SDE 图层可能使用密码信息进行保护，因此将创建一个临时 SDE 连接文件。此示例不会打印关于非 SDE 或 Web 服务图层的信息。
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")
#Report service properties for layers in a map that support SERVICEPROPERTIES
mxd = arcpy.mapping.MapDocument(r"C:\Project\ServerData.mxd")
for lyr in arcpy.mapping.ListLayers(mxd):
if lyr.supports("SERVICEPROPERTIES"):
servProp = lyr.serviceProperties
print "Layer name:" + lyr.name
print "-----------------------------------------------------"
if lyr.serviceProperties["ServiceType"] != "SDE":
print "Service Type: " + servProp.get('ServiceType', 'N/A')
print " URL: " + servProp.get('URL', 'N/A')
print " Connection: " + servProp.get('Connection', 'N/A')
print " Server: " + servProp.get('Server', 'N/A')
print " Cache: " + str(servProp.get('Cache', 'N/A'))
print " User Name: " + servProp.get('UserName', 'N/A')
print " Password: " + servProp.get('Password', 'N/A')
print ""
else:
print "Service Type: " + servProp.get('ServiceType', 'N/A')
print " Database: " + servProp.get('Database', 'N/A')
print " Server: " + servProp.get('Server', 'N/A')
print " Service: " + servProp.get('Service', 'N/A')
print " Version: " + servProp.get('Version', 'N/A')
print " User name: " + servProp.get('UserName', 'N/A')
print " Authentication: " + servProp.get('AuthenticationMode', 'N/A')
print ""
del mxd
以下脚本将修改地图文档中图层的符号系统。它首先通过磁盘上的图层文件使用 UpdateLayer 函数来更新图层的符号系统。该图层文件包含适用于图层的自定义色带。然后，该脚本会验证图层是否具有分级颜色符号系统。最后，该脚本会修改 GraduatedColors 符号系统类中的大量属性，并将结果导出至 PDF。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Census")[0]
lyr = arcpy.mapping.ListLayers(mxd, "StatePopulation", df)[0]
lyrFile = arcpy.mapping.Layer(r"C:\Project\LYRs\Population.lyr")
arcpy.mapping.UpdateLayer(df, lyr, lyrFile, True)
if lyr.symbologyType == "GRADUATED_COLORS":
lyr.symbology.valueField = "POP2000"
lyr.symbology.numClasses = 4
lyr.symbology.classBreakValues = [250000, 999999, 4999999, 9999999, 35000000]
lyr.symbology.classBreakLabels = ["250,000 to 999,999", "1,000,000 to 4,999,999",
"5,000,000 to 9,999,999", "10,000,000 to 35,000,000"]
arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Output\StatePopulation.pdf")
del mxd, lyrFile
以下脚本用于测试图层文件是否支持时间，以及时间属性是否已设置。该脚本随后使用时间信息（开始时间和结束时间）来计算已启用时间的图层的时间范围。
import arcpy, datetime
lyr = arcpy.mapping.Layer(r'C:\Project\Data\Time\TemperatureWithTime.lyr')
if lyr.supports("TIME"):
lyrTime = lyr.time
if lyr.time.isTimeEnabled:
startTime = lyrTime.startTime
endTime = lyrTime.endTime
timeDelta = endTime - startTime
print "Start Time: " + str(startTime)
print "End Time: " + str(endTime)
print "Time Extent: " + str(timeDelta)
else:
print "No time properties have been set on the layer"
else:
print "Time is not supported on this layer"