简介ArcGIS Python Add-In 入门源码与教程面向需要利用 Python 扩展 ArcGIS Desktop 的 GIS 工程师和二次开发初学者围绕自定义工具、菜单与面板的快速开发需求提供一份从零到一的实操指引。压缩包共包含 7 个文件由 pdf 开发说明、两个 py 脚本、esriaddin 扩展包、xml 配置文件、txt 说明文档以及示例位图文件组成整体大小仅 142KB轻量便捷。目前已有 1216 人浏览学习是被多次验证的入门资料。内容详细覆盖了开发环境搭建、Add-In 组件创建、XML 用户界面配置、ArcPy 脚本编写、Add-In Manager 调试以及打包分发等完整流程教程还特别说明了如何利用 Python 常用库强化空间分析能力。配套的源码模板不是孤立代码而是与 xml、esriaddin 文件联动的可运行项目读者可通过对照 PDF 文档理解各个文件的作用直接在模板上修改快速生成自己的 GIS 工具适用于个人学习、团队内部分享和项目原型搭建。 ArcGIS Python Add-In我最早接触它是在做内业批量处理的时候。当时每天要在ArcMap里重复做同一套操作打开属性表、筛选、计算、导出点得手酸。后来花了一个周末用Python写了个小插件把整个流程缩成工具栏上一个按钮点一下就全跑完。那感觉就像终于给自己配了个“自动化小弟”。这篇文章要讲的就是怎么从零开始做一个ArcGIS Python Add-In包括源码结构、核心写法、打包分发以及我一路踩过的坑。适合刚接触GIS二次开发、想在ArcMap里自定义工具按钮的从业者和学生参考。1. 为什么还要折腾Add-In1.1 它能帮你把“重复劳动”变成“点一下”ArcGIS Desktop 10.x 时代给ArcMap加一个自定义按钮传统路线是写.NET或Java组件各种COM注册、DLL引用没接触过的光看教程就能劝退。Python Add-In把这件事拉低到了一个非常友好的门槛按钮、工具、菜单、工具条本质上都是Python脚本包了一层“壳”壳负责把按钮画在界面上脚本负责干实际活。我拿它做过最典型的几类事情批量出图、按字段拆分数据、自动检查拓扑错误、批量坐标系转换、统计选中要素面积并导出Excel。以前需要在工具箱里翻半天再一步步执行的操作封装成Add-In以后同事只需要记住“点那个按钮”就行。说句实话这种开发模式特别适合内业岗、数据处理岗的人自给自足不用依赖开发部门排期。1.2 和ArcGIS Pro的Add-In比怎么选很多人在网上查资料会看到ArcGIS Pro的Add-In用的工具链和桌面版完全不一样。我直接用实际体验对比一下方便你判断自己该学哪条路线对比项桌面版 Python Add-InArcGIS Pro Add-In适配平台ArcGIS Desktop 10.xArcGIS Pro开发语言Python 2.7 arcpyC#/PythonPro 3.x后主要靠ArcGIS Pro SDKUI描述方式config.xml 声明式配置.NET构建面板/按钮打包分发makeaddin.py 生成 .esriAddIn生成 .ppkx上手难度较低纯Python能搞定较高需要接触Visual Studio或Pro SDK适用场景存量环境、老项目维护、快速自用工具新项目、大数据、三维场景我的态度很明确如果单位还在用ArcMap 10.x桌面版Add-In就是性价比最高的自研工具方案如果新项目已经在ArcGIS Pro上跑那就别花大力气学这套老壳子了直接把arcpy处理逻辑抽出来迁到Pro的脚本工具里去。文章后面给的源码思路其实两头都能用。2. 开发环境与前置准备2.1 ArcGIS Desktop与Python版本必须对上ArcGIS Desktop 10.0捆绑的是Python 2.610.1到10.8.2捆绑的是Python 2.7。Add-In开发绕不开这个版本约束因为ArcMap进程内加载Python插件时用的就是安装ArcGIS时自带的那个Python环境。这就带来一个必须接受的现实在桌面版Add-In里你写的是Python 2.7语法不是3.x。代码里常见的差异点包括print是语句不是函数except后面要写except Exception, e:而不是as e字符串默认是byte字符串中文处理要格外小心。我见过不少朋友把所有精力花在按钮逻辑上结果被一个中文字符编码问题卡了半天所以后面会专门写一节编码避坑。另外要注意32位和64位的问题。ArcMap本身是32位程序Add-In跑在ArcMap进程里用的自然是32位Python。ArcGIS有一个“64位后台地理处理补丁”那个Python是64位的但Add-In不能依赖它。大数据量处理时Add-In更适合先把任务写进脚本工具再通过GP服务或批处理后台跑别在按钮里一次性塞几千万要素的密集运算。2.2 装好环境避开Win11兼容性坑网上经常有人问“ArcGIS Desktop 10.8.2与Win11不兼容怎么办”。我实测下来的情况是大部分功能能跑但偶尔会遇到启动慢、界面控件异常、或者Add-In管理器加载不稳定的问题。比较有效的处理顺序是先安装ArcGIS Desktop 10.8.2的官方补丁和更新包很多兼容性问题在补丁里已经修了。如果启动还异常右键ArcMap快捷方式用“兼容性疑难解答”选Windows 8兼容模式运行。还解决不了最省心的方案是换到ArcGIS Pro环境把老工具迁移过去。配合检查一下机器上是否已经装好Python 2.7和arcpy。正常装完ArcGIS Desktop后ArcMap自带的Python会在类似C:\Python27\ArcGIS10.8的目录下可以直接在命令行运行python验证。Add-In开发本身不要求单独安装Python直接用内置的就好也不用额外配IDE记事本、VSCode、PyCharm都可以。2.3 Add-In Wizard生成骨架的神器开发Add-In最推荐的起步方式是先装“Python Add-In Wizard”一个很小的向导程序用来生成项目骨架。官网和镜像站都能下载到对应ArcGIS版本的版本安装后桌面会出现快捷方式。它会在你填完项目信息后自动生成一整套文件夹和示例代码省去手写config.xml的麻烦。我不太建议一上来就手写全套文件因为Add-In对config.xml里的节点格式比较敏感少一个标签或者类名对不上按钮就静默消失不报错也不显示。用向导生成能保证初始骨架是正确的后面所有精力都可以放在脚本逻辑上。3. 从零写一个能跑的Add-In3.1 用向导生成项目骨架具体操作流程大概是这样的双击打开“Python Add-In Wizard”点击Next。填写项目名称、项目描述、作者和公司。这里有个血泪教训项目名称和类名不要写中文尽量用英文字母和下划线否则生成后的模块导入阶段很容易出问题。选UI类型。先勾上Button和Toolbar一个按钮加一个工具条是最典型的组合。设置工具条显示名称比如叫“我的批量工具”。添加一个按钮填上Caption按钮显示文字、Tooltip悬停提示和类名类名建议用一开始就能看懂的比如Button_StatArea。点Finish向导会在指定目录生成项目文件夹。生成后的项目里会有一个readme.txt里面写着开发Python Add-In的基本步骤说实话比很多网上的教程都清楚值得先读一遍。3.2 生成的源码到底长什么样项目目录结构大概是这样MyAddIn/ ├─ Install/ ├─ Images/ │ └─ button.png ├─ arcpy/ ├─ MyAddIn.py ├─ config.xml ├─ makeaddin.py └─ README.txt几个关键文件的作用分别是MyAddIn.py真正的脚本文件你的按钮逻辑都写在这个文件里。config.xml界面配置声明有哪些按钮、工具、菜单、工具条以及每个界面元素对应的脚本类名。makeaddin.py打包脚本运行后会生成.esriAddIn安装文件。Images存放按钮图标。Install存放打包结果和安装说明。config.xml里最关键的一段大概长这样Toolbars Toolbar caption我的批量工具 categoryMyAddIn showfalse Items Button caption统计面积 classButton_StatArea imagebutton.png / /Items /Toolbar /Toolbars注意class字段必须和MyAddIn.py里的类名完全一致包括大小写。我第一次做的时候就是改了类名忘记改config.xml结果工具栏干干净净什么按钮都没有。3.3 第一个按钮统计选中要素面积并导出CSV生成骨架后打开MyAddIn.py会看到一个模板类。我一般把它改造成这样做一个非常实用的小功能统计当前地图中选中图层里每个要素的面积导出为CSV。# -*- coding: utf-8 -*- import arcpy import pythonaddins import csv import traceback class Button_StatArea(object): def __init__(self): self.enabled True self.checked False def onClick(self): try: mxd arcpy.mapping.MapDocument(CURRENT) layer None for lyr in arcpy.mapping.ListLayers(mxd): if lyr.isFeatureLayer and lyr.getSelectionSet(): layer lyr break if not layer: pythonaddins.MessageBox(请先选中一个图层, 提示) return out_csv rD:\temp\area_stat.csv with open(out_csv, wb) as f: writer csv.writer(f) writer.writerow([OBJECTID, AREA]) with arcpy.da.SearchCursor(layer, [OBJECTID, SHAPE]) as cursor: for oid, shape in cursor: writer.writerow([oid, shape.area]) pythonaddins.MessageBox(导出完成 out_csv, 完成) except Exception as e: pythonaddins.MessageBox(str(e), 错误) traceback.print_exc()这段代码有几个点值得展开说一下。arcpy.mapping.MapDocument(CURRENT)获取的是当前打开的ArcMap文档这个只能在ArcMap界面内运行时生效如果脱离ArcMap用外部Python跑需要传mxd文件路径。getSelectionSet()判断图层是否有选中要素没有选中就弹个提示避免后面遍历空数据。arcpy.da.SearchCursor返回的结果里SHAPE代表几何对象调用.area得到的是要素的面积单位由当前数据框的坐标系决定。4. 核心源码逐段拆解与扩展4.1 在onClick里安全地操作arcpyonClick按钮事件是Add-In最核心的入口所有点击后的逻辑都从这儿开始。我在实操中养成了几个固定习惯能明显减少翻车概率。第一每次onClick开头先设置arcpy环境变量。有人觉得arcpy.env.workspace设一次就好其实不然ArcMap里用户随时可能切换数据源上一次脚本留下的workspace状态会在下次点击时残留。我习惯在函数开头重新指定arcpy.env.workspace rD:\gis_data\project.gdb arcpy.env.overwriteOutput True第二尽量把数据处理逻辑拆成独立的普通函数不要在按钮类里堆一大坨。比如说先写一个stat_areas(layer, out_csv)函数然后在onClick里只做界面交互和参数获取。这样以后把这个函数复制到ArcGIS Pro或者脚本工具里几乎不用改就能复用。第三所有可能出错的地方都要用try/except包住并且把错误信息弹出来或写进日志。Add-In的按钮一旦抛出未捕获异常用户看到的是按钮没反应不会看到堆栈排查体验很差。4.2 做一个需要画框的交互式Tool按钮适合“选中参数点一下执行”的场景但如果要在地图上画一个矩形、画一条线、或者点一个点就得用Tool类型。这个需求在批量处理里特别常见比如框选一批要素做缓冲区分析。向导生成时如果选了Tool会生成一个继承或包含Tool逻辑的类。核心代码大概这样import arcpy import pythonaddins class Tool_SelectByBox(object): def __init__(self): self.shape Rectangle self.cursor 3 def onRectangle(self, rectangle): try: mxd arcpy.mapping.MapDocument(CURRENT) df mxd.activeDataFrame for lyr in arcpy.mapping.ListLayers(mxd): if lyr.isFeatureLayer and lyr.visible: arcpy.SelectLayerByLocation_management(lyr, INTERSECT, rectangle) arcpy.RefreshActiveView() pythonaddins.MessageBox(框选完成, 提示) except Exception as e: pythonaddins.MessageBox(str(e), 错误)解释一下关键点self.shape Rectangle告诉ArcMap用户点击这个工具后鼠标拖拽画的是矩形。onRectangle在画完矩形后触发矩形对象会作为参数传进函数。接下来用arcpy.SelectLayerByLocation_management按空间位置选中所有与矩形相交的要素。除了onRectangle还有onLine、onPoint、onMouseDown、onMouseUp等回调。如果是需要连续点击多次才能结束的图形建议优先找现成的回调比如画线用onLine画点用onPoint不要自己在MouseDown里维护状态机一旦状态错乱会很头疼。4.3 控制按钮的可用状态按钮在不需要的时候应该置灰比如没有打开地图文档、没有选中图层时点了反而报错。这个可以通过enabled属性和onUpdate回调控制。class Button_StatArea(pythonaddins.Button): def __init__(self): self.enabled True def onUpdate(self): try: mxd arcpy.mapping.MapDocument(CURRENT) self.enabled self._hasSelectedLayer(mxd) except Exception: self.enabled False def _hasSelectedLayer(self, mxd): for lyr in arcpy.mapping.ListLayers(mxd): if lyr.isFeatureLayer and lyr.getSelectionSet(): return True return False def onClick(self): # 实际统计逻辑 passonUpdate会在ArcMap界面空闲时被反复调用用来刷新按钮状态。这里注意性能别再回调里做重量级操作简单检查图层和选择集就够了。判断逻辑要轻量否则界面会卡顿。4.4 打包、分发与卸载开发完成后在项目目录下打开命令行运行python makeaddin.py会在Install文件夹里生成MyAddIn.esriAddIn文件。双击这个文件ArcMap会自动识别并提示安装。安装后在ArcMap的“自定义 加载项管理器”里能看到已安装的插件点击工具条名称勾选显示你的按钮就出现了。分发给同事时直接把.esriAddIn文件发过去在对方机器上双击安装。有几件事要提前注意目标机器必须装有对应版本的ArcGIS Desktop且License可用。如果按钮里写了绝对路径换台机器很可能跑不通最好把路径参数写到config.xml或外部配置文件里。卸载很简单加载项管理器里选中插件点“删除”即可。5. 常见问题与避坑实录5.1 按钮不显示、点不动怎么排查我把这几年最常遇到的界面问题整理成一个速查表现象可能原因处理方法工具条根本找不到安装未成功重新运行makeaddin重新双击esriAddIn安装工具条存在但按钮空白config.xml里class类名和脚本类名不一致打开config.xml核对class字段按钮置灰onUpdate里enabled返回False或当前环境不满足检查是否有当前地图文档、选中图层点击没反应脚本抛出异常但弹窗被吞加try/except调试日志看堆栈图标变形图片尺寸不对图标用16x16 PNG放在Images目录5.2 Python 2.7的语法和中文编码坑这个必须单独拿出来说因为太容易踩了。Add-In跑在Python 2.7和主流的Python 3语法有不少差别。常见错误包括# 错误写法Python 3语法 except Exception as e: print(e) # 正确写法Python 2.7 except Exception, e: print e中文编码问题更隐蔽。脚本文件第一行我建议写上# -*- coding: utf-8 -*-中文字符串前加u前缀。读文件时用codecs.open或指定编码写入CSV文件时文件要用二进制模式wb否则中文可能写成乱码。我见过一个同事在按钮里拼接中文路径怎么跑都报“找不到文件”最后发现是编码没统一一旦路径里有中文就出问题。5.3 arcpy导入失败与运行环境问题Add-In运行在ArcMap进程里所以正常情况下import arcpy不会失败。如果你在外部Python命令行里import arcpy报错大概率是因为你用的不是ArcGIS自带的Python环境或者安装时没有把Python组件装上。解决办法是改用ArcGIS捆绑的C:\Python27\ArcGIS10.x\python.exe跑脚本或者修复ArcGIS安装。另外注意如果机器上自己装了其他版本的Python系统PATH可能指向那个版本导致命令行里输入python后import不到arcpy。处理方式是直接写全路径调用ArcGIS的Python不要依赖PATH。5.4 调试日志看不见print时的救命稻草在Add-In里print输出很难看到按钮点击后脚本报了什么错完全不透明。我的做法是封装一个简单的日志函数把运行信息写到本地文本文件import datetime import traceback def log(msg): with open(rD:\temp\addin_debug.log, a) as f: f.write([%s] %s\n % (datetime.datetime.now(), msg)) def log_exception(): with open(rD:\temp\addin_debug.log, a) as f: traceback.print_exc(filef)然后在所有onClick、onRectangle的except里调用log_exception()。按钮没反应时先去看日志尾部错误堆栈一目了然。这个方法救了我好多次强烈建议从一开始就加上。5.5 配合天地图等在线底图的小思路平时做项目时经常要叠加在线底图尤其天地图用得很多。严格说天地图的加载和Add-In开发是两件事。天地图影像一般通过WMTS服务或者ArcGIS Online方式接入ArcMap需要在天地图官网申请开发者Key然后在ArcMap里添加WMTS服务器地址按规范填写Key和图层名称。在Add-In里如果想自动化加载底图可以用arcpy.mapping.AddLayer添加一个保存了天地图服务参数的lyr文件。实际操作时我通常先把天地图配置手动调好另存为图层文件然后在Add-In里引用它。要注意在线底图涉及网络、服务可用性和数据版权问题用于项目成果时务必遵守天地图的授权规则。回到Add-In本身我的理解是它能解决的是“我自己的操作流程自动化”而不是“把在线地图塞进ArcMap”。搞清楚边界开发思路才会清晰。最后再分享一个我正在用的习惯把Add-In项目丢进Git仓库每次改代码都提交一次config.xml、脚本、图标保持版本同步。后来单位升级ArcGIS Pro我整理老工具时才发现这些历史提交记录帮了大忙哪些按钮被谁改过、功能怎么迭代的一清二楚。而且前期把arcpy处理逻辑都写成独立函数的话迁到Pro的时候基本只换壳不用重写核心逻辑。这个习惯算是比写出一两个按钮更值钱的经验了。本文还有配套的精品资源点击获取