Краткая информация
Объект TextElement обеспечивает доступ к свойствам и методам для управления элементами текстов в компоновке или в слое графики карты.
Обсуждение
Объект TextElement представляет собой текст, вставленный в компоновку или в графический слой карты. Он включает такие элементы, как текст, выноски, текст в прямоугольнике, заголовки и т.д. В него не входят текстовые строки, являющиеся частью легенды, рамки таблицы или другие элементы зарамочного оформления карты. Метод listElements для объекта Layout возвращает список Python из объектов элементов компоновки страницы. Затем для каждого элемента списка надо указать номер индекса, который будет ссылаться на определенный объект элемента страницы. Чтобы получить список только объектов TextElement, используйте константу TEXT_ELEMENT для параметра elementType. Значение wildcard также может быть использовано для дальнейшей тонкой настройки поиска на основе значения name элемента. Дайте каждому элементу текста уникальное имя, на которое можно будет легко ссылаться.
Существует два метода создания элементов текста. Первый - это метод createTextElement на объекте ArcGISProject, который позволяет создать текстовый элемент в компоновке или слое графики с использованием геометрии Point, Polygon или Polyline. Второй метод заключается в клонировании существующих текстовых элементов с помощью метода clone на объекте TextElement. Это удобно, поскольку в некоторых случаях проще начать с уже существующего элемента. При клонировании элемента укажите значение suffix, чтобы клонированные элементы можно было впоследствии легко распознать с помощью метода listElements, при котором используется групповой символ и такое же значение suffix. Возвращенный список элементов затем можно изменить или удалить с помощью метода delete.
Значения elementPositionX и elementPositionY базируются на положении якорной точки элемента, которое установлено на вкладке Формат в ArcGIS Pro. Положения якорных точек можно изменить с помощью метода setAnchor. Важно понимать разницу между свойствами elementRotation и textAngle. Наилучшим примером будет вставленный текст в прямоугольнике. Свойство elementRotation отвечает за поворот прямоугольника, а свойство textAngle управляет углом поворота текста в этом прямоугольнике. Для точечного текста оба значения синхронизированы вне зависимости от того, какой из свойств задано.
Для элементов текста предусмотрены методы getDefinition и setDefinition, которые позволяют изменять дополнительные свойства, недоступные классу TextElement. Более подробную информацию см. в разделе справки Доступ к CIM в Python.
Свойства
| Свойство | Описание | Тип данных |
| anchor (только чтение) | Возвращает одно из следующих строковых значений, которые описывают текущую позицию якоря. Чтобы изменить значение, используйте метод setAnchor.
| String |
| elementHeight (чтение и запись) | Высота элемента в единицах страницы. | Double |
| elementPositionX (чтение и запись) | x-положение позиции точки якоря элемента. Единицы измерения задаются или считываются в единицах страницы. | Double |
| elementPositionY (чтение и запись) | y-положение позиции точки якоря элемента. Единицы измерения задаются или считываются в единицах страницы. | Double |
| elementRotation (чтение и запись) | Угол поворота элемента в градусах. Положительные значения поворачивают по часовой стрелке, а отрицательные – против часовой стрелки. | Double |
| elementWidth (чтение и запись) | Ширина элемента в единицах страницы. | Double |
| fontFamilyName (чтение и запись) | Шрифт текстового символа, связанный с элементом. Примечание:Значение, отображаемое в раскрывающемся списке Имя шрифта на ленте, не всегда совпадает со свойством font_style_name. Вариативные шрифты содержат именованные экземпляры стилей шрифтов, их также можно настроить дополнительно. Перед тем как задать значение, можно установить его на ленте и просмотреть, каким будет возвращаемое значение свойства. | String |
| fontStyleName (чтение и запись) | В зависимости от шрифта стили могут включать нормальный, полужирный, курсив, сочетание этих вариантов или расширенный список. Примечание:Значение, отображаемое в раскрывающемся списке Стиль шрифта на ленте, не всегда совпадает со свойством font_style_name. Вариативные шрифты содержат именованные экземпляры стилей шрифтов, их также можно настроить дополнительно. Перед тем как задать значение, можно установить его на ленте и просмотреть, каким будет возвращаемое значение свойства. | String |
| isOverflowing (только чтение) | Возвращает True, если текст не помещается в границы предоставленной геометрии. Обычно это отображается красным многоточием в компоновке. Это позволяет изменить размер шрифта или увеличить геометрию, под которую подгоняется текст. | Boolean |
| locked (чтение и запись) | Если установлено значение True, элемент нельзя выбрать графически в виде компоновки. | Boolean |
| longName (только чтение) | Полное имя элемента, включая информацию о группе, если она существует. Например, элемент с именем 'Text' в групповом элементе с именем 'Group Element' вернет значение longName, равное 'Group Element\\Text'. Если элемент не входит в группу, longName будет таким же, как и значение name. | String |
| name (чтение и запись) | Имя элемента. Важно, чтобы все элементы имели уникальное имя, благодаря чему на них было бы легко ссылаться по имени. | String |
| parentGroupElement (только чтение) | Если элемент находится в группе, возвращаемым значением будет GroupElement, в противном случае будет возвращено NoneType. | GroupElement |
| text (чтение и запись) | Текстовая строка, связанная с элементом. | String |
| textAngle (чтение и запись) | Угол в градусах, на который поворачивается текстовая строка. Положительные значения поворачивают по часовой стрелке, а отрицательные – против часовой стрелки. | Double |
| textSize (чтение и запись) | Размер текста элемента в точках. | Double |
| type (только чтение) | Возвращает значение TEXT_ELEMENT. | String |
| visible (чтение и запись) | Указывает, виден ли элемент в компоновке или слое графики. | Boolean |
Обзор метода
| Метод | Описание |
| applyStyleItem (style_item) | Применяет StyleItem к TextElement. |
| clone ({suffix}) | Предоставляет механизм для клонирования существующего текстового элемента в компоновке страницы. |
| delete () | Обеспечивает механизм удаления существующего текстового элемента на странице компоновки. |
| getDefinition (cim_version) | Получает определение CIM текстового элемента. |
| setAnchor (anchor) | Метод setAnchor, управляющий положением якоря. |
| setDefinition (definition_object) | Задает определение CIM текстового элемента. |
Методы
applyStyleItem (style_item)
При привязывании StyleItem с помощью метода listStyleItems для класса ArcGISProject параметр style_class должен быть TEXT. Обратитесь к разделу справки StyleItem для получения дополнительной информации и примеров кода.
Примечание:
Перед использованием метода applyStyleItem необходимо добавить стили в проект. Их можно добавить, используя метод updateStyles для класса ArcGISProject.
clone ({suffix})| Параметр | Описание | Тип данных |
suffix | Дополнительная строка, использующаяся для добавления тега к созданным текстовым элементам. Новый элемент получает имя родительского элемента, суффикс и числовой секвенсер. Например, если имя родительского элемента FieldLabel и у suffix значение равно _copy, клонированные элементы будут называться FieldLabel_copy, FieldLabel_copy_1, FieldLabel_copy_2 и т.п. А если suffix не указан, результаты будут выглядеть как FieldLabel_1, FieldLabel_2, FieldLabel_3 и т.п. | String |
Сгруппированные текстовые элементы копировать нельзя. Все сгруппированные элементы являются графическими. Проверьте, не является ли графический элемент групповым, с помощью свойства isGroup объекта GraphicElement.
delete ()
Может понадобиться удалить существующие или клонированные текстовые элементы. Клонированным элементам при создании можно присваивать собственный suffix, чтобы их можно было легко найти с помощью параметра wildcard для метода listElements на объекте Layout .
getDefinition (cim_version)
| Параметр | Описание | Тип данных |
cim_version | A string that represents the major version of the CIM that will be used.
| String |
| Тип данных | Описание |
| Object | Возвращает определение CIM для TextElement. |
Более подробно о работе с CIM и примеры использования см. в разделе Доступ к Python CIM.
setAnchor (anchor)
| Параметр | Описание | Тип данных |
anchor | A string that specifies an anchor position.
| String |
Установка положения якоря позволяет вам управлять тем, как элемент может расширяться за счет дополнительного текста. Например, установка положения якоря к CENTER_POINT с помощью текста точки полезна для динамических строк, которые вы хотите сохранить центрированными, таких как заголовок в верхней части компоновки.
setDefinition (definition_object)
| Параметр | Описание | Тип данных |
definition_object | A modified CIM definition object originally retrieved using getDefinition. | Object |
Более подробно о работе с CIM и примеры см. Доступ к CIM в Python.
Пример кода
Следующий скрипт заменяет 2022 на 2023 во всех содержащих год строках текстовых элементов компоновки и во всех компоновках проекта.
import arcpy
search_text = '2022'
replace_text = '2023'
p = arcpy.mp.ArcGISProject(r'C:\Projects\YosemiteNP\Yosemite.aprx')
for lyt in p.listLayouts():
for txt in lyt.listElements('TEXT_ELEMENT'):
if search_text in txt.text:
print(f'For element: "{txt.name}" in layout: "{lyt.name}"')
print(f' Replacing: "{txt.text}"')
txt.text = txt.text.replace(search_text, replace_text)
print(f' With: "{txt.text}"')
print('')
p.save()Следующий скрипт создает компоновку и элемент текста, используя элемент системного стиля. Далее он изменяет положение точки якоря, чтобы при изменении размера текста он оставался по центру компоновки. Наконец, он изменяет размер текста под ширину компоновки с 10%-ным отступом от краев.
p = arcpy.mp.ArcGISProject('current')
#Create a layout
lyt = p.createLayout(8.5, 11, 'INCH', 'New Layout with Point Text')
lyt.openView()
#Create point text element using a system style item
txtStyleItem = p.listStyleItems('ArcGIS 2D', 'TEXT', 'Title (Serif)')[0]
ptTxt = p.createTextElement(lyt, arcpy.Point(4.25, 10), 'POINT',
'Fit My Title To Layout Width, Less 10%',
10, style_item=txtStyleItem)
#Change the anchor position and reposition the text to center
ptTxt.setAnchor('Center_Point')
ptTxt.elementPositionX = 4.25
ptTxt.elementPositionY = 10
#Adjust text size to fit the width of the layout
while ptTxt.elementWidth < (lyt.pageWidth - (lyt.pageWidth * 0.1)):
ptTxt.textSize = ptTxt.textSize + 0.1Следующий скрипт создает карту, добавляет файл слоя и создает слой графики. Затем по каждому объекту в слое он создает текстовый элемент графики карты в зависимости от значения name объекта.
p = arcpy.mp.ArcGISProject('current')
#Create a map, add a layer file and create a graphics layer
m = p.createMap('New Map with Text Graphics', 'Map')
lyrFile = arcpy.mp.LayerFile(r'C:\Projects\GreatLakes\GreatLakes_CenterPts.lyrx')
m.addLayer(lyrFile)
lyr = m.listLayers('GreatLakes_CenterPoint')[0]
gl = m.createGraphicsLayer('New Graphics Layer')
#Create a map graphic at each point location using each feature's name value
txtStyleItem = p.listStyleItems('ArcGIS 2D', 'TEXT', 'Water (Large)')[0]
for row in arcpy.da.SearchCursor(lyr, ['SHAPE@XY', 'NAME']):
x, y = row[0]
txt = p.createTextElement(gl, arcpy.Point(x,y), 'POINT', row[1])
m.openView()Следующий скрипт использует шаблон JSON для создания кривой (дуги) и геометрии Безье. Эта геометрия используется для создания двух графических элементов и двух текстовых элементов в новой компоновке. Дополнительно доступ к Python CIM используется для изменения свойств кривой Безье. Дополнительные сведения о создании геометрических объектов с использованием JSON см. в разделе справки для разработчиков Геометрические объекты.
p = arcpy.mp.ArcGISProject('current')
lyt = p.createLayout(6, 3, 'INCH', 'New Layout with 2 curves')
#Construct a curve/arc graphic element using a default symbol
arcPath = {"curvePaths" : [[[3.5,1.25],{"c" : [[5,1.25],[4.25, 1.75]]}]]}
arc = arcpy.AsShape(arcPath, esri_json=True)
arcGra = p.createGraphicElement(lyt, arc, name='ArcPy_Arc')
arcTxt = p.createTextElement(lyt, arc, 'LINE', 'Arc-e-Text', 24, 'Comic Sans MS', name='ArcPy_ArcText')
#Construct a bezier curve graphic element using a system style item
curveStyle = p.listStyleItems('ArcGIS 2D', 'Line', 'Dashed 1 Long 1 Short')[0]
curvePath = {"curvePaths" : [[[1.25,1.25],
{"b" : [[3,1.5],[1.6875,2.75],[2.125,0]]}]]}
curve = arcpy.AsShape(curvePath, esri_json=True)
curveGra = p.createGraphicElement(lyt, curve, curveStyle, 'ArcPy_Curve')
curveTxt = p.createTextElement(lyt, curve, 'LINE', 'Curved text', 24, 'Comic Sans MS', name='ArcPy_CurveText')
#Optional CIM modification
curveTxt_cim = curveTxt.getDefinition('V3')
curveTxt_cim.symbol.symbol.verticalAlignment = 'Center'
curveTxt.setDefinition(curveTxt_cim)
lyt.openView()Следующий скрипт создает в новой компоновке графический и текстовый элементы прямоугольника. Строка текста сделана специально длинной, чтобы можно было продемонстрировать, как изменить размер текста, чтобы он поместился в прямоугольник. Функция используется для создания прямоугольника, а свойство isOverflowing - для того, чтобы определить, поместится ли текст в данную геометрию.
def MakeRec_UL(ulx, uly, w, h):
xyRecList = [[ulx, uly], [ulx+w, uly], [ulx+w,uly-h], [ulx,uly-h], [ulx,uly]]
array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
rect = arcpy.Polygon(array)
return rect
p = arcpy.mp.ArcGISProject('current')
#Create a layout
lyt = p.createLayout(8.5, 11, 'INCH', 'New Layout with Rectangle Text')
lyt.openView()
#Rectangle Text
text = '''THIS TEXT WILL BE REDUCED UNTIL ALL THE TEXT FITS IN THE RECTANGLE AREA.
AGAIN - THIS TEXT WILL BE REDUCED UNTIL ALL THE TEXT FITS IN THE RECTANGLE AREA.
AND AGAIN - THIS TEXT WILL BE REDUCED UNTIL ALL THE TEXT FITS IN THE RECTANGLE AREA.'''
recTxt = p.createTextElement(lyt, MakeRec_UL(0.5, 10.5, 7.5, 1), 'POLYGON',
text, 25, 'Arial', 'Regular', name='ArcPy_RecText')
#Reduce text to fix rectangle
while recTxt.isOverflowing:
recTxt.textSize = recTxt.textSize - 1Следующий скрипт создает в новой компоновке пользовательский графический и текстовый полигональный элемент. Строка текста намеренно длинная, чтобы с помощью свойства isOverflowing можно было продемонстрировать, как она накладывается на данную геометрию, а также как изменяется размер текста, чтобы он соответствовал форме этой геометрии. Скрипт также показывает, как с помощью доступа Python CIM установить фон и символы границы текстового элемента.
p = arcpy.mp.ArcGISProject('current')
#Create a layout
lyt = p.createLayout(8.5, 11, 'INCH', 'New Layout with Polygon Text')
lyt.openView()
#Polygon Text
polyCoords = [[0.5, 10], [4.25, 10], [4.25, 9.5], [8, 9.5], [8, 8.5], [0.5, 8.5], [0.5, 10]]
polyShp = arcpy.Polygon(arcpy.Array([arcpy.Point(*coords) for coords in polyCoords]))
text = 'Some Text String that is really long and is <BOL>forced to wrap to other \
lines</BOL> so that we can see how it fits the polygon shape provided to the function.'
polyTxt = p.createTextElement(lyt, polyShp, 'POLYGON', text, 25,
'Arial', 'Regular', name='ArcPy_PolygonText')
#Reduce text to fit shape
while polyTxt.isOverflowing:
polyTxt.textSize = polyTxt.textSize - 1
#OPTIONAL CIM modifications
polyTxt_cim = polyTxt.getDefinition('V3')
#CIM Change text color
polyTxt_cim.symbol.symbol.symbol.symbolLayers[0].color.values = [0,0,255,100]
#CIM Create a graphic frame background symbol
bgRGBColor = arcpy.cim.CreateCIMObjectFromClassName('CIMRGBColor', 'V3')
bgRGBColor.values = [225, 225, 225, 100]
bgSolidFillLyr = arcpy.cim.CreateCIMObjectFromClassName('CIMSolidFill', 'V3')
bgSolidFillLyr.color = bgRGBColor
bgPolySym = arcpy.cim.CreateCIMObjectFromClassName('CIMPolygonSymbol', 'V3')
bgPolySym.symbolLayers = [bgSolidFillLyr]
bgSymRef = arcpy.cim.CreateCIMObjectFromClassName('CIMSymbolReference', 'V3')
bgSymRef.symbol = bgPolySym
GraphicFrame = arcpy.cim.CreateCIMObjectFromClassName('CIMGraphicFrame', 'V3')
GraphicFrame.backgroundSymbol = bgSymRef
#CIM Create a graphic frame border symbol
brdRGBColor = arcpy.cim.CreateCIMObjectFromClassName('CIMRGBColor', 'V3')
brdRGBColor.values = [255, 0, 0, 100]
brdSolidStrokeLyr = arcpy.cim.CreateCIMObjectFromClassName('CIMSolidStroke', 'V3')
brdSolidStrokeLyr.color = brdRGBColor
brdSolidStrokeLyr.miterLimit = 10
brdSolidStrokeLyr.width = 5
brdLineSym = arcpy.cim.CreateCIMObjectFromClassName('CIMLineSymbol', 'V3')
brdLineSym.symbolLayers = [brdSolidStrokeLyr]
brdSymRef = arcpy.cim.CreateCIMObjectFromClassName('CIMSymbolReference', 'V3')
brdSymRef.symbol = brdLineSym
GraphicFrame.borderSymbol = brdSymRef
polyTxt_cim.frame = GraphicFrame
polyTxt.setDefinition(polyTxt_cim)Этот скрипт строит графическую таблицу, основанную на значениях данных из таблицы в карте. Компоновка был создана с вертикальной линией с именем vertLine, горизонтальной линией с именем horzLine и текстовым элементом cellText. Каждый из этих элементов был создан с необходимыми свойствами символов и текста. Якорные точки элемента были установлены в верхнее левое положение, и выполнено верхнее левое выравнивание текстового элемента по вертикали и по горизонтали.
def MakeRec_LL(llx, lly, w, h):
xyRecList = [[llx, lly], [llx, lly+h], [llx+w,lly+h], [llx+w,lly], [llx,lly]]
xyRecList = [[1,1],[1, 2], [2.75, 2], [2.75, 1], [1, 1]]
array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
rec = arcpy.Polygon(array)
return rec
p = arcpy.mp.ArcGISProject('CURRENT')
#Create a layout
lyt = p.createLayout(6, 3, 'INCH', 'New Layout with Rectangles')
#Construct a pre-defined rectangle graphic element using a system style item
# and a rectangle function that takes x/y min/max and a width/height
# using the lower left corner as a start location
polyStyle = p.listStyleItems('ArcGIS 2D', 'Polygon', 'Orchard')[0]
p.createPredefinedGraphicElement(lyt, MakeRec_LL(1, 1, 1.75, 1), 'RECTANGLE',
polyStyle, 'ArcPy_Rectangle_Env',
lock_aspect_ratio=False)
#Construct the same element above using a point location
rec = p.createPredefinedGraphicElement(lyt, arcpy.Point(3, 1), 'RECTANGLE',
polyStyle, 'ArcPy_Rectangle_Pt',
lock_aspect_ratio=False)
rec.elementWidth = 1.75
rec.elementHeight = 1
lyt.openView()