addItem

汇总

通过 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 访问 对内容进行细化访问。

语法

addItem()

属性

名称	说明	数据类型
anchor （只读）	返回表示当前锚点位置的以下字符串值之一。 要更改值，请使用 setAnchor 方法。 BOTTOM_LEFT_CORNER—左下角位置 BOTTOM_MID_POINT—底部中央位置 BOTTOM_RIGHT_CORNER—右下角位置 CENTER_POINT—中央位置 LEFT_MID_POINT—左侧中央位置 RIGHT_MID_POINT—右侧中央位置 TOP_LEFT_CORNER—左上角位置 TOP_MID_POINT—顶部中央位置 TOP_RIGHT_CORNER—右上角位置	String
columnCount （读取和写入）	图例中指定列的数量。 此属性仅在将 fittingStrategy 设置为 AdjustFontSize 、 AdjustFrame 或 ManualColumns 时适用。	Long
elementHeight （读取和写入）	元素的高度（以页面单位计）。	Double
elementPositionX （读取和写入）	元素的锚点位置的 x 位置。 分配或报告的单位为页面单位。	Double
elementPositionY （读取和写入）	元素的锚点位置的 y 位置。 分配或报告的单位为页面单位。	Double
elementRotation （读取和写入）	相对于锚点位置旋转元素。 正值表示顺时针旋转，负值表示逆时针旋转。	Double
elementWidth （读取和写入）	元素的宽度（以页面单位计）。	Double
fittingStrategy （读取和写入）	表示有效自适应策略方法的字符串。 有效值如下： AdjustFontSize—调整字号。 AdjustColumns—调整列。 AdjustColumnsAndFont—调整列和字号。 AdjustFrame—调整框架。 ManualColumns—手动列。	String
items （只读）	返回相关 LegendItem 类列表。 您不能直接设置此属性，但是，可以遍历图例项并修改其属性。	List
isOverflowing （只读）	如果图例中的所有内容均不在所提供几何的边界内，则返回 True 。 这种情况下，布局上通常会显示红色省略号。 该属性在 while 循环的上下文中效果很好。 它可以支持更改字体大小、适应策略或元素大小，直到所有内容均能容纳。	Boolean
locked （读取和写入）	设置为 True 时，无法在布局视图中以图形方式选择元素。	Boolean
longName （只读）	元素的全名，包括组信息（如果存在）。 例如，在一个名称为 Map Frame 的组元素中，名称为 Group Element 的元素将返回 longName 的 Group Element\\Map Frame 值。 如果元素不在组中，则 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})

您可以使用基本放置选项将 图层 添加到图例中。

名称	说明	数据类型
layer	对 Layer 对象（将要添加到图例中的图层表示为 LegendItem ）的引用。	Layer
add_position （可选）	此常数用于确定在图例内添加的图层的放置位置。 BOTTOM—在 TOC 图层堆叠底部放置单个或多个图层。 TOP—在 TOC 图层堆叠顶部放置单个或多个图层。 (默认值为 TOP)	String

返回值

数据类型	说明
LegendItem	LegendItem 对象。

applyStyleItem(style_item)

将 StyleItem 应用于 LegendElement 。

名称	说明	数据类型
style_item	A reference to a StyleItem in a project.	StyleItem

getDefinition(cim_version)

返回图例元素的 CIM 定义。

名称	说明	数据类型
cim_version	A string that represents the major version of the CIM that will be used. V2—The 2.x version of the CIM will be used. V3—The 3.x version of the CIM will be used.	String

返回值

数据类型	说明
Object	返回 LegendElement 值的 CIM 定义。

moveItem(reference_item, move_item, {move_position})

您可以将图例项移动到图例中的特定位置。

名称	说明	数据类型
reference_item	LegendItem 对象表示现有图例项，该项目用于确定移动 move_item 的相对位置。	LegendItem
move_item	对 LegendItem 对象（表示要移动的图层）的引用。	Layer
move_position （可选）	此常数用于确定移动的图层相对于参考图层的放置位置。 AFTER—将图例项移动到 reference_item 之后或之下。 BEFORE—将图例项移动到 reference_item 之前或之上。 (默认值为 BEFORE)	String

removeItem(remove_item)

允许您从图例中移除图例项。

名称	说明	数据类型
remove_item	对 LegendItem 对象（表示要移除的项目）的引用。	LegendItem

setAnchor(anchor)

setAnchor 方法可控制 LegendElement 的锚点位置。

名称	说明	数据类型
anchor	A string that specifies the location of the anchor position. BOTTOM_LEFT_CORNER—The anchor will be set at the bottom left corner position. BOTTOM_MID_POINT—The anchor will be set at the bottom center position. BOTTOM_RIGHT_CORNER—The anchor will be set at the bottom right corner position. CENTER_POINT—The anchor will be set at the center position. LEFT_MID_POINT—The anchor will be set at the left center position. RIGHT_MID_POINT—The anchor will be set at the right center position. TOP_LEFT_CORNER—The anchor will be set at the top left corner position. TOP_MID_POINT—The anchor will be set at the top center position. TOP_RIGHT_CORNER—The anchor will be set at the top right corner position.	String

setDefinition(definition_object)

设置图例元素的 CIM 定义。

名称	说明	数据类型
definition_object	A modified CIM definition object originally retrieved using getDefinition.	Object

代码示例

LegendElement 示例 1

以下脚本可向布局添加新图例并更新多个属性。 在添加图层文件之前，该脚本会关闭图层同步，以使地形色彩映射表不显示。 添加图层后，图层同步将再次打开。

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', key='*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")

LegendElement 示例 2

以下脚本可将 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'))

LegendElement 示例 3

以下脚本使用 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)