将ArcPy脚本封装为工具箱工具

ArcPy
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

将 ArcPy 脚本封装为工具箱工具,主要有两种正规方式:在自定义工具箱(推荐 .atbx)里新建脚本工具,或直接创建 Python 工具箱(.pyt)。封装后的工具外观、运行方式与系统地理处理工具一致,可在目录窗格打开、放入 ModelBuilder、被其他脚本调用,并写入地理处理历史。新手优先用脚本工具;需要大量自定义参数验证时,再考虑 Python 工具箱。

脚本工具与工具箱关系示意

脚本工具和 Python 工具箱怎么选

两者都能把你的 ArcPy 逻辑变成可复用工具,差别主要在参数定义方式和维护成本。脚本工具用属性对话框配置参数,源代码通常放在单独的 .py 文件里,适合先写好脚本再“挂”到工具箱。Python 工具箱把工具箱类、参数、验证和执行代码全部写在一个 .pyt 文件中,更利于版本控制和复杂校验,但对 Python 类结构更熟悉。

对比项 脚本工具(.atbx / 旧 .tbx) Python 工具箱(.pyt)
参数定义 工具属性对话框(向导) 代码里用 arcpy.Parameter
源代码位置 外部 .py,或嵌入工具 全部在 .pyt 中
验证逻辑 可选 Validation 页 / 脚本 updateParameters、updateMessages 等方法
适合谁 新手、脚本已写好、参数相对固定 需复杂联动验证、重视纯文本版本管理
其他类型工具 同一工具箱还可放模型工具等 本身是代码工具箱,可调用其他工具箱中的工具

截至 2026 年 11 月,ArcGIS Pro 从 3.0 起已不能在工程里新建旧版 .tbx,推荐使用 .atbx(自 2.9 引入,跨版本兼容与持久性更好)。旧版 ArcMap 相关流程已退役,新项目一律按 Pro 与 .atbx / .pyt 来做。更细的对比可参考 Esri 官方说明:自定义工具箱与 Python 工具箱对比。

如何把现有 ArcPy 脚本做成脚本工具

目标很明确:让同事在工具对话框里填参数就能跑,而不是打开 Python 窗口粘代码。按下面步骤在 ArcGIS Pro 中操作即可。

  1. 在目录窗格中,右键“工具箱”→ 新建工具箱,选择 ArcGIS 工具箱(.atbx),放到工程文件夹或共享路径下。
  2. 右键该工具箱 → 新建 → 脚本,打开工具属性对话框。
  3. 在 General 页填写:名称(仅字母数字下划线)、标签(可含空格,显示给用户)、描述。名称不要用中文或空格。
  4. 在 Parameters 页按顺序添加参数:每个参数指定显示名称、数据类型、类型(必选/可选)、方向(输入/输出)。至少要有一个输出参数,否则难以在 ModelBuilder 中串联。
  5. 在 Execution 页指定脚本:指向外部 .py,或直接把代码嵌入。分享给他人时,建议嵌入脚本(Import Script),避免路径丢失。
  6. 需要时在 Validation 页写校验逻辑(如根据输入图层自动过滤字段列表)。保存后,在地理处理窗格中打开工具试跑。

官方逐步说明见:Adding a script tool(添加脚本工具)。创建完成后,工具会出现在工具箱中,用法与系统工具相同。

Esri 官方“添加脚本工具”文档页面示意
Esri 官方“添加脚本工具”文档页面示意(截图来源:pro.arcgis.com)

脚本里怎样正确获取参数并写出结果

封装的关键是:对话框里的参数顺序与脚本读取索引一致。推荐用 arcpy.GetParameterAsText(index) 取文本形式参数(无长度限制),或用 arcpy.GetParameter(index) 取对象类型;索引从 0 开始,与 Parameters 列表顺序一一对应。尽量少用 sys.argv,它有长度限制且不适合复杂类型。

典型写法要点:

  • 输入要素类、字段、工作空间等,按你在对话框中定义的顺序用 GetParameterAsText 取出。
  • 环境设置可直接用 arcpy.env(如 overwriteOutput、scratchWorkspace),工具运行时 ArcPy 会感知当前工程环境。
  • 必须把最终结果写到“输出”参数对应的路径或数据集上;可用 arcpy.SetParameterAsText 或 SetParameter 把结果回传给对话框/ModelBuilder。
  • 用 arcpy.AddMessage、AddWarning、AddError 写进度与诊断信息,用户才能在工具消息窗口看到,而不是只在你本地的 print 里。

验收标准:在工具对话框中填好参数后能成功运行;地理处理历史里有记录;把输出拖进地图或接到下一个模型工具时路径正确;改一个可选参数后行为符合预期。

路径、分享和加密要注意什么

最常见翻车点是脚本路径。相对路径在工具箱或脚本被移动后容易失效,典型报错是“与此工具关联的脚本不存在”(错误 000576)。处理办法:

  • 右键工具 → 属性,检查 Execution / Source 中的脚本路径是否仍有效。
  • 分享前优先把脚本导入工具(显示为 <<Imported>>),或保持 .atbx 与 .py 相对目录不变并一起打包。
  • .atbx 本身更利于跨版本携带;若必须用旧 .tbx,注意相对路径选项,但新项目不要再新建 .tbx。
  • 需要保护源码时,脚本工具可嵌入并设置密码保护;Python 工具箱可对 .pyt 加密。以当前 Pro 版本界面操作为准。

若要把一整套工具作为模块分发,还可进一步做成地理处理 Python 包(含消息与帮助),那是工具箱之上的扩展方式,适合团队内部统一发布,而不是单次脚本封装。

常见问题

脚本工具和直接在 Python 窗口跑脚本有什么实质区别?

窗口跑脚本适合调试;封装成工具后,参数有对话框、能进 ModelBuilder、写入地理处理历史、可被其他工具调用,同事无需改代码即可复用,这才是“工具箱工具”的价值。

Parameters 里一定要设输出参数吗?

是的。没有输出参数时,工具很难在 ModelBuilder 中作为下游输入,也无法规范地回传结果路径。即使脚本只是改属性或写日志,也应定义一个输出(例如输出要素类、表或派生参数)。

出现错误 000576 怎么办?

几乎都是脚本路径失效。打开工具属性核对脚本位置;分享时改为嵌入脚本,或保证工具箱与 .py 相对位置不变。修好路径后重新打开工具再运行。

该用 .atbx 还是 .pyt?我已经有一个能跑的 .py 了。

已有独立 .py、参数不复杂:用 .atbx 新建脚本工具最快。若参数会互相联动、校验很多、又希望整个工具箱都是纯文本便于 Git:新建 .pyt,把逻辑迁进去。

把 ArcPy 脚本封装为 arcpy 脚本工具,核心是选对载体(新手用 .atbx 脚本工具)、参数顺序与 GetParameterAsText 对齐,并保证至少有一个输出参数。先做一次本地试跑和路径检查,再决定是否嵌入源码用于分享;需要复杂验证时再转到 Python 工具箱,避免一开始就把简单脚本写得过重。