摘要
通过 MapsurroundElement 类，可以访问大小和定位属性，并引用与相关联的地图框。
说明
MapSurroundElement 为布局元素，它具有关联的 MapFrame 元素，并与地图框信息动态链接。 例如，指北针为地图整饰要素，与关联地图框的地图旋转链接；比例尺与地图的比例链接。 Layout 类上的 listElements 方法将返回包含所有可能布局元素的 Python 列表。 要仅返回 MapSurroundElement 对象的列表，应对 element_type 参数使用 MAPSURROUND_ELEMENT 常量。 还可以使用 wildcard 值，基于元素的 name 值对搜索进行进一步优化。 有必要确保为每个布局元素指定唯一名称，因为这样可以在 ArcPy 脚本中引用它。
MapSurroundElement 为通用对象，包含属性相对较少。 其中许多属性与地图整饰要素在布局中的大小和位置有关。 mapFrame 属性将返回一个对 MapFrame 对象的引用，使用该对象 map 属性，可以访问地图框的 map。
许多布局元素返回一个 type 值 MAPSURROUND_ELEMENT。 其中包括指北针、比例尺、图表框、表格框和其他可能当前没有具有特定属性的专用对象的未来元素类型。 可以使用 Python CIM 访问访问其中某些专用对象的属性。 以下代码示例提供了示例。 其中一个具有专用方法和属性的地图整饰要素示例为 LegendElement。 它返回一个 type 值为 LEGEND_ELEMENT 的元素。
警告：
在未来开发中，当前 type 值为 MAPSURROUND_ELEMENT 的对象可能成为其自己的专用对象类型，这可能会对元素 type 属性的值，以及适用于布局 listElements 方法的 element_type 枚举列表造成影响。
elementPositionX 和 elementPositionY 值取决于元素的锚点位置，该位置在格式选项卡上进行设置。 默认位置取决于地图整饰要素的类型。 例如，指北针的默认锚点位置为中心点，而比例尺的默认位置为左下角。
还可以使用 Layout 类的 createMapSurroundElement 方法创建地图整饰要素。 使用此方法，仅可根据 map_surround_type 输入参数创建地图整饰要素类型。 在创建过程中引用现有 StyleItem 元素也非常有用，这可以控制元素在布局中的外观。 示例如下。
属性
| 属性 | 说明 | 数据类型 |
| anchor (只读) | 返回表示当前锚点位置的以下字符串值之一。 要更改值，请使用 setAnchor 方法。
| String |
| elementHeight (可读写) | 元素的高度（以页面单位计）。 | Double |
| elementPositionX (可读写) | 元素的锚点位置的 x 位置。 分配或报告的单位为页面单位。 | Double |
| elementPositionY (可读写) | 元素的锚点位置的 y 位置。 分配或报告的单位为页面单位。 | Double |
| elementRotation (可读写) | 元素旋转角度（以度为单位）。 正值将使方向顺时针旋转，负值将使方向逆时针旋转。 注：此属性不适用于指北针，因为其旋转基于地图旋转。 | Double |
| elementWidth (可读写) |
元素的宽度（以页面单位计）。 | Double |
| locked (可读写) | 设置为 True 时，无法在布局视图中以图形方式选择元素。 | Boolean |
| longName (只读) | 元素的全名，包括组信息（如果存在）。 例如，在一个名称为 North Arrow 的组元素中，名称为 Group Element 的元素将返回 Group Element\\North Arrow 的 longName 值。 如果元素不在组中，则 longName 与 name 值相同。 | String |
| mapFrame (可读写) | 对关联 MapFrame 的引用。 | MapFrame |
| name (可读写) | 元素的名称。 必须确保所有元素均具有唯一名称，因为这样可以通过在 Layout 对象的 listElements 函数中使用 wildcard 参数以唯一方式引用这些元素。 | String |
| parentGroupElement (只读) | 如果元素在组中，则返回的值为 GroupElement，否则返回 NoneType。 | GroupElement |
| type (只读) | 返回值 MAPSURROUND_ELEMENT。 | String |
| visible (可读写) | 如果元素在布局上可见，则返回 True。 打印或导出之前，您可以打开和关闭元素的可见性，而不必从页面移除不需要的对象。 | Boolean |
方法概述
| 方法 | 说明 |
| applyStyleItem (style_item) | 将 StyleItem 应用于 MapSurroundElement。 |
| getDefinition (cim_version) | 返回地图整饰元素的 CIM 定义。 |
| setAnchor (anchor) | setAnchor 方法可控制 MapSurroundElement 值的锚点位置。 |
| setDefinition (definition_object) | 设置地图整饰元素的 CIM 定义。 |
方法
applyStyleItem (style_item)
当在 ArcGISProject 类上使用 listStyleItems 方法引用 StyleItem 时，style_class 参数必须是 NORTH_ARROW 或 SCALE_BAR。 有关详细信息和代码示例，请参阅 StyleItem 帮助主题。
注：
在使用 applyStyleItem 方法之前，必须先将样式添加到工程中。 可以在 ArcGISProject 类上使用 updateStyles 方法添加样式。
getDefinition (cim_version)
| 参数 | 说明 | 数据类型 |
cim_version | A string that represents the major version of the CIM that will be used.
| String |
| 数据类型 | 说明 |
| Object | 返回 MapsurroundElement 值的 CIM 定义。 |
有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。
setAnchor (anchor)
| 参数 | 说明 | 数据类型 |
anchor | A string that specifies the location of the anchor position.
| String |
设置锚点位置非常有用，因为您可以控制元素在调整大小时的展开方式。 例如，比例尺地图整饰要素元素的默认锚点位置为 BOTTOM_LEFT_CORNER。 如果将锚点位置更改为 TOP_RIGHT_CORNER，则更改 elementHeight 将使元素向下扩展，而非向上扩展；更改 elementWidth 将使元素向左扩展。
setDefinition (definition_object)
| 参数 | 说明 | 数据类型 |
definition_object | A modified CIM definition object originally retrieved using getDefinition. | Object |
有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。
代码示例
以下脚本查找名为 ScaleBar 的 MapsurroundElement，并将更改其位置，以使比例尺的中心点位于其关联地图框的下方和中心位置的 0.5 个页面单位处。 请注意，比例尺先前的锚点位置为中心位置。 地图框先前的锚点位置为左下角。
import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Points of Interest")[0]
scaleBar = lyt.listElements("MAPSURROUND_ELEMENT", "ScaleBar")[0]
mf = scaleBar.mapFrame
scaleBar.elementPositionX = mf.elementPositionX + (mf.elementWidth / 2)
scaleBar.elementPositionY = mf.elementPositionY - 0.5
aprx.save()
del aprx以下脚本使用 Esri 系统样式在布局上的某个点位置创建了一个指北针。 然后，它使用 Python CIM 访问修改了 calibrationAngle 值。
#Page units Centimeters
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]
naStyle = p.listStyleItems('ArcGIS 2D', 'North_Arrow', 'Compass North 1')[0]
na = lyt.createMapSurroundElement(arcpy.Point(18.5,18), 'North_Arrow', mf,
nArrowStyle, "Compass North Arrow")
na.elementWidth = 2
#CIM modifications - change calibration angle
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
if elm.name == "Compass North Arrow":
elm.northType = 'TrueNorth'
elm.calibrationAngle = -2.5
lyt.setDefinition(lyt_cim)以下脚本使用 Esri 系统样式在布局上创建了一个比例尺，并使用辅助函数创建了放置比例尺的矩形。 然后，它使用 Python CIM 访问修改了比例尺的分刻度和取整。
#Helper function to make an envelope from a lower left X, Y, width and height
def MakeRec_LL(llx, lly, w, h):
xyRecList = [[llx, lly], [llx, lly+h], [llx+w,lly+h], [llx+w,lly], [llx,lly]]
array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
rec = arcpy.Polygon(array)
return rec
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]
#Page units Centimeters
sbName = 'Double Alternating Scale Bar 1 Metric'
sbStyle = p.listStyleItems('ArcGIS 2D', 'Scale_bar', sbName)[0]
sbEnv = MakeRec_LL(1.5, 15, 8, 1)
sb = lyt.createMapSurroundElement(sbEnv, 'Scale_bar', mf, sbStyle, 'New Scale Bar')
#CIM modifications - change number of subdivisions and rounding
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
if elm.name == 'New Scale Bar':
elm.subdivisions = 2
elm.numberFormat.roundingOption = "esriRoundNumberOfSignificantDigits"
elm.numberFormat.roundingValue = 2
lyt.setDefinition(lyt_cim)以下脚本使用 Esri 系统样式在布局上创建了一个图例，并使用辅助函数创建了放置图例的矩形。 然后，它使用 Python CIM 访问修改了最小字体大小。
#Helper function to make an envelope from a upper left X, Y, width and height
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])
rec = arcpy.Polygon(array)
return rec
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]
#Page units Centimeters
legStyle = p.listStyleItems('ArcGIS 2D', 'Legend', 'Legend 3')[0]
legEnv = MakeRec_UL(1.5, 14, 18.5, 10)
sb = lyt.createMapSurroundElement(legEnv, 'Legend', mf, legStyle, 'New Legend')
#CIM modifications - change the minimum font size
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
if elm.name == 'New Legend':
if elm.fittingStrategy == 'AdjustColumnsAndSize':
elm.minFontSize = 8
lyt.setDefinition(lyt_cim)