LegendElement

摘要

通过 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' 为开头的属性可用于控制如何将项目添加到图例。 您也可以使用 fittingStrategycolumnCount 属性控制图例的外观。

elementPositionXelementPositionY 值取决于元素的锚点位置,该位置在格式选项卡上进行设置。 如果希望在添加图层时 LegendElement 对象向下延伸,请将锚点位置设置为左上角。 您可以使用 setAnchor 方法更改位置。

items 属性将返回 LegendItem 类列表。您可以单独对这些类进行修改,以进一步自定义图例的内容。 LegendElement 类还提供 AddItemMoveItemRemoveItem 方法,以便您管理图例中的项目。 LegendElementLegendItem 类仅提供对常用属性的访问权限。 可以使用 Python CIM 访问对内容进行细化访问。

属性

属性说明数据类型
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 设置为 AdjustFontSizeAdjustFrameManualColumns 时适用。

Long
elementHeight
(可读写)

元素的高度(以页面单位计)。

Double
elementPositionX
(可读写)

元素的锚点位置的 x 位置。 分配或报告的单位为页面单位。

Double
elementPositionY
(可读写)

元素的锚点位置的 y 位置。 分配或报告的单位为页面单位。

Double
elementRotation
(可读写)

相对于锚点位置旋转元素。 正值表示顺时针旋转,负值表示逆时针旋转。

Double
elementWidth
(可读写)

元素的宽度(以页面单位计)。

Double
fittingStrategy
(可读写)

表示有效自适应策略方法的字符串。 有效值如下:

  • AdjustFontSize调整字号。
  • AdjustColumns调整列。
  • AdjustColumnsAndFont调整列和字号。
  • AdjustFrame调整框架。
  • ManualColumns手动列。
String
items
(只读)

返回相关 LegendItem 类列表。 您不能直接设置此属性,但是,可以遍历图例项并修改其属性。

List
locked
(可读写)

设置为 True 时,无法在布局视图中以图形方式选择元素。

Boolean
longName
(只读)

元素的全名,包括组信息(如果存在)。 例如,在一个名称为 Group Element 的组元素中,名称为 Map Frame 的元素将返回 Group Element\\Map FramelongName 值。 如果元素不在组中,则 longNamename 值相同。

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

此常数用于确定在图例内添加的图层的放置位置。

  • BOTTOM在 TOC 图层堆叠底部放置单个或多个图层。
  • TOP在 TOC 图层堆叠顶部放置单个或多个图层。

(默认值为 TOP)

String
返回值
数据类型说明
LegendItem

LegendItem 对象。

addItem 方法用于将图层添加至布局中的图例。默认 add_position 可将图层添加到图例项列表的顶部,因此该图层显示在首位。有关更精确的图例项放置,请参阅 moveItem 方法。

applyStyleItem (style_item)
参数说明数据类型
style_item

A reference to a StyleItem in a project.

StyleItem

当在 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.

  • V2The 2.x version of the CIM will be used.
  • V3The 3.x version of the CIM 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

此常数用于确定移动的图层相对于参考图层的放置位置。

  • AFTER将图例项移动到 reference_item 之后或之下。
  • BEFORE将图例项移动到 reference_item 之前或之上。

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

  • BOTTOM_LEFT_CORNERThe anchor will be set at the bottom left corner position.
  • BOTTOM_MID_POINTThe anchor will be set at the bottom center position.
  • BOTTOM_RIGHT_CORNERThe anchor will be set at the bottom right corner position.
  • CENTER_POINTThe anchor will be set at the center position.
  • LEFT_MID_POINTThe anchor will be set at the left center position.
  • RIGHT_MID_POINTThe anchor will be set at the right center position.
  • TOP_LEFT_CORNERThe anchor will be set at the top left corner position.
  • TOP_MID_POINTThe anchor will be set at the top center position.
  • TOP_RIGHT_CORNERThe anchor will be set at the top right corner 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 访问

代码示例

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', '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)