摘要
通过 LegendElement 类可以访问用于管理布局上的图例元素的属性和方法。
说明
LegendElement 是一种特定类型的 MapSurroundElement 布局元素。 该元素还具有与 MapFrame 对象的关联，包含特定于图例的附加属性，包括对 LegendItem 对象的访问。 Layout 对象上的 listElements 方法将返回页面布局元素对象的 Python 列表。 如要仅返回 LegendElement 对象的列表，请为 element_type 参数使用 LEGEND_ELEMENT 常量。 还可以使用 wildcard 值，基于元素的 name 值对搜索进行进一步优化。 为每个页面布局元素提供唯一名称，以便轻松地引用元素。
您可以使用 Layout 对象的 createMapSurroundElement 方法，将 map_surround_type 设置为 LEGEND 以创建图例。可以在创建期间指定现有的 StyleItem 值以控制元素在布局中的显示方式。
默认情况下，添加到 Map 对象的图层将自动添加到 LegendElement 对象。 这样便可以使用空地图和图例创建布局，但在将新图层添加到地图时动态更新这些项目。 有多个以 'sync' 为开头的属性可用于控制如何将项目添加到图例。 您也可以使用 fittingStrategy 和 columnCount 属性控制图例的外观。
elementPositionX 和 elementPositionY 值取决于元素的锚点位置，该位置在格式选项卡上进行设置。 如果希望在添加图层时 LegendElement 对象向下延伸，请将锚点位置设置为左上角。 您可以使用 setAnchor 方法更改位置。
items 属性将返回 LegendItem 类列表。您可以单独对这些类进行修改，以进一步自定义图例的内容。 LegendElement 类还提供 AddItem、MoveItem 和 RemoveItem 方法，以便您管理图例中的项目。 LegendElement 和 LegendItem 类仅提供对常用属性的访问权限。 可以使用 Python CIM 访问对内容进行细化访问。
属性
| 属性 | 说明 | 数据类型 |
| anchor (只读) | 返回表示当前锚点位置的以下字符串值之一。 要更改值，请使用 setAnchor 方法。
| String |
| columnCount (可读写) | 图例中指定列的数量。 此属性仅在将 fittingStrategy 设置为 AdjustFontSize、AdjustFrame 或 ManualColumns 时适用。 | Long |
| elementHeight (可读写) | 元素的高度（以页面单位计）。 | Double |
| elementPositionX (可读写) | 元素的锚点位置的 x 位置。 分配或报告的单位为页面单位。 | Double |
| elementPositionY (可读写) | 元素的锚点位置的 y 位置。 分配或报告的单位为页面单位。 | Double |
| elementRotation (可读写) | 相对于锚点位置旋转元素。 正值表示顺时针旋转，负值表示逆时针旋转。 | Double |
| elementWidth (可读写) | 元素的宽度（以页面单位计）。 | Double |
| fittingStrategy (可读写) | 表示有效自适应策略方法的字符串。 有效值如下：
| String |
| items (只读) | 返回相关 LegendItem 类列表。 您不能直接设置此属性，但是，可以遍历图例项并修改其属性。 | List |
| locked (可读写) | 设置为 True 时，无法在布局视图中以图形方式选择元素。 | Boolean |
| longName (只读) | 元素的全名，包括组信息（如果存在）。 例如，在一个名称为 Group Element 的组元素中，名称为 Map Frame 的元素将返回 Group Element\\Map Frame 的 longName 值。 如果元素不在组中，则 longName 与 name 值相同。 | String |
| mapFrame (可读写) | 对关联 MapFrame 的引用。 | MapFrame |
| name (可读写) | 元素的名称。 有必要确保所有元素均具有唯一名称，因为这样可以轻松对其进行引用。 | String |
| parentGroupElement (只读) | 如果元素在组中，则返回的值为 GroupElement，否则返回 NoneType。 | GroupElement |
| showTitle (可读写) | 一个布尔值，用于控制标题是否显示在图例中。 | Boolean |
| syncLayerOrder (可读写) | 一个布尔值，用于控制图例中的项目是否与地图中图层的顺序相同。 | Boolean |
| syncLayerVisibility (可读写) | 一个布尔值，用于控制项目是否应自动出现在图例中（如果图例在地图中可见）。 | Boolean |
| syncNewLayer (可读写) | 一个布尔值，用于控制当项目被添加到地图中时是否应自动将该项目添加到图例中。 | Boolean |
| syncReferenceScale (可读写) | 一个布尔值，用于控制图例中的符号是否与地图中符号的比例相匹配（如果设置了参考比例）。 | Boolean |
| title (可读写) | 表示图例标题的文本字符串。 | String |
| type (只读) | 返回值 LEGEND_ELEMENT。 | String |
| visible (可读写) | 如果元素在布局上可见，则返回 True。 打印或导出之前，您可以打开和关闭元素的可见性，而不必从页面移除不需要的对象。 | Boolean |
方法概述
| 方法 | 说明 |
| addItem (layer, {add_position}) | 您可以使用基本放置选项将图层添加到图例中。 |
| applyStyleItem (style_item) | 将 StyleItem 应用于 LegendElement。 |
| getDefinition (cim_version) | 返回图例元素的 CIM 定义。 |
| moveItem (reference_item, move_item, {move_position}) | 您可以将图例项移动到图例中的特定位置。 |
| removeItem (remove_item) | 允许您从图例中移除图例项。 |
| setAnchor (anchor) | setAnchor 方法可控制 LegendElement 的锚点位置。 |
| setDefinition (definition_object) | 设置图例元素的 CIM 定义。 |
方法
addItem (layer, {add_position})| 参数 | 说明 | 数据类型 |
layer | 对 Layer 对象（将要添加到图例中的图层表示为 LegendItem）的引用。 | Layer |
add_position | 此常数用于确定在图例内添加的图层的放置位置。
(默认值为 TOP) | String |
| 数据类型 | 说明 |
| LegendItem | LegendItem 对象。 |
addItem 方法用于将图层添加至布局中的图例。默认 add_position 可将图层添加到图例项列表的顶部，因此该图层显示在首位。有关更精确的图例项放置，请参阅 moveItem 方法。
applyStyleItem (style_item)
当在 ArcGISProject 类上使用 listStyleItems 方法引用 StyleItem 时，style_class 参数必须是 LEGEND。 有关详细信息和代码示例，请参阅 StyleItem 帮助主题。
注：
在使用 applyStyleItem 方法之前，必须先将样式添加到工程中。 可以在 ArcGISProject 类上使用 updateStyles 方法添加样式。
getDefinition (cim_version)
| 参数 | 说明 | 数据类型 |
cim_version | A string that represents the major version of the CIM that will be used.
| String |
| 数据类型 | 说明 |
| Object | 返回 LegendElement 值的 CIM 定义。 |
有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。
moveItem (reference_item, move_item, {move_position})| 参数 | 说明 | 数据类型 |
reference_item | LegendItem 对象表示现有图例项，该项目用于确定移动 move_item 的相对位置。 | LegendItem |
move_item | 对 LegendItem 对象（表示要移动的图层）的引用。 | Layer |
move_position | 此常数用于确定移动的图层相对于参考图层的放置位置。
(默认值为 BEFORE) | String |
moveItem 方法用于移动图例中的图例项。可将 move_item 移动到 reference_item 之后或之前。
removeItem (remove_item)
| 参数 | 说明 | 数据类型 |
remove_item | 对 LegendItem 对象（表示要移除的项目）的引用。 | LegendItem |
removeItem 方法用于从图例中移除单个图例项。
setAnchor (anchor)
| 参数 | 说明 | 数据类型 |
anchor | A string that specifies the location of the anchor position.
| String |
设置锚点位置非常有用，因为您可以控制元素在调整大小时的展开方式。 例如，图例元素的默认锚点位置为 TOP_LEFT_CORNER。 如果将锚点位置更改为 BOTTOM_RIGHT_CORNER，则更改 elementHeight 将使元素向下扩展，更改 elementWidth 将使元素向左扩展。
setDefinition (definition_object)
| 参数 | 说明 | 数据类型 |
definition_object | A modified CIM definition object originally retrieved using getDefinition. | Object |
有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。
代码示例
以下脚本可向布局添加新图例并更新多个属性。 在添加图层文件之前，该脚本会关闭图层同步，以使地形色彩映射表不显示。 添加图层后，图层同步将再次打开。
import arcpy
p = arcpy.mp.ArcGISProject(r'C:\Projects\YosemiteNP\Yosemite_Trails.aprx')
#Create a new legend and set legend properties
lyt = p.listLayouts('Main Attractions')[0]
mf = lyt.listElements('MapFrame_Element', 'Yose*')[0]
legSi = p.listStyleItems('ArcGIS 2D', 'LEGEND', 'Legend 3' )[0]
leg = lyt.createMapSurroundElement(arcpy.Point(0.75,3.5), 'LEGEND', mf, legSi, 'New Legend Element')
leg.elementWidth = 7
leg.elementHeight = 3
leg.fittingStrategy = 'AdjustFontSize'
leg.columnCount = 5
leg.title = 'Yosemite National Park'
#Add a layer file but first turn of legend layer synchronization
leg.syncNewLayer = False
lyr = arcpy.mp.LayerFile(r'C:\Projects\YosemiteNP\LayerFiles\Terrain.lyrx')
m = p.listMaps('Yosemite National Park')[0]
m.addLayer(lyr, 'BOTTOM')
leg.syncNewLayer = True
p.saveACopy(r"C:\Projects\YosemiteNP\Yosemite_Trails_OUT.aprx")以下脚本可将 fittingStrategy 设置为 ManualColumns，然后将 columnCount 设置为 4。 接下来，脚本会构建一个字典，其中包含图例项名称和用于放置图例项的列。 最后，脚本会遍历每个图例项，并基于字典值将其放置在适当的列中。
import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])
p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'NewMexicoGeology', 'NewMexicoGeology.aprx'))
lyt = p.listLayouts('Layout')[0]
leg = lyt.listElements('LEGEND_ELEMENT')[0]
#Change Title and fitting strategy to (4) Manual Columns
leg.fittingStrategy = 'ManualColumns'
leg.columnCount = 4
#Dictionary of item name and column pairs
legDict = {'Cretaceous' : 1,
'Mississippian' : 1,
'Tertiary' : 2,
'Silurian' : 2,
'Ordovician' : 2,
'Quaternary' : 3,
'Jurassic' : 3,
'Devonian' : 3,
'Permian': 4,
'Proterozoic' : 4,
'Other' : 4 }
#Place each legend item into the appropriate column based on name
for legItm in leg.items:
legItm.column = legDict[legItm.name]
p.saveACopy(os.path.join(relpath, 'NewMexicoGeology', 'NewMexicoGeology_OUT.aprx'))以下脚本使用 Python CIM 访问修改图例的标题符号系统和图面宽度。 该脚本还使用 CIM 修改唯一值渲染器中每个类的图面形状。
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
leg = lyt.listElements('LEGEND_ELEMENT')[0]
#Use Legend poperties to display and modify title text
leg.showTitle = True
leg.title = "Legend CIM Changes"
#CIM modifications to Title font properties and patch width
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
if elm.name == "Legend":
leg_cim = lyt_cim.elements[1]
leg_cim.titleSymbol.symbol.height = 30
leg_cim.titleSymbol.symbol.horizontalAlignment = 'Center'
leg_cim.titleSymbol.symbol.fontStyleName = 'Bold'
leg_cim.titleSymbol.symbol.symbol.symbolLayers[0].color.values = [255,0,0,100]
for itm in reversed(elm.items): #Done in reversed order
itm.patchWidth = 50
lyt.setDefinition(lyt_cim)
#CIM modification to layer patch shape (it affects legend items)
m = p.listMaps('Overview Map')[0]
for itm in leg.items:
lyr = m.listLayers(itm.name)[0]
if lyr.symbology.renderer.type == 'UniqueValueRenderer':
lyr_cim = lyr.getDefinition('V3')
for grp in lyr_cim.renderer.groups: #Iterate through each group
for cls in grp.classes: #Iterate through each class
cls.patch = "AreaNaturalPoly" #Called Natural area in app
lyr.setDefinition(lyr_cim)