GraphicElement

摘要

GraphicElement 对象提供了对属性和方法的访问，属性用于在页面布局上重新定位图形元素，而方法用于复制和删除现有图形元素。

说明

对添加到页面布局中的大多数通用元素来说，GraphicElement 是一种万能型元素类型。它包含了可添加到页面布局中的各种项目（如元素组、点、线和区域形状等）。对图形元素执行的最常见操作是获取或设置其页面布局的位置和大小。Layout 对象上的 listElements 方法将返回页面布局元素对象的 Python 列表。随后需要遍历列表中的每个项目，或指定一个索引号以引用具体的页面元素对象。要仅返回 GraphicElements 列表，请对 element_type 参数使用 GRAPHIC_ELEMENT 常量。您可使用通配符根据元素名对搜索过程进行优化。有必要确保每个页面布局元素均具有唯一的名称，因为这样可以使用 ArcPy 脚本轻松进行区分。

listElements 方法将返回展开的元素列表。例如，对表示一组三个文本元素的图形元素执行 listElements 将返回四个元素：组元素和每个单独的文本元素。GraphicElement 可用于同时对所有项目重新定位，也可以分别管理文本元素的文本值。

所有分组元素都将被当作图形元素。无法克隆分组的图形元素，因为这些元素可能不仅仅包括图形或文本元素。它们还可能包括其他项目，例如指北针和比例尺等。在克隆图形元素前可使用 isGroup 属性确定图形元素是否为组元素。

可以复制和删除现有图形元素。添加此功能的初衷是为了支持在页面布局中创建动态图表，布局中的表中的每个单元格都可使用线图形进行描画。要实现此目的，至少需使用两种线图形元素制作布局：垂直线和水平线。从表格中读取信息后，可以使用 clone 方法克隆这些线，同时，可使用其他图形元素定位属性调整其位置和大小。克隆元素时，提供一个 suffix 值将会非常有用，因为在使用 ListLayoutElements 函数时如果结合 wildcard 和该 suffix 值，可以轻易识别出克隆的元素。可以使用 delete 方法进一步修改或删除返回的元素列表。下面列出了一个构建动态图表的完整代码示例。

elementPositionX 和 elementPositionY 值取决于元素的锚点位置，可在格式选项卡上对选定元素进行设置。

属性

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

方法概述

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

方法

clone ({suffix})

参数	说明	数据类型
suffix	用于标记每个新建图形元素的可选字符串。新元素的元素名为父项图形元素加上 suffix 值以及数值定序符。例如，如果父元素名称为 Line 且 suffix 值为 _copy，则新克隆的元素的名称为 Line_copy、Line_copy_1、Line_copy_2 等。如果未提供 suffix，则名称类似于 Line_1、Line_2、Line_3 等。	String

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

delete ()

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

代码示例

GraphicElement 示例 1

以下脚本将名为 Title Block 的组元素移动到页面布局上的新位置，然后保存更改。

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Main attractions*")[0]
elm = lyt.listElements("GRAPHIC_ELEMENT", "Title Block")
elm.elementPositionX = 4.75
elm.elementPositionY = 10.5
aprx.save()
del aprx

GraphicElement 示例 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