TextElement

摘要

可通过 TextElement 对象访问用于在页面布局中重新定位文本以及修改文本字符串和字体大小的属性。

说明

TextElement 对象表示在页面布局中插入的文本。其中包括文本、注释、矩形文本、标题等项目。还包括组元素中的文本字符串。但不包括属于图例或插入表的一部分的文本字符串。Layout 对象上的 listElements 方法用于返回页面布局元素对象的 Python 列表。随后需要遍历列表中的每个项目，或指定一个索引号以引用具体的页面元素对象。要仅返回 TextElements 的列表，应对 elementType 参数使用 TEXT_ELEMENT 常量。还可以使用 wildcard 对基于元素 name 的搜索进行进一步优化。有必要确保每个页面布局元素均具有唯一的名称，因为这样可以使用 ArcPy 脚本轻松进行区分。

TextElement 具有 text 属性，这是它与其他大多数页面元素唯一不同之处。可使用此属性修改字符串。

可以克隆和删除文本元素。添加此功能的初衷是为了支持创建动态图形表。要实现这一目的，必须使用唯一的具有相应符号系统的文本元素集合预先制作一个布局。例如，如果列字段名称与单元值之间的文本属性设置不同，则需要创作两个文本元素，一个文本元素对应一种文本样式。从表中读取信息后，可以使用 clone 方法克隆文本元素，然后使用其他文本定位属性在布局上进行正确定位。克隆元素时，建议提供 suffix 值，这样可以在将 listElements 函数与 wildcard 和同一 suffix 值搭配使用时识别克隆元素。可以使用 delete 方法进一步修改或删除返回的元素列表。

elementPositionX 和 elementPositionY 值取决于元素的锚点位置，该位置在 ArcGIS Pro 中的格式选项卡上进行设置。

了解 elementRotation 与 textAngle 之间的差异至关重要。建议以插入矩形文本为例。elementRotation 属性用于控制矩形的旋转角度，而 textAngle 属性用于控制矩形内文本的角度。对于点文本，无论设置何种属性，这两个值均将进行同步。

属性

属性	说明	数据类型
elementHeight (可读写)	元素的高度（以页面单位计）。	Double
elementPositionX (可读写)	元素的锚点位置的 x 位置。分配或报告的单位为页面单位。	Double
elementPositionY (可读写)	元素的锚点位置的 y 位置。分配或报告的单位为页面单位。	Double
elementRotation (可读写)	元素的旋转角度（以度为单位）。正值将使方向顺时针旋转，负值将使方向逆时针旋转。	Double
elementWidth (可读写)	元素的宽度（以页面单位计）。	Double
name (可读写)	元素的名称。有必要确保所有元素均具有唯一名称，因为这样可以轻松对其进行引用。	String
text (可读写)	与元素相关联的文本字符串。	String
textAngle (可读写)	用于旋转文本字符串的角度值（以度为单位）。正值将使方向顺时针旋转，负值将使方向逆时针旋转。	Double
textSize (可读写)	元素文本大小（以点为单位）。	Double
type (只读)	返回 TEXT_ELEMENT 的值。	String
visible (可读写)	如果元素在布局上可见，则返回 True。进行打印或导出前，您可以切换元素的可见性，而不是从页面中移除不需要的对象。	Boolean

方法概述

方法	说明
clone ({suffix})	提供了一种克隆页面布局中现有文本元素的机制。
delete ()	提供了一种删除页面布局中现有文本元素的机制。

方法

clone ({suffix})

参数	说明	数据类型
suffix	用于标记每个新建文本元素的可选字符串。新元素的元素名称为父项文本元素的元素名称加上 suffix 值以及数值定序符。例如，如果父元素名称为 FieldLabel 且 suffix 值为 _copy，则新克隆的元素的名称为 FieldLabel_copy、FieldLabel_copy_1、FieldLabel_copy_2 等。如果未提供 suffix，则名称类似于 FieldLabel_1、FieldLabel_2、FieldLabel_3 等。	String

无法克隆分组的文本元素。所有分组元素都是图形元素类型。使用 GraphicElement 对象中的 isGroup 属性验证图形元素是否分组。

delete ()

可能需要删除现有或已克隆的文本元素。创建克隆元素时，可为克隆元素指定自定义 suffix，以便在对 Layout 对象上的 listElements 方法使用通配符参数时可轻松找到这些元素。

代码示例

TextElement 示例 1

以下脚本将 2013 年出现的事件全部替换为 2014 年。

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
for lyt in aprx.listLayouts():
    for elm in lyt.listElements("TEXT_ELEMENT"):
        if elm.text == "2013":
            elm.text = "2014"
aprx.save()
del aprx

TextElement 示例 2

下面的脚本将通过地图中的表构建基于数据值的图表。布局使用名为 vertLine 的垂直线、名为 horzLine 的水平线和名为 cellText 的文本元素进行创作。每个元素使用相应的符号系统和文本属性进行创作。元素的锚点设在左上方位置，文本元素的垂直和水平对齐方式则设为靠上和靠左。

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")

#Reference items in the project
m = aprx.listMaps("Yosemite National Park")[0]
lyr = m.listLayers("Valley_Pts")[0]
lyt = aprx.listLayouts("Points of Interest")[0]
horzLine = lyt.listElements("GRAPHIC_ELEMENT", "horzLine")[0]
vertLine = lyt.listElements("GRAPHIC_ELEMENT", "vertLine")[0]
tableText = lyt.listElements("TEXT_ELEMENT", "cellText")[0]

#Get/set information about the table
numRows = int(arcpy.GetCount_management(lyr).getOutput(0))
rowHeight = 0.2
fieldNames = ["COMPLEXID", "NAME"]
numColumns = len(fieldNames)
colWidth = 1.5

#Build graphic table lines based on upper left coordinate
#  set the proper size of the original, parent line, then clone it and position appropriately
upperX = 1.0
upperY = 5.0

#Vertical lines
vertLine.elementPositionX = upperX
vertLine.elementPositionY = upperY
vertLine.elementHeight =  (rowHeight * numRows) + rowHeight #extra line for column names

x = upperX
for vert in range(1, numColumns+1):
  x = x + colWidth
  vert_clone = vertLine.clone("_clone")
  vert_clone.elementPositionX = x

#Horizontal lines
horzLine.elementPositionX = upperX
horzLine.elementPositionY = upperY
horzLine.elementWidth = numColumns * colWidth

y = upperY - rowHeight
for horz in range(1, numRows +2 ):  #need to accommodate the extra line for field names
  temp_horz = horzLine.clone("_clone")
  temp_horz.elementPositionY = y
  y = y - rowHeight

#Place text column names
tableText.elementPositionX = upperX + 0.05 #slight offset
tableText.elementPositionY = upperY
tableText.text = fieldNames[0]
accumWidth = colWidth
for field in range(1, numColumns):
  newFieldTxt = tableText.clone("_clone")
  newFieldTxt.text = fieldNames[field]
  newFieldTxt.elementPositionX = newFieldTxt.elementPositionX + accumWidth
  accumWidth = accumWidth + colWidth

#Create text elements based on values from the table
table = arcpy.SearchCursor(lyr.dataSource)
y = upperY - rowHeight
for row in table:
  x = upperX + 0.05 #slight offset
  try:   
    for field in fieldNames:
      newCellTxt = tableText.clone("_clone")
      newCellTxt.text = row.getValue(field)
      newCellTxt.elementPositionX = x
      newCellTxt.elementPositionY = y
      accumWidth = accumWidth + colWidth
      x = x + colWidth
    y = y - rowHeight
  except:
    print("Invalid value assignment")

#Export to PDF and delete cloned elements
lyt.exportToPDF(r"C:\Temp\test.pdf")

for elm in lyt.listElements(wildcard="_clone"):
  elm.delete()
del aprx