arcpy.mapping常用四大件-MapsurroundElement

by 李远祥

        在arcpy.mapping 中，除了数据入口MapDocument、图层Layer之外，另一重要的角色就是MapsurroundElement。MapsurroundElement直接关系的就是地图的整饰元素。只要凑齐上述的这三大件，ArcGIS的制图自动化基本上就可以实现了。

        地图的整饰元素有很多，例如文本（标题及其他说明）、图例、比例尺、指北针、图片、外加图形等。利用arcpy.mapping 的MapsurroundElement类，可以做到对这些元素的布局进行精确的排布。

        接下来可以看看MapsurroundElement的一些属性和方法了。严格来说，MapsurroundElement没有方法，所有的设置都是在属性当中，下面是MapsurroundElement的官方帮助截图，从截图中可以看到其主要的作用。

        基本的属性设置，如整饰元素的位置、长宽级重命名都可以设置，以及一个parentDataFrameName用于识别其所在的dataframe（这个一般没什么作用，除非需要做接图表用到多个dataframe），从中可以看出，其主要功能在于整饰元素的识别及大小、位置调整。细节调整部分主要落在type上。这有点类似于上一章提到的Layer，type也是只读，但具体的可设置部分则在不同的包含对象中。其涉及到DATAFRAME_ELEMENT、GRAPHIC_ELEMENT、LEGEND_ELEMENT、MAPSURROUND_ELEMENT、PICTURE_ELEMENT、TEXT_ELEMENT这几类，全部都是继承了MapsurroundElement，所以，如果只是一般的是大小和位置操作，倒是通过name属性去识别，然后通过代码去调整元素的位置和大小。不同的类型也适当的增加一些可设置的属性，不过总体来说，可设置的属性也不多。

        这几个类中，有一个非常神秘的就是DATAFRAME_ELEMENT，笔者经历了好几个版本的ArcGIS帮助，都没能查到其说明，应该是一个预留的接口，从字面上来看，估计是能够设置经纬网的，但目前还没开放，看看帮助就知道了，其他几个类别都能找到其说明，就唯独缺少它的说明。

        GRAPHIC_ELEMENT 对应的就是通过【绘图】工具条绘制出来的图形，相对于MapsurroundElement基类，主要是增加了 isGroup（只读）属性，其用途，但目前作用不大，只是判读是否组合而已，连解除组合的方法都没有。方法上就是增加复制clone 和删除delete方法。

        LEGEND_ELEMENT 则对应的是图例的操作，图例对象是属性和方法最多的一个子类，autoAdd、items、title。其中items是只读的，返回表示图例项目名称的字符串的列表，并不能进行修改。而title则是可读写的属性，可以直接进行设置，还有一个就是autoAdd，这个是一个布尔值，用于决定新的图层加入进来后是否添加到图例中，其实际作用就是【图例】--【属性】--【常规】中的【新图层添加到地图时向图例添加新项】

图例的方法倒是开放了不少比较有用的功能，下面几个就是不错的方法

• adjustColumnCount (column_count) ： 设置图例的列数
• listLegendItemLayers () ：获取图例对应的图层列表
• removeItem (legend_item_layer, {index}) ：删除图例的某一项
• updateItem (legend_item_layer, {legend_item_style_item}, {preserve_item_sizes}, {use_visible_extent}, {show_feature_count}, {use_ddp_extent}, {index})  ：更新图例设置

        对于图例的这些操作方法，尚算让人满意吧，当然不可能将图例转换为图形这些操作加进去，毕竟arcpy定位的是粗粒度的操作，图例转图形这些就是放在AO上去代码编辑，都是比较麻烦的。

        PICTURE_ELEMENT是插入的图片对象，其中多出一项sourceImage属性，可以用来读取路径（很少人会天真的用来读取路径）和设置新的插入图片。除此之外，这个子类也没有具体的方法可以使用。

        TEXT_ELEMENT则是最常用的子类，所有的文本对象，包括静态的还是动态的文本对象都可以用它进行设置。其增加了angle、fontSize和text属性，基本上可以望文生义了。常用的就是进行文本内容和文本字体的修改。在方法上同样是增加了clone 和delete的操作。

        在所有的MapsurroundElement 中，眼尖点的人就会发现，没有任何的一个add或者create的字眼。因为MapsurroundElement对象不能通过代码进行创建，至少目前没有任何一个ArcGIS版本支持代码创建。这意味着在arcpy中，MapsurroundElement的使用范围只是限制在已经创建的整饰元素中。个人感觉就是Esri对arcpy.mapping的定位就是基于固定模版去做自动化制图，而不是通过代码级别去创建地图整饰元素。

接下来可以看看具体的代码调用方式。可以参考一下官方的例子，将布局视图中所有出现的2009 年全部替换为2010 年。

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for elm in arcpy.mapping.ListLayoutElements(mxd, "TEXT_ELEMENT"):
    if elm.text == "2009":
        elm.text = "2010"
mxd.save()
del mxd

        但一般来说，极少使用这种方式来进行替换文本值的。最常见的方式是通过对象的name来标识找到，指定到具体的对象。而获取整饰元素的方法可以使用ListLayoutElements ，返回的是一个数组，再通过元素在ArcMap中设定的对象名称也就是name来确定。例如如下的代码

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for elm in arcpy.mapping.ListLayoutElements(mxd, "TEXT_ELEMENT"):
    if elm.name == "tile_elm":
        elm.text = "修改后的标题"
mxd.save()
del mxd

        可见，在arcpy.mapping.ListLayoutElements方法中，是不带通过name参数直接指定对象的，都需要通过数组去查找。此外，还必须预先对元素对象命名，如下图，则是对标题文本设置了一个名称为【tile_name】

        其他整饰元素设置也是一样，其中最重要的原则就是在加入整饰元素的时候必须给一个元素名称，这是一种规范做法，不管后期是否使用arcpy进行调整。这样可以规避后期的一些修改。笔者曾经帮助过某一个用户解决过千张专题图的生产，其中一个非常重要的部分就是在后期修改整饰元素的位置，都是一些细微的操作，例如微调位置和修改文本值，如果一开始没有设置整饰元素的名称，那么后期面对上千个mxd，则是灾难性的工作。

总结：

        MapsurroundElement是非常好用的整饰元素对象，在制图自动化中给与了非常高的便利性。当然，它有固定的使用模式和场景，就是需要在一开始创建好元素对象，并且设置好其元素名称。由于这些对象不能通过代码去创建，因此，利用arcpy去做地图模版，那是不合理的。MapsurroundElement只是一种便利的辅助方法。

arcpy.mapping常用四大件-MapsurroundElement