ArcPy 参数界面怎么配置
ArcPy 参数界面指地理处理窗格中工具参数的默认外观与控件。配置通常有两条路:脚本工具(.tbx / .atbx)在工具属性对话框的“参数”选项卡里设置标注、数据类型、必需/可选、过滤器等;Python 工具箱(.pyt)则在工具类的 getParameterInfo 方法中创建 arcpy.Parameter 对象并返回参数列表。需要改默认控件时,用 Parameter 的 controlCLSID 覆盖,官方只支持有限几种自定义控件。截至 2026 年 11 月,相关说明以 ArcGIS Pro 最新文档为准。

脚本工具里怎么配置参数界面
脚本工具适合把现成 .py 脚本挂到工具箱里给同事用。参数界面主要在创建工具时,或事后在属性对话框里配齐,不必先改代码。
- 在 Catalog 中右键工具箱 → 新建 → 脚本,或对已有脚本工具右键 → 属性。
- 打开 参数 选项卡,逐行添加参数:填写显示名(标注)、内部名称、数据类型、类型(必需 / 可选 / 派生)、方向(输入 / 输出)。
- 按需要勾选多值,设置默认值、类别、描述;在过滤器列选择 ValueList、Range、Feature Class、File、Field、Workspace 等(可用类型取决于数据类型)。
- 若某参数依赖另一参数(例如字段依赖要素图层),在依赖关系列指定上游参数。
- 派生输出(修改输入、标量结果、已知路径写出等)务必设好依赖,并在脚本里用 arcpy.SetParameter 或 SetParameterAsText 赋值,这样 ModelBuilder 才能串工具。
- 确定后保存;运行工具时地理处理窗格会按数据类型给出默认控件。
脚本内取值优先用 arcpy.GetParameterAsText(index)(字符串、无字符长度限制);需要对象时用 GetParameter。不建议依赖 sys.argv。更细的字段说明见 Esri 中文文档 设置脚本工具参数。
- 验收标准:打开工具窗格后,每个参数控件类型正确、必填项有红星、过滤器下拉可选、依赖字段随图层切换而刷新。
- 常见坑:派生参数方向设成 Input、忘记 SetParameter,或在验证阶段试图改 datatype / controlCLSID(这些特性一般只能在初始化时设定)。
Python 工具箱里怎么定义参数
Python 工具箱把工具类写在 .pyt 里,参数完全用代码声明,便于版本管理和复杂联动。
- 在工具类中实现 getParameterInfo,创建多个 arcpy.Parameter 对象。
- 为每个参数设置 name、displayName、direction、datatype、parameterType、enabled、category、multiValue 等;需要时再设 filter、parameterDependencies、value、symbology。
- 把参数对象按顺序放进列表并 return;地理处理框架按该顺序生成界面。
- 在 updateParameters / updateMessages 里做联动与校验(例如根据上一项启用下一项、改 filter.list),但不要在这里改 datatype、controlCLSID 等初始化特性。
- 执行逻辑里用参数的 value 或 valueAsText 取值;派生输出同样用 SetParameter 系列写回。
Parameter 构造大致为:name、displayName、direction、datatype、parameterType、enabled、category、symbology、multiValue。类属性与约束见 Parameter 类参考;中文步骤见 在 Python 工具箱中定义参数。ArcPy 本身是随 ArcGIS Pro 等产品提供的站点包,环境与版本需与本机 Pro 一致,可参考 ArcPy 与 ArcGIS API for Python 入门。

怎么用 controlCLSID 自定义控件
默认控件由数据类型和是否多值决定。官方框架只开放有限自定义控件,通过给 Parameter 赋 controlCLSID(GUID 字符串)覆盖。脚本工具通常在 ToolValidator 的 __init__ 里设置;Python 工具箱在 getParameterInfo 建好参数后立刻赋值。工具属性对话框里改不了这项。
| 适用场景 | controlCLSID(示例) | 效果简述 |
|---|---|---|
| 范围 Extent | {15F0D1C1-F783-49BC-8D16-619B8E92F668} | 去掉 Intersect / Union 按钮 |
| 数值 Long/Double + Range | {C8C46E43-3D27-4485-9B38-A49F3AC588D9} | 增加滑动条 |
| 数值大文本框 | {7A47E79C-9734-4167-9698-BFB00F43AE41} | 左对齐大输入框 |
| 复合类型 | {BEDF969C-20D2-4C41-96DA-32408CA72BF6} | 可切换数据类型选择列表 |
| 多行字符串 | {E5456E51-0C41-4797-9EE4-5269820C6F0E} | 多行文本框 |
| 多值 + ValueList | {172840BF-D385-4F83-80E8-2AC3B79EB0E0} | 选择列表式多值 |
| 多值含全选 | {38C34610-C7F7-11D5-A693-0008C711C8C1} | 带全选按钮 |
| 要素图层 / Feature Set | {60061247-BCA8-473E-A7AF-A2026DDE1C2D} | 支持要素集交互 |
| 值表 Value Table | {1AA9A769-D3F3-4EB0-85CB-CC07C79313C8} | 水平排列 |
| 值表单组 | {1A1CA7EC-A47A-4187-A15C-6EDBA4FE0CF7} | 限制单组,去掉“添加另一个” |
| 仅日期 / 仅时间 | {499BF343-569C-4B2B-864B-742C602C33FE} / {4FA5E857-E8CC-4226-8B87-1BFA0A9876EC} | 日期或时间专用控件 |
GUID 与支持范围以官方 参数控件说明 为准;列表外的 GUID 通常无效。配完后重新打开工具窗格验收控件形态是否变化。
过滤器、依赖与派生输出要注意什么
- 过滤器:ValueList、Range、要素类类型、文件扩展名、字段类型、工作空间类型、面积/长度/时间单位等。脚本工具在属性表填;.pyt 里设 filter.type 与 filter.list。Range 配合数值滑动条类 controlCLSID 时体验更好。
- 依赖关系:字段参数依赖要素图层/表,输出方案常依赖输入要素类。依赖设错会出现空下拉或方案不同步。
- 派生输出:输出与输入同路径、只改 schema、返回标量、或由其他参数拼出路径时用 Derived;脚本必须 SetParameter,否则模型链断、结果不进窗格。
- 多值与类别:多值适合批量路径;类别可把次要参数折叠分组,避免窗格过长。
- 版本:文档随 ArcGIS Pro 更新。资料显示 Pro 3.7 相关说明约在 2026 年 5 月发布,后续版本以官网 “latest” 页面为准,本地行为以你安装的 Pro 版本实测为准。
常见问题
属性对话框里找不到 controlCLSID 选项?
正常。自定义控件只能在 ToolValidator 的初始化或 .pyt 的 getParameterInfo 里给 Parameter.controlCLSID 赋值,属性对话框不提供该项。
updateParameters 里改了 datatype 为什么不生效?
datatype、controlCLSID 等多数特性属性只能在参数创建或初始阶段设置,验证方法里动态改通常会被忽略,应在 getParameterInfo 或 ToolValidator 初始化时定死。
脚本工具和 Python 工具箱该选哪个?
界面以对话框配置为主、脚本已独立时用脚本工具更省事;需要复杂联动、Git 管理、多工具共用逻辑时用 .pyt。两者都能配齐过滤器、依赖和派生输出。
参数取到空值或类型不对怎么查?
先核对参数索引顺序与方向;脚本工具优先 GetParameterAsText;检查过滤器是否过严、依赖图层是否为空。派生输出确认已 SetParameter,并在 ModelBuilder 中看输出是否连上。
配置 ArcPy 参数界面,核心是:脚本工具走属性“参数”选项卡,Python 工具箱走 getParameterInfo;需要改控件形态时再用官方列出的 controlCLSID。建议先把数据类型、必需/可选、过滤器和依赖配正确并跑通取值与 SetParameter,再按需加自定义控件;验收时以地理处理窗格实际控件与 ModelBuilder 串联结果为准,细节以 Esri 最新 Pro 文档为准。