LegendElement

摘要

LegendElement 对象可用于对属性和方法进行访问，这些属性和方法用于在页面布局中重新定位和调整图例元素的大小以及修改其标题和图例项。

讨论

与 MapsurroundElement 类似，LegendElement 对象与单个父数据框之间存在关联。此外，LegendElement 还包含了各种用于管理图例内容的方法和属性。这些方法和属性可用于控制新项目添加到图例中的方式、调整图例的大小、使用样式项目更新图例项属性以及指定图例中的列数。

ListLayoutElements 函数将返回页面布局元素对象的 Python 列表。随后需要遍历列表中的每个项目，或指定一个索引号以引用具体的页面元素对象。要返回只有 LegendElements 的列表，element_type 参数应使用 LEGEND_ELEMENT 常量。您可使用通配符根据元素名对搜索过程进行优化。

布局中的图例元素在 ArcMap 用户界面中对应一个称为新图层添加到地图时会向图例添加新项的属性，用于在地图中添加或移除图层时自动更新图例。autoAdd 属性用于控制此功能的开启/关闭，以便控制新添加的图层是否出现在图例中。例如，您可能需要添加正射影像，但是不需要在图例中显示它。在使用 AddLayer 函数前，需要将 autoAdd 属性设置为 False。

ArcMap 用户界面中的图例元素还包含一个称为固定框的属性。当此属性切换到开启状态并且所添加的图例项过多时，指定的固定区域内可能无法容纳所有项目。这种情况下，无法容纳的图例元素会被替换为小图标，以指示图例发生了溢出。isOverflowing 属性可用于对此进行检查，随后通过使用其他图例项样式来相应的调整图例元素的大小或修改图例项（例如，使用较小字号的图例项）。

removeItem 和 updateItem 属性可满足基本的 arcpy.mapping 要求：通过它可以使用自定义设置来移除图例项或修改其样式。在用户界面中，向内容列表中添加新图层并且该要素自动添加到图例中时，将应用默认样式。通过 arcpy.mapping 模块，您可以在 LegendElement 中更新页面布局的各图例项样式项目。具体可通过以下工作流实现。

• 使用样式管理器 制作一个自定义图例项样式项目。
• 使用 ListStyleItems 函数引用该自定义图例项样式项目。
• 使用 ListLayoutElements 函数引用图例元素。
• 使用 LegendElement 类中的 updateItem 方法更新图例中特定的图例项样式项目。

建议您为每个页面布局元素赋予唯一的名称，以便在使用 ArcPy 脚本时便于区分。可以在 ArcMap“属性”对话框的大小和位置选项卡中对其进行设置。

X 和 Y 元素的位置以元素的锚点位置为基础，也可以通过 ArcMap“属性”对话框中的大小和位置选项卡进行设置。

页面单位只能在 ArcMap 中通过自定义 > ArcMap 选项 > 布局视图选项卡来更改。

属性

属性	说明	数据类型
autoAdd (可读写)	控制当使用 AddLayer 或 AddLayerToGroup 函数时，是否自动将图层添加到图例。此属性的作用与标注为新图层添加到地图时会向图例添加新项的“地图连接”复选框选项相类似，该复选框位于“图例属性”对话框的“项目”选项卡中。	Boolean
elementHeight (可读写)	以页面单位计量的元素高度。分配或报告的单位采用页面单位。	Double
elementPositionX (可读写)	数据框元素的锚点位置的 x 位置。分配或报告的单位采用页面单位。	Double
elementPositionY (可读写)	数据框元素的锚点位置的 y 位置。分配或报告的单位采用页面单位。	Double
elementWidth (可读写)	以页面单位计量的元素宽度。分配或报告的单位采用页面单位。	Double
isOverflowing (只读)	如果在图例属性中设置了固定框选项，则在无法容纳图例项目的情况下返回 True。	Boolean
items (只读)	返回表示图例项目名称的字符串的列表。	String
name (可读写)	元素的名称。	String
parentDataFrameName (只读)	表示相关元素的数据框名称的字符串。	String
title (可读写)	表示图例标题的文本字符串。	String
type (只读)	返回任意给定页面布局元素的元素类型。 DATAFRAME_ELEMENT —数据框元素 GRAPHIC_ELEMENT —图形元素 LEGEND_ELEMENT —图例元素 MAPSURROUND_ELEMENT —地图整饰要素 PICTURE_ELEMENT —图片元素 TEXT_ELEMENT —文本元素	String

方法概述

方法	说明
adjustColumnCount (column_count)	提供一种机制用于在图例中设置列数量。
listLegendItemLayers ()	为图例中每个图例项返回图层对象引用的列表。
removeItem (legend_item_layer, {index})	removeItem 方法用于从布局上的图例中移除图例项。
updateItem (legend_item_layer, {legend_item_style_item}, {preserve_item_sizes}, {use_visible_extent}, {show_feature_count}, {use_ddp_extent}, {index})	updateItem 方法用于更新布局上的图例中图例项的各属性。

方法

adjustColumnCount (column_count)

参数	说明	数据类型
column_count	表示所需列数的整数。 (默认值为 1)	Integer

在很多情况下，由于布局上的空间不足，无法在一列中容纳所有图例项。可以使用图例的 elementHeight 或 elementWidth 属性来查询图例以确定页面上的所需空间。另一种方法是计算图例中的项目数。无论使用哪种方法，都可以使用 adjustColumnCount 来确定图例中的所需列数。

listLegendItemLayers ()

返回值

数据类型	说明
Layer	图层对象的 Python 列表。每个图例项引用一个图层。

listLegendItemLayers 方法用于确定图例中使用的各种图层和对应的使用次数。为图例中每个图例项返回图层对象。图层有可能只在内容列表中出现一次但在图例中出现多次。通过评估图层对象的已返回列表（为每个图例项返回一个对象），可以确定图层是否出现多次。如果希望移除或修改每个实例，您需要提供 removeItem 和 updateItem 方法的索引参数值。

removeItem (legend_item_layer, {index})

参数	说明	数据类型
legend_item_layer	对图例中所使用图层的引用。	Layer
index	可以将一个图层多次添加到相同图例中。索引值提供了引用特定图例项的方法。如果您有多个项目，并且想要移除所有实例，则需要多次调用 removeItem。默认情况下，将移除图层的第一个图例项。 (默认值为 0)	Long

有时，您可能希望从图例中移除图例项。例如，图例中完全不需要正射影像的图例项。removeItem 方法用于在自动添加图例项后从布局上的图例中移除该图例项。另一种方法则是设置图例的 autoAdd 属性以控制是否将新添加图层自动添加到图例中。

updateItem (legend_item_layer, {legend_item_style_item}, {preserve_item_sizes}, {use_visible_extent}, {show_feature_count}, {use_ddp_extent}, {index})

参数	说明	数据类型
legend_item_layer	对图例中所使用图层的引用。	Layer
legend_item_style_item	对从 ListStyleItems 函数返回的图例项样式项的引用。此项目必须来自样式文件夹名称图例项。 (默认值为 None)	Object
preserve_item_sizes	用于控制如果图例的大小更改，符号大小是否更改的布尔值。如果设置为 True，则在样式项中创作的大小将保持不变。 (默认值为 False)	Boolean
use_visible_extent	用于控制是否将在图例中仅显示数据框可见范围中的要素的布尔值。 (默认值为 False)	Boolean
show_feature_count	用于控制是否将在图例中显示要素计数的布尔值。 (默认值为 False)	Boolean
use_ddp_extent	用于控制是否将在图例中仅显示数据驱动页面索引图层要素内的要素的布尔值。必须启用数据驱动页面。 (默认值为 False)	Boolean
index	可以将一个图层多次添加到相同图例中。索引值提供了引用特定图例项的方法。如果您有多个项目，并且想要移除所有实例，则需要多次调用 updateItem 方法。默认情况下，将更新图层的第一个图例项。 (默认值为 0)	Long

updateItem 方法满足基本 arcpy.mapping 要求，以便可以使用自定义设置更新图例项。在用户界面中，当您向内容列表中添加一个新的图层并且该要素被自动添加到图例中时，将应用默认样式。通过 arcpy.mapping 模块，您可以在 LegendElement 中更新页面布局的各图例项。

代码示例

LegendElement 示例 1

以下脚本将图层添加到地图文档的新数据框中，且该地图文档包括名为“Legend”的已插入图例元素。将除了正射影像外的图层自动添加到图例中。自动添加由 autoAdd 属性控制。最后，添加图层后，将列数调整为 2。

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "New Data Frame")[0]
lyr1 = arcpy.mapping.Layer(r"C:\Project\Data\Parcels.lyr")
lyr2 = arcpy.mapping.Layer(r"C:\Project\Data\MapIndex.lyr")
lyr3 = arcpy.mapping.Layer(r"C:\Project\Data\Orthophoto.lyr")
legend = arcpy.mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT", "Legend")[0]
legend.autoAdd = True
arcpy.mapping.AddLayer(df, lyr1, "BOTTOM")
arcpy.mapping.AddLayer(df, lyr2, "BOTTOM")
legend.autoAdd = False
arcpy.mapping.AddLayer(df, lyr3, "BOTTOM")
legend.adjustColumnCount(2)
mxd.save()
del mxd

LegendElement 示例 2

以下脚本使用启用固定框的图例项。如果图例项发生溢出，此脚本则将图例的高度增加 0.1 英寸，直至所有项目均可显示。

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
legendElm = arcpy.mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT", "Legend")[0]
while legendElm.isOverflowing:
  legendElm.elementHeight = legendElm.elementHeight + 0.1
del mxd

LegendElement 示例 3

以下脚本使用上述工作流并更新给定图例项。将向地图文档中的第一个数据框中添加图层，并通过名为 NewDefaultLegendStyle 的自定义图例项样式更新该图例项。自定义 .style 文件保存在用户配置文件所在的位置中。接下来，此脚本检查图例是否发生溢出，如果发生溢出，则从图例中移除不必要图层以留有额外空间。

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd)[0]
lyrFile = arcpy.mapping.Layer(r"C:\Project\Data\Rivers.lyr")
arcpy.mapping.AddLayer(df, lyrFile, "TOP")
lyr = arcpy.mapping.ListLayers(mxd, 'Rivers', df)[0]
styleItem = arcpy.mapping.ListStyleItems("USER_STYLE", "Legend Items", "NewDefaultLegendStyle")[0]
legend = arcpy.mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT")[0]
legend.updateItem(lyr, styleItem)
if legend.isOverFlowing:
  removeLyr = arcpy.mapping.ListLayers(mxd, "County Boundary")[0]
  legend.removeItem(removeLyr)
del mxd

LegendElement 示例 4

以下脚本将更新图例中的所有图层，以使用名为 MyNewStyle 的自定义图例项样式项目。

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
legend = arcpy.mapping.ListLayoutElements(mxd,"LEGEND_ELEMENT")[0]
styleItem = arcpy.mapping.ListStyleItems("USER_STYLE", 
                                         "Legend Items", 
                                         "MyNewStyle")[0]
for lyr in legend.listLegendItemLayers():
     legend.updateItem(lyr, styleItem)
del mxd