TextElement

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

Объект 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.

  • 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
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)
ПараметрОписаниеТип данных
style_item

A reference to a StyleItem in a project.

StyleItem

При привязывании 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.

  • V2The 2.x version of the CIM will be used.
  • V3The 3.x version of the CIM will be used.
String
Возвращаемое значение
Тип данныхОписание
Object

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

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

setAnchor (anchor)
ПараметрОписаниеТип данных
anchor

A string that specifies an 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

Установка положения якоря позволяет вам управлять тем, как элемент может расширяться за счет дополнительного текста. Например, установка положения якоря к CENTER_POINT с помощью текста точки полезна для динамических строк, которые вы хотите сохранить центрированными, таких как заголовок в верхней части компоновки.

setDefinition (definition_object)
ПараметрОписаниеТип данных
definition_object

A modified CIM definition object originally retrieved using getDefinition.

Object

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

Пример кода

Пример 1 TextElement

Следующий скрипт заменяет 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()
TextElement, пример 2

Следующий скрипт создает компоновку и элемент текста, используя элемент системного стиля. Далее он изменяет положение точки якоря, чтобы при изменении размера текста он оставался по центру компоновки. Наконец, он изменяет размер текста под ширину компоновки с 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
TextElement, пример 3

Следующий скрипт создает карту, добавляет файл слоя и создает слой графики. Затем по каждому объекту в слое он создает текстовый элемент графики карты в зависимости от значения 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()
TextElement, пример 4

Следующий скрипт использует шаблон 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()
TextElement, пример 5

Следующий скрипт создает в новой компоновке графический и текстовый элементы прямоугольника. Строка текста сделана специально длинной, чтобы можно было продемонстрировать, как изменить размер текста, чтобы он поместился в прямоугольник. Функция используется для создания прямоугольника, а свойство 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
TextElement, пример6

Следующий скрипт создает в новой компоновке пользовательский графический и текстовый полигональный элемент. Строка текста намеренно длинная, чтобы с помощью свойства 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)
TextElement, пример 7

Этот скрипт строит графическую таблицу, основанную на значениях данных из таблицы в карте. Компоновка был создана с вертикальной линией с именем 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()