LegendElement

Краткая информация

Класс LegendElement обеспечивает доступ к свойствам и методам для управления элементами легенды в компоновке.

Обсуждение

Объект LegendElement — это особый тип элемента компоновки MapSurroundElement. Он также имеет связь с объектом MapFrame, но обладает дополнительными свойствами, специфичными для легенд, включая доступ к объектам LegendItem. Метод listElements для объекта Layout возвращает список Python объектов элементов компоновки страницы. Чтобы получить список только объектов LegendElement, используйте константу LEGEND_ELEMENT для параметра element_type. Значение wildcard также может быть использовано для дальнейшей тонкой настройки поиска на основе значения name элемента. Присвойте каждому элементу компоновки страницы уникальное имя, чтобы на него можно было легко ссылаться.

Вы можете создавать легенды, используя метод createMapSurroundElement для объекта Layout с параметром 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.

  • 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
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})

Позволяет добавить Слой в легенду, используя базовые свойства размещения.

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

При привязывании StyleItem с помощью метода listStyleItems для класса ArcGISProject параметр style_class должен быть LEGEND. Обратитесь к разделу справки StyleItem для получения дополнительной информации и примеров кода.

Примечание:

Перед использованием метода applyStyleItem необходимо добавить стили в проект. Их можно добавить, используя метод updateStyles для класса ArcGISProject.

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

Возвращает определение CIM для значения LegendElement.

Более подробно о работе с CIM и примеры см. Доступ к CIM в Python.

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 Можно переместить или AFTER или BEFORE 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 и примеры см. Доступ к CIM в Python.

Пример кода

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)