Краткая информация
Класс 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.
| 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 |
| mapFrame (чтение и запись) | Ссылка на связанный MapFrame. | MapFrame |
| name (чтение и запись) | Имя элемента. Важно, чтобы все элементы имели уникальное имя, благодаря чему на них было бы легко ссылаться по имени. | String |
| showTitle (чтение и запись) | Булево значение, определяющее, будет ли заголовок отображаться в легенде. | Boolean |
| syncLayerOrder (чтение и запись) | Булево значение, определяющее, будут ли элементы легенды в том же порядке, что и слои на карте. | Boolean |
| syncLayerVisibility (чтение и запись) | Булево значение, определяющее, будет ли элемент автоматически виден в легенде, если он виден на карте. | Boolean |
| syncNewLayer (чтение и запись) | Булево значение, определяющее, будет ли элемент автоматически добавлен в легенду, если он добавлен к карте. | Boolean |
| syncReferenceScale (чтение и запись) | Булево значение, определяющее, должны ли символы соответствовать масштабу символов на карте, если задан базовый масштаб. | Boolean |
| title (чтение и запись) | Текстовая строка, представляющая заголовок легенды. | String |
| type (только чтение) | Возвращает значение LEGEND_ELEMENT. | String |
| visible (чтение и запись) | Возвращает True, если элемент является видимым в компоновке. Вместо того чтобы удалять ненужные объекты со страницы перед печатью или экспортом, вы можете включать и выключать видимость элементов. | Boolean |
Обзор метода
| Метод | Описание |
| addItem (layer, {add_position}) | Позволяет добавить Слой в легенду, используя базовые свойства размещения. |
| 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.
getDefinition (cim_version)
| Параметр | Описание | Тип данных |
cim_version | A string that represents the major version of the CIM that 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 | Константа, которая определяет размещение перемещаемого слоя по отношению к базовому слою.
(Значение по умолчанию — 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.
| 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.
Пример кода
Следующий скрипт добавляет новую легенду в компоновку и обновляет несколько свойств. Перед добавлением файла слоя он отключает синхронизацию слоев, чтобы цветовая карта ландшафта не отображалась. После добавления слоя синхронизация слоев снова включается.
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)