Layer

摘要

用于对基本图层属性和方法进行访问。

说明

使用地图类中的 listLayers 方法可引用工程中的图层，或使用 LayerFile 类中的 listLayers 方法引用存储于磁盘上的图层文件（.lyr 或 .lyrx）中的图层。

Layer 对象以单一通用方式进行设计，以便处理所有图层。 图层类型千差万别，所支持的属性集也并不都一样。 例如，要素图层支持定义查询，而栅格图层不支持，但栅格目录支持。 一些有用的属性允许您获取有关图层及其支持的属性的信息，从而无需在各种不同的图层对象中查找所有可能的图层类型与属性的组合。 许多 is 属性都使您能够确定图层是否属于常规类别，例如 is3DLayer、isFeatureLayer、isGroupLayer、isRasterLayer、isWebLayer 等等。

还有少数专题图层和数据集并不属于这些常规类别：注记子类、尺寸要素、terrain 数据集、拓扑数据集等。 这种情况下，对所关注的图层执行操作前，您需要先测试其他属性以分离该图层。 supports 方法可帮助确定哪一特定图层支持何种特定图层属性。 此方法可用于在尝试获取或设置值之前测试该图层是否支持这一属性，从而可减少不必要的错误信息。 例如，请查看以下代码：

if lyr.supports("BRIGHTNESS"):
    lyr.brightness = 10

地图类中的 listLayers 方法将返回按图层在内容列表中的显示顺序或在图层文件中的显示顺序从上至下生成的索引值。 如果图层组在另一个图层组内，则同样适用。 例如，具有包含三个子图层的单个图层组的地图将返回包含四个图层名称的列表，图层组为第一个，三个子图层为第二、第三和第四。 有两种方法可以确定图层是否为图层组。 第一种方式，可以查看该图层是否支持 isGroupLayer 属性。 第二种方式，可以评估 longName 属性。 图层的 longName 值除了图层名称外还包括组名称。 例如，在一个名称为 Layer1 的图层组中，名称为 Group1 的图层将具有 Group1\Layer1 的 longName 值。 如果 name 值等于 longName 值，则该图层不在图层组中。 处理复合图层的子图层时，longName 属性将包含子图层和顶级图层的名称。

ArcGIS Pro 可读取旧的 .lyr 文件类型，但仅可将其保存到 .lyrx 文件类型。 如果正在引用 .lyr 文件类型且已调用 save 方法，则会将其转换为 .lyrx 文件类型，但文件名保持不变。

要素图层可以支持零到多个定义查询，但只能激活一个定义查询。 也有可能存在一个或多个定义查询但没有一个是活动的。 有几种方法可以管理定义查询。 第一种方式，可以使用 definitionQuery 属性。 如果在不具有定义查询的图层或具有多个定义查询的图层上设置唯一 SQL 字符串，则会添加新定义查询并将其设置为活动查询。 如果在具有相同查询的图层上设置 SQL 字符串，则会将其设置为活动定义查询（如果它尚未处于活动状态）。 管理定义查询的第二种方法是结合使用 listDefinitionQueries 和 updateDefinitionQueries 函数。 listDefinitionQueries 函数返回 Python 字典列表，这些字典表示与每个查询关联的属性。 字典关键字是 name、sql 和 isActive。 可以使用核心 Python 从 Python 列表中添加、修改或删除定义查询。 可以将字典 isActive 值设置为 True 以设置活动查询。 同样，只有一个查询可以处于活动状态。 如果您尝试将多个查询设置为活动状态，则会返回错误。 更改完成后，使用 updateDefinitionQueries 函数设置新的更改。

更改图层的数据源是一项常见要求。 Layer 对象中的方法和属性可帮助解决此问题。 有关详细说明、参数信息、案例和代码示例，请参阅更新和修复数据源帮助主题。

属性

属性	说明	数据类型
brightness (可读写)	图层的亮度值。 默认正常亮度为 0%。 输入 +100% 和 -100% 之间的任意值。 在值的左侧输入加号或减号以指定该值是大于零还是小于零。	Integer
connectionProperties (只读)	图层数据源连接信息作为 Python 字典返回。	Dictionary
contrast (可读写)	图层的对比度值。 默认中性对比度为 0%。 输入 +100% 和 -100% 之间的任意值。 在值的左侧输入加号或减号以指定该值是大于零还是小于零。	Integer
dataSource (只读)	返回图层数据源的完整路径。 其中包括完整的工作空间路径和数据集的名称。 对于企业级地理数据库图层，将返回包含图层连接信息的字符串。 提示： ArcGIS Pro 工程中的企业级地理数据库图层不保留用于创建图层的数据库连接文件的路径 (.sde)。	String
definitionQuery (可读写)	图层的定义查询。 如果在不具有定义查询的图层或具有多个定义查询的图层上设置唯一 SQL 字符串，则会添加新定义查询并将其设置为活动查询。 如果在具有相同查询的图层上设置 SQL 字符串，则仅会将其设置为活动定义查询（如果它尚未处于活动状态）。	String
is3DLayer (只读)	如果图层是 3D 图层，则返回 True。	Boolean
isBasemapLayer (只读)	如果图层是底图图层，则返回 True。	Boolean
isBroken (只读)	如果图层的数据源损坏，则返回 True。	Boolean
isFeatureLayer (只读)	如果图层是要素图层，则返回 True。	Boolean
isGraphicsLayer (只读)	如果图层为图形图层，则将返回 True。	Boolean
isGroupLayer (只读)	如果图层是图层组，则返回 True。	Boolean
isNetworkAnalystLayer (只读)	如果图层是 True 图层，则返回 ArcGIS Network Analyst 扩展。	Boolean
isNetworkDatasetLayer (只读)	如果图层是 ArcGIS Network Analyst 扩展 网络数据集图层，则返回 True。	Boolean
isParcelFabricLayer (只读)	如果图层为宗地结构图层，则将返回 True。	Boolean
isRasterLayer (只读)	如果图层是栅格图层，则返回 True。	Boolean
isSceneLayer (只读)	如果图层是场景图层，则返回 True。	Boolean
isTimeEnabled (只读)	指示在图层上是否启用时间。 如果 isTimeEnabled 返回 True，可以使用图层上的 time 属性返回 LayerTime 对象。 使用 enableTime 方法以在包含时间信息的图层上启用时间。	Boolean
isWebLayer (只读)	如果图层是 GIS 服务图层，则返回 True。 GIS 服务是自动化的地理信息服务，可以使用标准技术和协议在 Web 上对其进行发布和访问。 Esri 底图就是一个示例。	Boolean
longName (只读)	包含图层组和复合图层结构的图层全名。	String
maxThreshold (可读写)	图层的 2D 地图的最大比例阈值及其 3D 地图的地上最大距离。 如果图层被放大的比例超过了最大比例，则不会显示出来。 要清除最大比例，请将值设置为 0。	Double
metadata (可读写)	获取或设置图层的元数据类信息。 注： 设置元数据取决于 isReadOnly 属性值。	Metadata
minThreshold (可读写)	图层的 2D 地图的最小比例阈值及其 3D 地图的地上最大距离。 如果图层被缩小的比例超过了最小比例，则不会显示出来。 要清除最小比例，请将值设置为 0。	Double
name (可读写)	图层在内容列表中显示的名称。 可包含空格。 有必要确保地图上的所有图层都具有唯一的名称，因为这样便可通过这些唯一名称轻松对其进行引用。	String
showLabels (可读写)	控制图层标注的显示。 如果设置为 True，则显示标注；如果设置为 False，则不会绘制标注。	Boolean
symbology (可读写)	用于访问图层的符号系统。	Object
time (只读)	如果在图层上启用了时间，则返回一个 LayerTime 对象。	LayerTime
transparency (可读写)	图层的透明度值。 这样即可看透图层。 使用 0 和 100 之间的值。 值 0 表示不透明。 大于 90% 的透明度值经常导致图层几乎未被绘制。	Integer
URI (只读)	图层的统一资源指示符。 这是项目中图层的唯一标识符，使用 Python CIM 访问时有时需要它。 添加图层并建立 URI 后，该值不会随时间变化。 例如，如果您修改图层的名称，则 URI 不会更改。	String
visible (可读写)	控制图层的显示。 如果设置为 True，则绘制图层；如果设置为 False，则不绘制图层。	Boolean

方法概述

方法	说明
enableTime ({startTimeField}, {endTimeField}, {autoCalculateTimeRange}, {timeDimension})	如果图层具有时间信息，则在该图层上启用时间。
extrusion ({extrusion_type}, {expression})	在图层中对 2D 要素进行拉伸以显示 3D 符号系统。
getDefinition (cim_version)	获取图层 CIM 定义。
getSelectionSet ()	以 Python 对象 ID 集的形式返回图层选择。
listDefinitionQueries ({wildcard})	返回与图层关联的定义查询的 Python 列表。
listLabelClasses ({wildcard})	返回图层中的 LabelClass 对象的 Python 列表。
listLayers ({wildcard})	返回图层组或复合图层中的图层对象的 Python 列表。
listTables ({wildcard})	返回存在于图层组中的 Table 对象的 Python 列表。
saveACopy (file_name)	将图层保存为图层文件 (.lyrx)。
setDefinition (definition_object)	设置图层的 CIM 定义。
setSelectionSet ({oidList}, {method})	使用 Python 对象 ID 列表设置图层选择。
supports (layer_property)	用于确定特定图层类型是否支持图层对象的属性。 并非所有图层都支持同一组属性；尝试设置属性前可使用 supports 属性测试图层是否支持该属性。
updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case})	updateConnectionProperties 方法使用工作空间字典或路径替换连接属性。
updateDefinitionQueries (definitionQueries)	更新图层的定义查询集合。
updateLayerFromJSON (json_data)	从 JSON 字符串更新图层。

方法

enableTime ({startTimeField}, {endTimeField}, {autoCalculateTimeRange}, {timeDimension})

参数	说明	数据类型
startTimeField	The name of the field containing the start time values. If each feature has a single time field, specify that field name in the startTimeField and leave endTimeField blank. If each feature has a start and end time field, specify both the startTimeField and endTimeField. (默认值为 None)	String
endTimeField	The name of the field containing the end time values. Not all layers use an end time field. If each feature has a single time field, specify that field name in the startTimeField and leave endTimeField blank. If each feature has a start and end time field, specify both the startTimeField and endTimeField. (默认值为 None)	String
autoCalculateTimeRange	If set to True, the start and end time attribute information is used to calculate the layer's time extent. (默认值为 True)	Boolean
timeDimension	The name of the dimension containing time values when using netCDF data. (默认值为 None)	String

enableTime 方法的所有参数均为可选参数。 如果未指定 startTimeField 和 endTimeField，则该方法将评估数据并尝试提供适当的默认值。

运行 enableTime 方法后，可以使用图层上的 time 属性返回 LayerTime 对象。 如果布局上的 MapFrame 包含启用时间的图层，则可以使用 MapTime 类访问地图时间设置。

extrusion ({extrusion_type}, {expression})

参数	说明	数据类型
extrusion_type	用于指定拉伸方法的字符串。默认值为 NONE，即关闭图层拉伸。 ABSOLUTE_HEIGHT—无论要素的 z 值是多少，要素都将被拉伸到指定的 z 值以形成平整的顶部。 BASE_HEIGHT—为表示要素基本高度的每个折点计算 z 值，要素将被拉伸到各 z 值的高度，以创建多面顶部。 MAX_HEIGHT—向要素的最小 z 值添加拉伸高度，要素将被拉伸到处于该值高度的平面。 MIN_HEIGHT—向要素的最小 z 值添加拉伸高度，要素将被拉伸到处于该值高度的平面。 NONE—要素未被拉伸。 (默认值为 NONE)	String
expression	用于定义拉伸表达式的字符串，该表达式为每个要素提供一个绝对拉伸高度。 (默认值为 None)	String

拉伸是通过垂直拉伸 2D 平面形状来创建 3D 对象的过程。这是一种基于二维要素创建三维符号系统的方法。面要素和线要素均具有五个可用的 extrusion_type 选项；点要素不使用 MAX_HEIGHT 或 MIN_HEIGHT 选项。

getDefinition (cim_version)

参数	说明	数据类型
cim_version	A string that represents the major version of the CIM.	String

在 ArcGIS Pro 2.4 中引入了对其他对象属性的 CIM 级别访问权限。 要返回对象的 CIM 定义，必须指定 cim_version。 Esri 遵循语义版本规范。 这意味着在主要版本（例如 3.0）中允许突破性 API 更改。 如果可能在新版本中引入突破性更改，Python 脚本作者可通过该值控制脚本运行期间使用的 CIM 版本。 如果您正在为 ArcGIS Pro 2.x 创作脚本，可将 cim_version 指定为 'V2'。 如果您正在为 ArcGIS Pro 3.x 创作脚本，可将 cim_version 指定为 'V3'。 使用 cim_version 'V2' 创作的脚本可继续在 ArcGIS Pro 3.x 中使用。

有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。

getSelectionSet ()

提供检索图层当前选择的简便方式。

listDefinitionQueries ({wildcard})

参数	说明	数据类型
wildcard	A wildcard is based on the query name and is not case sensitive. A combination of asterisks (*) and characters can be used to limit the resulting list. (默认值为 None)	String

返回值

数据类型	说明
List	表示与每个查询关联的属性的 Python 字典列表。 字典关键字是 name、sql 和 isActive。

可以使用标准做法从 Python 列表中添加、修改或删除定义查询。 可以将字典 isActive 值设置为 True 以设置活动查询。 同样，只有一个查询可以处于活动状态。 如果您尝试将多个查询设置为活动状态，则会返回错误。 更改完成后，使用 updateDefinitionQueries 函数设置新的更改。

listLabelClasses ({wildcard})

参数	说明	数据类型
wildcard	通配符基于标注类名称且不区分大小写。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None)	String

返回值

数据类型	说明
List	返回图层中的 LabelClass 对象的 Python 列表。

返回图层中的 LabelClass 对象的 Python 列表。

listLayers ({wildcard})

参数	说明	数据类型
wildcard	通配符基于图层名称且不区分大小写。星号 (*) 和字符的组合可用于帮助限制生成的列表。 (默认值为 None)	String

返回值

数据类型	说明
List	返回图层组或复合图层中的图层对象的 Python 列表。

返回图层组或复合图层中的图层对象的 Python 列表。

listTables ({wildcard})

参数	说明	数据类型
wildcard	A wildcard is based on the table name and is not case sensitive. A combination of asterisks (*) and characters can be used to limit the resulting list. (默认值为 None)	String

返回值

数据类型	说明
List	图层中 Table 对象的 Python 列表。

返回存在于图层组中的 Table 对象的 Python 列表。 ListTables 始终返回列表对象，即使仅返回一个表。

图层组中可能存在同名的表。 在这种情况下，可能需要使用其他属性来隔离特定图层。 例如，表的 datasource、definitionQuery 或 URI 属性可用来执行此操作。 理想状态为所有表名称均唯一。

saveACopy (file_name)

参数	说明	数据类型
file_name	包含输出图层文件 (.lyrx) 的位置和名称的字符串。	String

保存图层组时，TOC 中该组下所有的图层都将被保存到图层文件 (.lyrx) 中。

setDefinition (definition_object)

参数	说明	数据类型
definition_object	使用 getDefinition 最初检索的已修改 CIM 定义对象。	Object

有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。

setSelectionSet ({oidList}, {method})

参数	说明	数据类型
oidList [oidList,...]	与相应的选择方法一起使用的 Python 对象 ID 列表。 (默认值为 None)	Integer
method	用于指定要使用的选择方法的字符串。 NEW—从 oidList 创建一个新的要素选择。 DIFFERENCE—选择不在当前选择中但在 oidList 中的要素。 INTERSECT—选择当前选择和 oidList 中均含有的要素。 SYMDIFFERENCE—选择当前选择或 oidList 不含的要素。 UNION—选择当前选择和 oidList 中的全部要素。 (默认值为 NEW)	String

利用此方法可方便管理图层选择。要清空选择，请使用包含空列表的 NEW 选择方法或不设置任何参数。

注意：Python 列表可用于设置 oidList，但可通过 Layer 对象的 getSelectionSet 方法返回 Python 集。

supports (layer_property)

参数	说明	数据类型
layer_property	The name of a particular layer property that will be tested. BRIGHTNESS—A raster layer's brightness value. CONNECTIONPROPERTIES—A Layer's connection information. CONTRAST—A raster layer's contrast value DATASOURCE—A layer's file path or connection file. DEFINITIONQUERY—A layer's definition query string. LONGNAME—A layer's path including the group layers it may be nested within. MAXTHRESHOLD—A layer's maximum threshold to display the features. METADATA—A layer that can persist metadata. MINTHRESHOLD—A layer's minimum threshold to display the features. NAME—A layer's name. SHOWLABELS—A layer that can display labels. SYMBOLOGY—A layer that symbology can be accessed. TIME—A layer's time properties. TRANSPARENCY—A layer's transparency value. URI—A layer's Universal Resource Identifier. VISIBLE—A layer's visibility state. (默认值为 name)	String

返回值

数据类型	说明
Boolean

图层类型千差万别，所支持的属性也并不都一样。 例如，要素图层支持定义查询，而栅格图层不支持，但栅格目录支持。 supports 方法主要用于协助识别哪些图层类型支持哪些属性，而不是创建所有可能图层类型和属性组合的各个图层对象。 如果您不知道图层类型是否支持此属性，在获得或设置属性值前，您可以使用 support 方法对其进行测试。 如果图层支持该属性，则 supports 属性将返回 True。

不需要使用 supports 测试布尔属性，这是因为如果该图层类型不支持图层属性，则将返回 False 值。

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

有关更详细的说明、参数信息、情景和代码示例，请参阅更新和修复数据源。

updateDefinitionQueries (definitionQueries)

参数	说明	数据类型
definitionQueries [definitionQueries,...]	Updates a list of dictionaries that represent the properties of each definition query.	List

此函数通常用于应用对 listDefinitionQueries 函数返回的结果所做的更改。

updateLayerFromJSON (json_data)

参数	说明	数据类型
json_data	The layer definition in JavaScript Object Notation (JSON) format. See the ExportWebMap JSON specification for more information. ArcGIS API for JavaScript and ArcGIS Web AppBuilder allow you to get this JSON string from the web app. The layer definition is a subset of the webmap_json used in the ConvertWebMapToArcGISProject function. You don't need to create the web map JSON; the APIs take care of it for you. However, you need to extract the layer definition from the full webmap_json.	String

此函数可在 Web 工具中使用，此工具会在支持更改动态 Web 服务图层中的渲染器（或其他属性）的 Web 地图打印应用程序中使用 ConvertWebMapToArcGISProject 函数。 如果 Web 工具在运行 ConvertWebMapToArcGISProject 后将服务图层替换为过渡的矢量图层，则 updateLayerFromJSON 将按照 webmap_json 中指定的渲染器（或其他图层属性）应用于在布局模板中过渡的相应矢量图层。 有关详细信息和代码示例，请参阅 ConvertWebMapToArcGISProject。

代码示例

图层示例 1

以下脚本打印工程中每个地图的名称并列出每个地图中的图层名称。 如果数据源损坏，脚本还会在图层名称后附加一个 (BROKEN) 前缀。

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
for m in aprx.listMaps():
    print("Map: {0} Layers".format(m.name))
    for lyr in m.listLayers():
        if lyr.isBroken:
            print("(BROKEN) " + lyr.name)
        else:
            print("  " + lyr.name)
del aprx

图层示例 2

以下脚本将清除名为 Yosemite National Park 的地图中的所有图层定义查询并关闭所有图层的标注：

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
m = aprx.listMaps("Yosemite National Park")[0]
for lyr in m.listLayers():
    if lyr.supports("DEFINITIONQUERY"):
        lyr.definitionQuery = ""
    if lyr.supports("SHOWLABELS"):
        lyr.showLabels = False
aprx.save()
del aprx

图层示例 3

以下脚本向图层添加新的定义查询，或者如果 SQL 字符串已存在，则将相同的查询设置为活动定义查询：

p = arcpy.mp.ArcGISProject('current')
m = p.listMaps()[0]
l = m.listLayers()[0]
if l.supports('DefinitionQuery'):
  l.definitionQuery = "AREA > 3000000"

图层示例 4

以下脚本通过将 Python 字典附加到现有列表查询来创建新的定义查询。 因为查询可能已经处于活动状态，所以在设置新的活动查询之前首先清除现有的活动查询很重要。

p = arcpy.mp.ArcGISProject('current')
m = p.listMaps()[0]
l = m.listLayers()[0]
if l.supports('DefinitionQuery'):
  #Get the list of definition queries
  dql = l.listDefinitionQueries()
  #Clear active definition queries otherwise the update will fail if there is already an active query
  for dq in dql:
    dq['isActive'] = False
  #Create a new definition query and append it to the list
  dql.append({'name': 'Appended Query', 'sql': "name = 'Lake Superior'", 'isActive': True})
  #Update the definition queries with the newly modified list
  l.updateDefinitionQueries(dql)