简介围绕 ArcGIS Python Add-In 入门开发展开的这套资料面向希望用 Python 扩展 ArcGIS Desktop 功能的 GIS 从业者与初学者可帮助理解自定义工具、菜单、面板的构建流程以及从脚本编写、界面配置到打包部署的基本方法适合刚接触 Add-In 开发、需要从零建立整体认识并动手实践的人群。压缩包共 7 个文件约 142KB包含 2 个 py 脚本、1 份 pdf 开发说明、1 个 xml 配置、1 个 esriaddin 项目包并辅以 txt 说明和 bmp 图片兼顾教程阅读与实例对照。已有 1220 人学习说明其在入门场景中具有一定参考热度。读者可借助 pdf 梳理 Add-In 开发步骤结合 Python 代码与 XML 结构观察组件定义、ArcPy 调用和打包方式再把 esriaddin 当作可拆解的学习模板用于搭建自己的小型 GIS 工具、复现示例流程或排查接口配置问题同时可留意按钮交互、命令组织、参数传递与调试分发等细节。1. 从一次改属性改到手抖说起前阵子有个做管网数据入库的朋友发来截图一条管线图层 300 多个要素的长度字段全是空的他在属性表里一个个点开算、一个个填改到第 40 个说手已经在抖。这种活根本不该人干——ArcGIS Python Add-In 就是为这类场景准备的它把这套桌面软件里最常用的入口全部暴露成 Python 类按钮、下拉框、地图工具、工具条甚至打开/关闭文档这类全局事件都能挂一段脚本上去。市面上讲这机制的资料要么只贴个 Hello World要么直接甩一堆 ArcObjects 概念所以一份能把源码和教程对上号的资料就显得特别实在它给的不是语法课而是一套能直接抄走的工程骨架——config.xml 怎么描述组件、Python 类的注释怎么和组件 ID 对齐、打包脚本怎么把一堆散文件压成 .esriaddin。适合两类人看手上有大量重复性 GIS 操作、想固化成按钮的作业人员和要给业务方交付一个小工具包、又不想碰 COM 那套东西的开发者。2. 环境与工程骨架向导生成的目录里到底有什么2.1 运行环境与依赖先确认解释器再谈写代码Desktop 这一代的 Python 环境是独立的10.0 内嵌的是 Python 2.610.1 之后是 2.7而且都是 32 位。这个事实决定了很多事你在系统里另装的 Python 3 或者某个科学计算发行版对写 Add-In 一点忙都帮不上因为 arcpy 只装在桌面端自带的那份解释器里site-packages 也是另一套。我见过有人用 conda 环境把代码调通了装进桌面端一运行就报 ImportError翻来覆去查了半天最后发现根本是两份解释器。找解释器路径不用猜打开桌面端的 Python 窗口跑三行就知道自己站在哪个坑里。# 在桌面端自带的 Python 窗口里执行确认版本与 arcpy 是否可用 import sys import arcpy print(sys.version) # 期望 2.7.x32 位 print(sys.executable) # 解释器绝对路径写批处理时要用 print(arcpy.GetInstallInfo()[Version]) # 桌面端版本和 Target 要对上这三行里最有价值的是第二行后面做自动化打包、写启动脚本、给同事配环境都要拿这个路径去定位。第三行输出的是桌面端主版本它必须和你工程里 config.xml 声明的目标版本对得上否则包做出来能双击、能显示安装成功但工具条就是不出现——这个坑后面单独讲。向导程序 addin_assistant 就躺在桌面端安装目录的 Bin 下面10.x 各小版本位置略有出入直接在安装目录里搜这个文件名最快。它是个独立的窗体程序不依赖你当前打开的文档随手就能起。2.2 用向导建工程四类文件夹各管一摊向导第一步填工程信息名称、输出目录、版本号、作者、描述、目标桌面端版本。这些字段不是走过场名称会变成打包出来的文件名和 Python 母模块的前缀版本号关系到覆盖安装能不能生效。第二步才是加组件每加一个按钮/工具/下拉框要填类名、标题、ID、图标、分类、提示文字这些东西最后都会落到 config.xml 里。生成的工程目录结构相当固定值得先记住路径作用改动频率config.xml组件清单、目标版本、图标引用整个包的身份证高Scripts/Python 源码母模块加自定义模块都放这高Images/图标 pngconfig.xml 里用相对路径引用中Install/打包输出目录放生成的 .esriaddin不用手动碰MakeAddin.py打包脚本读 config.xml 后压缩整个工程基本不改新手最容易犯的错是把脚本写到工程目录外面或者图标用绝对路径引用。打包脚本只扫工程根目录外面的东西一律进不了包本机跑得好好的发给同事就是缺文件。我的习惯是工程建好之后先原样打一次包、装一遍确认这条链路通了再写业务代码省得后面出问题时分不清是环境问题还是代码问题。2.3 config.xml一个组件一段配置ID 是唯一纽带打开 config.xml 能看到整份结构根节点下面依次是名称、GUID、描述、版本、图标、作者、目标平台、组件列表。组件列表是核心每个按钮、工具、下拉框、扩展各占一个节点。?xml version1.0 encodingutf-8? ESRI.Configuration xmlnshttp://schemas.esri.com/Desktop/AddIns NamePipeTools/Name AddInID{8f3c1a2e-0000-0000-0000-000000000000}/AddInID Description管网数据批处理工具集/Description Version1.0/Version Targets !-- 目标桌面端版本比当前环境高会装不上 -- Target nameDesktop version10.2 / /Targets Components !-- id 必须和 Python 类注释里的路径逐字一致 -- Button idPipeTools_addin.btn_calc_len classCalcLengthButton caption批量算长度 category管网工具 imageImages\calc.png tip按几何长度回填 LEN_M 字段 / ComboBox idPipeTools_addin.combo_layer classLayerCombo caption目标图层 category管网工具 tip选择要处理的图层 / /Components /ESRI.Configuration节点里的 id 是整份配置的命门。它的格式是「母模块名.组件标识」Python 那边靠类注释里的同一串字符串完成绑定两边差一个字母组件就会在界面上消失或者点了没反应而且不报任何错。image 路径要用反斜杠、相对 Images 目录写成正斜杠在部分版本上图标会空白。category 决定它落在哪个选项卡下同一个 category 的组件会自动归到一组这个设计挺省事不用自己去排版工具条。2.4 Scripts 目录绑定关系藏在类的注释里向导会在 Scripts 下生成一个名为「工程名_addin.py」的母模块里面预置了每个组件的空类。看一个按钮类的标准长相import os import sys import arcpy import pythonaddins # 运行时的工作目录不一定是 Scripts手动把脚本目录塞进搜索路径 try: _here os.path.dirname(os.path.abspath(__file__)) except NameError: _here os.getcwd() if _here not in sys.path: sys.path.append(_here) import utils # 自己拆出去的工具模块 class CalcLengthButton(object): Implementation for PipeTools_addin.btn_calc_len (Button) def __init__(self): self.enabled True # 是否可点 self.checked False # 是否为按下态仅对可切换的按钮有意义 def onClick(self): pass那段 docstring 不是给人看的注释是运行时解析绑定关系的依据第一行必须是「Implementation for 母模块名.组件ID (组件类型)」少了或者写错就等于这个类没人认领。顶部那段 sys.path 处理是我踩过坑之后固定加的桌面端加载脚本时工作目录并不固定在 Scripts 下你拆出去的 utils.py 在开发机上能 import换台机器就报找不到模块。用__file__拼绝对路径最稳实在取不到再退回当前目录兜底。3. 五类扩展点拆解从按钮到文档事件的调用链3.1 ButtononClick 到游标更新的最小闭环按钮是最简单的扩展点生命周期也最好理解脚本加载时实例化一次点击时调一次 onClick中间不做任何缓存。适合放「一键执行」型的批处理把用户在界面上要点十几下的流程压成一次点击。class CalcLengthButton(object): Implementation for PipeTools_addin.btn_calc_len (Button) def __init__(self): self.enabled True self.checked False def onClick(self): # CURRENT 表示当前打开的文档是 Add-In 里唯一正确的取文档方式 mxd arcpy.mapping.MapDocument(CURRENT) df arcpy.mapping.ListDataFrames(mxd, Layers)[0] layer arcpy.mapping.ListLayers(mxd, PIPE_LINE, df)[0] # dataSource 拿到的是真实路径游标要操作数据源而不是图层对象 n 0 with arcpy.da.UpdateCursor(layer.dataSource, [SHAPELENGTH, LEN_M]) as cur: for row in cur: row[1] round(row[0], 2) cur.updateRow(row) n 1 arcpy.RefreshActiveView() pythonaddins.MessageBox(u已更新 %d 条要素 % n, u完成, 0)几个参数值得抠一下。MapDocument(CURRENT)是这套机制里拿当前文档的唯一入口写死文件路径的脚本在按钮里基本没法用。ListDataFrames第二个参数传名称比传索引稳索引会随用户拖拽顺序变化。layer.dataSource这一步不能省图层对象本身不是游标能吃的输入而且图层组、内存图层调 dataSource 会直接抛异常得提前判断。MessageBox 的第三个参数是按钮组合0 表示只有一个确定适合做结果回执类型 4 是是否适合做二次确认别在批量删除这种操作上省这一步。3.2 Tool鼠标坐标与几何回传工具和按钮的差别在于它有交互状态。用户点下地图那一刻方法收到的是地图坐标而不是屏幕坐标中间那层换算框架已经做完了。class PickPointTool(object): Implementation for PipeTools_addin.tool_pick_point (Tool) def __init__(self): self.enabled True self.shape NONE # 不要框架帮忙画几何坐标自己处理 self.cursor 3 # 十字光标采集点位时手感更好 def onMouseDownMap(self, x, y, button, shift): mxd arcpy.mapping.MapDocument(CURRENT) df arcpy.mapping.ListDataFrames(mxd)[0] layer arcpy.mapping.ListLayers(mxd, PIPE_POINT, df)[0] with arcpy.da.InsertCursor(layer.dataSource, [SHAPEXY]) as cur: cur.insertRow([(x, y)]) arcpy.RefreshActiveView() def onShapeCreated(self, geometry): # 只有 self.shape 不是 NONE 时才会被调用geometry 是用户画完的几何 self.last_shape geometryself.shape这个属性决定框架要不要接管绘制设成 Point、Line、Polygon、Rectangle、Circle 时用户拖拽完会回调 onShapeCreated 并把几何传进来设成 NONE 就只有坐标回调适合点选、取点这类操作。onMouseDownMap的四个参数分别是地图 X、地图 Y、鼠标键、修饰键状态返回的坐标已经是地图单位直接塞进游标不用再投影。工具类是有状态的同一个实例会被反复调用所以临时数据可以挂在 self 上但千万别把上一次的几何不清空用户连续点两下就可能拿到混在一起的结果。3.3 ComboBox 与 Toolbar控件联动和刷新时机下拉框的坑集中在初始化时机。类实例化发生在文档加载之前这时MapDocument(CURRENT)拿不到任何东西在__init__里填 items 必然拿到空列表。class LayerCombo(object): Implementation for PipeTools_addin.combo_layer (ComboBox) def __init__(self): self.items [] # 这里只给空列表别急着读文档 self.editable False self.enabled True self.dropdownWidth 30* self.width 20* def refresh(self): # 每次展开下拉都会走这里是填充候选项最安全的时机 mxd arcpy.mapping.MapDocument(CURRENT) df arcpy.mapping.ListDataFrames(mxd)[0] self.items [lyr.name for lyr in arcpy.mapping.ListLayers(mxd, , df)] def onSelChange(self, selection): # selection 是选中项文本不是索引 pythonaddins.MessageBox(u当前目标 selection, u提示, 0)refresh()是关键它在每次用户点开下拉时被调用把读文档的动作放这里就不会有时序问题。width和dropdownWidth用30*这种带星号的写法表示按字符宽度自适应写死像素值在高分屏上会挤成一团。工具栏本身不写代码它只是 config.xml 里的一个容器节点把按钮和下拉框按 category 归组需要调整布局时改配置就行不用动 Python。3.4 Extension在文档事件里做全局逻辑扩展点没有界面挂在文档生命周期上用户感知不到它的存在适合做初始化、状态清理、日志这类脏活。class DocEventExtension(object): Implementation for PipeTools_addin.ext_doc (Extension) def __init__(self): self.enabled True self.cache {} def openDocument(self): # 文档打开完成此时读 CURRENT 是安全的 self.cache.clear() def activeViewChanged(self): # 视图切换包括布局视图和数据视图之间来回切 pass def closeDocument(self): # 必须在这里清理否则同一进程里再开一个文档会带着旧状态 self.cache.clear()扩展点最典型的用途是缓存把耗时的查询结果存在 self 上按钮和工具直接读省掉每次点击都重算。代价是要在 closeDocument 里把缓存清干净桌面端进程常驻用户关掉一个文档再开另一个扩展实例还在缓存不清就会读到上一个文档的数据这类 bug 极难复现也极难定位。4. 跑通与打包从脚本到 .esriaddin 的完整链路4.1 本地调试把 Add-In 当普通模块 importAdd-In 里的 print 是黑匣子输出没有接任何窗口打了等于没打。第一层调试手段是把脚本目录挂进 Python 窗口的搜索路径手动实例化类调方法让异常直接抛在眼前。# 在桌面端 Python 窗口里执行路径换成自己的 Scripts 目录 import sys sys.path.append(rD:\work\PipeTools\Scripts) import PipeTools_addin reload(PipeTools_addin) # 改完代码必 reload否则还是旧模块 btn PipeTools_addin.CalcLengthButton() btn.onClick() # 异常会直接打在窗口里比 MessageBos 好使reload这一步不能省Python 2.7 对已导入模块有缓存改完文件不 reload 你会怀疑人生。要注意 pythonaddins 这个模块只在 Add-In 上下文里可用Python 窗口里 import 可能失败所以业务代码里凡是用到它的地方都要拆出去调试时绕开。第二层手段是写文件日志在脚本目录下开一个 log.txt 追加写比弹窗温和也不会打断操作。第三层才是 MessageBox适合验证「这段代码到底有没有被执行到」。4.2 打包、安装与卸载打包脚本的逻辑很朴素读 config.xml 拿名称和版本把工程根目录下除 Install 以外的所有文件压成一个 zip改后缀成 .esriaddin 丢进 Install 目录。所以它只认工程内的文件任何外部依赖都得先搬进来。命令行跑一遍就行不需要开界面。# 在工程根目录执行打包结果输出到 Install 目录 python MakeAddin.py装的时候双击生成的 .esriaddin弹出安装工具点一下 Install文件会被解到用户目录下的AppData\Roaming\ESRI\Desktop10.x\AddIns\{GUID}\一个包一个 GUID 文件夹。这意味着安装是「按用户」的同一台机器换个账号登录就看不到你的工具条给团队部署时要提醒每人装一次。卸载有两条路安装工具里点 Delete或者直接删那个 GUID 目录。升级时直接重装覆盖但要注意版本号——有些环境下重装同名同版本的包界面上的行为不会变代码明明改了却像没生效把 config.xml 的 Version 加一再打一次包就正常了。这不是玄学是覆盖判断的依据没更新。4.3 版本兼容桌面端和 Pro 是两条路config.xml 的 Targets 节点决定了这个包能被哪些版本加载。目标版本填高了在低版本上装不上填低了在新版本上能用但新特性用不了。我在团队里统一约定目标版本按团队里最低的那个桌面端版本填宁可少用新 API也不要让一半人装不上。更要紧的是另一条分界线这套 .esriaddin 机制只属于桌面端另一个产品线项目名带 Pro 的那个根本不认这个格式那边对应的是 Python Toolbox.pyt和它自己的 Add-In 体系。所以选型阶段就要想清楚交付目标如果业务方迟早要迁到新端把业务逻辑抽成不依赖 UI 的纯函数模块迁移时重写一层壳就行代码主体能复用。这个决定做得越早越省事等到几十个按钮都写死了 arcpy.mapping返工量能让人哭。5. 常见问题排查五类故障的现象、成因与处置5.1 打包与加载阶段的三类失败现象一装完打开软件工具条里根本找不到自己的选项卡。原因通常有三个双击 .esriaddin 后只在解压界面看了一眼没点 Installconfig.xml 里 Target 版本高于当前桌面端版本包被静默拒绝或者装到了另一个用户账号下。处置方式是去AppData\Roaming\ESRI\Desktop10.x\AddIns\看有没有对应 GUID 的文件夹没有就是没装上有但界面不显示就查版本。这一步用文件系统确认比在界面里猜快得多。现象二选项卡出来了按钮是灰的或者点了毫无反应。九成是绑定断了类的 docstring 里那串 ID 和 config.xml 的 id 不一致中间改过名字、复制类没改注释、或者手改配置时多打了个空格。剩下的一成是脚本有语法错误被静默吞掉加载时异常没冒到界面上。处置时把 docstring 和配置里的 id 逐字对一遍再在 Python 窗口里 import 一次母模块语法错误会立刻现形。现象三本机能用发给同事就缺图标、缺模块。原因是工程里引用了目录外的文件或者用了绝对路径。打包脚本只扫工程根目录外面的东西一律不进包。处置是把所有资源和脚本搬进工程目录图标统一写Images\xxx.png这种相对路径反斜杠别写成斜杠。5.2 运行期与部署阶段的两类失败现象四下拉框永远是空的切换文档也不刷新。前面提过items 在__init__里赋值时文档还没加载完读到的必然是空。处置是把填充逻辑挪到refresh()里或者在扩展点的 openDocument 里主动推一次。现象五第一次点按钮正常第二次报数据被锁定。游标没关或者 MapDocument 对象没释放。桌面端对数据源有锁游标不关闭会一直占着。处置是所有游标一律用 with 语句MapDocument(CURRENT)用完显式 del循环里更不要反复新建文档对象。提示这类锁定错误在单机小数据上几乎不出现一到共享目录或者要素类上就集中爆发测试时尽量拿真实数据源跑别只在自己机器的 shapefile 上验证。6. 二次开发改造把示例骨架变成能交付的工具示例代码能跑但直接拿去交付会很难受因为它把取图层、算数据、弹提示三件事糊在一个 onClick 里。我的改造习惯是切三层母模块只负责从界面拿参数和给反馈业务逻辑全部下沉到 Scripts 下的独立模块配置常量单独一个文件。# Scripts/core.py —— 纯业务不 import pythonaddins不碰界面 import arcpy def calc_length(fc, length_field, unit_factor1.0): 按几何长度回填字段返回更新条数。unit_factor 用于米/千米换算。 n 0 with arcpy.da.UpdateCursor(fc, [SHAPELENGTH, length_field]) as cur: for row in cur: row[1] round(row[0] * unit_factor, 2) cur.updateRow(row) n 1 return n母模块那边就剩几行解析当前图层、调 core、弹结果。这么切的好处很直接——core.py 能在 Python 窗口里直接 import 测试不需要装包、不需要点按钮改一次验一次将来要迁到另一个端core.py 原样搬过去重写的只是外面那层壳。参数换算系数这类东西全部集中到一个 config.py 里当常量别散落在各个 onClick 中交付前改一个单位要翻五个文件是最典型的翻车现场。验证方法也简单每加一个功能先在 Python 窗口里对着真实数据把 core 函数跑通再挂到按钮上装包之后换一台没参与开发的机器完整走一遍专门看资源和依赖有没有漏。我吃过一次亏本机跑得好好的工具包发到现场打开就报找不到模块原因是拆出去的模块名和系统里某个库重名被抢先导入了从那以后我每次给工具模块起名都强制加项目前缀打包完也一定要在干净机器上装一遍再交付。希望帮到你。本文还有配套的精品资源点击获取