LegendElement (arcpy.mapping)

摘要

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 中更新页面布局的各图例项样式。具体可通过以下工作流实现。

建议您为每个页面布局元素赋予唯一的名称，以便在使用 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)

Provides a mechanism to set the number of columns in a legend.

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

An integer that represents the desired number of columns.

(默认值为 1)

Integer

There are plenty of cases where there is not enough space on a layout to fit all legend items in a single column. A legend can be interrogated using its elementHeight or elementWidth properties to determine the needed space on the page. Another method would be to count the number of items in a legend. Whichever method is used, adjustColumnCount can then be used to establish the number of desired columns in a legend.

listLegendItemLayers ()
返回值
数据类型说明
Layer

图层对象的 Python 列表。每个图例项引用一个图层。

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

removeItem (legend_item_layer, {index})
参数说明数据类型
legend_item_layer

A reference to a layer that is used in a legend.

Layer
index

A single layer can be added into the same legend multiple times. The index value provides a way to reference a specific legend item. If you have more than one item and you want to remove all instances, then the removeItem will need to be called multiple times. By default the first legend item for a layer is removed.

(默认值为 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

A reference to a layer that is used in a legend.

Layer
legend_item_style_item

A reference to a legend item style item that is returned from the ListStyleItems function. This item must come from the style folder name Legend Items.

(默认值为 None)

Object
preserve_item_sizes

A Boolean that controls whether or not the symbol sizes can change if the size of the legend is changed. If set to True, the sizes authored in the style item will remain unchanged.

(默认值为 False)

Boolean
use_visible_extent

A Boolean that controls if only the features in the data frame's visible extent will be displayed in the legend.

(默认值为 False)

Boolean
show_feature_count

A Boolean that controls if feature counts will be displayed in the legend.

(默认值为 False)

Boolean
use_ddp_extent

A Boolean that controls if only the features within the Data Driven Pages index layer feature will be displayed in the legend. Data Driven Pages must be enabled.

(默认值为 False)

Boolean
index

A single layer can be added into the same legend multiple times. The index value provides a way to reference a specific legend item. If you have more than one item and you want to remove all instances, then the updateItem method will need to be called multiple times. By default the first legend item for a layer is updated.

(默认值为 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")
styleItem = arcpy.mapping.ListStyleItems("USER_STYLE", "Legend Items", "NewDefaultLegendStyle")[0]
legend = arcpy.mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT")[0]
legend.updateItem(lyrFile, styleItem)
if legend.isOverFlowing:
  removeLyr = arcpy.mapping.ListLayers(mxd, "County Boundary")[0]
  legend.removeItem(removeLyr)
del mxd
Copyright © 1995-2013 Esri. All rights reserved.
9/15/2013