定义 Python 工具箱中的参数—ArcGIS Pro

几乎所有工具都具有参数，可在工具对话框或脚本中设置参数值。运行工具时，会将参数值发送到该工具的源代码。该工具将读取这些值并相应地对其进行处理。

要了解有关参数的详细信息，请参阅了解脚本工具参数。

在 Python 工具箱 (.pyt) 中，通过创建 Parameter 对象并设置其属性在工具类的 getParameterInfo 方法中定义工具参数。

Parameter 对象具有多个读写属性，但应为每个参数设置的属性如下所示：


属性	描述
displayName	地理处理窗格中显示的参数名称。
name	在 Python 的工具语法中显示的参数名称。
datatype	每个 Python 工具箱的工具参数都有关联的数据类型。打开地理处理窗格后，将使用该数据类型来检查参数值。数据类型也可用于浏览数据 - 仅与参数数据类型匹配的数据才会显示在浏览对话框中。要获取参数数据类型的列表，请参阅 Python 工具箱中的参数数据类型。
parameterType	以下为 parameterType 的选项： Required - 在提供值之前，该工具无法运行。 Optional - 无需为参数提供值。 Derived - 该参数仅适用于输出参数（请参阅以下 direction 属性）。派生的输出参数不会显示在工具对话框中。
direction	此属性定义参数是工具的输入还是工具的输出。选项为输入和输出。如果 parameterType 设置为 Derived，请将 direction 设置为 Output。

以下示例为工具定义了三个参数：一个用于接受要素图层的输入参数、一个用于接受新字段名称的输入参数以及一个基于第一个输入参数的派生输出参数。对于要反映在工具中的参数，将在 getParameterInfo 方法的结尾处返回这些参数。

def getParameterInfo(self):
    #Define parameter definitions

    # First parameter
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")

    # Second parameter
    param1 = arcpy.Parameter(
        displayName="Sinuosity Field",
        name="sinuosity_field",
        datatype="Field",
        parameterType="Optional",
        direction="Input")

    param1.value = "sinuosity"

    # Third parameter
    param2 = arcpy.Parameter(
        displayName="Output Features",
        name="out_features",
        datatype="GPFeatureLayer",
        parameterType="Derived",
        direction="Output")

    param2.parameterDependencies = [param0.name]
    param2.schema.clone = True

    params = [param0, param1, param2]

    return params

派生输出

以上示例中显示的最后一个参数是派生输出参数。派生的输出参数可用于下列五种工具：

输出与输入相同的工具，例如计算字段或以上所示示例。计算字段可更改输入表中特定字段的值，但不会创建表或修改输入的方案。可在编辑工具箱中找到的输出与输入相同的其他工具。
用于修改输入方案的工具，例如添加字段。添加字段可以向输入表中添加字段，但不会创建输出表。
可使用其他参数中的信息创建输出的工具，例如创建要素类工具。使用创建要素类工具时，仅需指定工作空间及新要素类的名称，即可创建要素类。
此工具可以创建相对于数据集的输出标量值。例如，获取计数工具可创建一个输出长整型值（记录数）。当工具输出标量值时，输出为“派生”类型。
此工具将在已知位置创建数据。例如，在您的脚本中，将更新已知工作空间中的现有表。用户无需在对话框或脚本中提供此表。

多值参数

如果希望参数处理一组值，而非仅处理单个值，请将 multiValue 属性设置为 True。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input",
        multiValue=True)

以下是多值参数的示例：

值表参数

您可通过值表参数指定多个条目。例如，可使追加、联合及许多其他工具中的输入要素参数包括多个数据集，也可使融合及汇总统计数据工具中的统计字段参数包括多个字段。

通过将 datatype 设置为 GPValueTable 来定义值表参数，并且设置一个 columns 属性以定义参数的数据类型和列标题。在以下示例中，通过接受统计类型 (GPString) 的字段名称和字符串值的两列来定义值表参数。使用 ValueList 过滤器和值列表时，可以在相应 GPValueTable 列下生成参数控件的下拉列表。要为值表参数设置默认值，可使用 values 属性并在值列表中提供参数值。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName ='Input Features',
        name ='in_features',
        datatype ="GPFeatureLayer",
        parameterType ='Required',
        direction ='Input')

    param1 = arcpy.Parameter(
        displayName='Statistics Field(s)',
        name='stat_fields',
        datatype='GPValueTable',
        parameterType='Required',
        direction='Input')

    param1.parameterDependencies = [param0.name]
    param1.columns = [['Field', 'Field'], ['GPString', 'Statistic Type']]
    param1.filters[1].type = 'ValueList'
    param1.values = [['NAME', 'SUM']]
    param1.filters[1].list = ['SUM', 'MIN', 'MAX', 'STDEV', 'MEAN']

注：

要将值表参数的列设置为复合数据类型，请将列表的第一项设置为数据类型列表。

或者，要将某个列设置为只读列，可以使用附加 ReadOnly 值来定义 columns 属性。值为 ReadOnly 将显示该列，仅供参考，例如 param1.columns = [['Field', 'Field', 'ReadOnly'], ['GPString', 'Statistic Type']]。

字段列对值表中的第一个数据列具有隐式依赖。任何后续字段列的参数下拉列表将自动包含数据中的任何可用字段。

为参数设置默认值

可通过两种方法为参数设置默认值：直接通过 value 属性应用一个值或通过 defaultEnvironmentName 应用环境设置的值。

打开脚本工具时，默认值为参数的内容。如果在脚本中为参数输入 #，则也是将要使用的值。如果未指定值，则在打开脚本工具时，参数值将为空。

设置来自环境的默认值

通过将 defaultEnvironmentName 属性设置为环境设置的名称，可将参数的默认值设置为环境设置的值。选择环境设置后，将忽略 value 属性。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Workspace",
        name="in_workspace",
        datatype="DEWorkspace",
        parameterType="Required",
        direction="Input")

    # In the tool's dialog box, the first parameter will show 
    #  the workspace environment's value (if set)
    param0.defaultEnvironmentName = "workspace"

参数方案

类型为要素类、表、栅格或工作空间的每个输出参数都具有 schema 对象。仅输出要素类、表、栅格和工作空间具有方案；其他类型则没有。 schema 对象通过地理处理进行创建。可以通过参数对象访问此 schema，或者设置规则以描述工具的输出。设置方案规则之后，地理处理内部验证代码会检查设置的规则并更新输出的描述。

当输入参数 datatype 为要素集或记录集时，用户必须指定要输入的要素的 fieldsRule 和 geometryType 值。

要素集和记录集

要素集和记录集数据类型允许交互输入数据。要素集允许脚本用户在通过单击地图以交互方式创建要素。记录集允许用户在表格中以交互方式创建行。

通过将参数的 value 属性设置为要素类、表或图层文件 (.lyrx)，可为要素集和记录集数据类型设置符号系统和方案（属性和几何类型）。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Feature Set",
        name="in_feature_set",
        datatype="GPFeatureRecordSetLayer",
        parameterType="Required",
        direction="Input")

    # Use __file__ attribute to find the .lyr file (assuming the
    #  .pyt and .lyr files exist in the same folder)
    param0.value = os.path.join(os.path.dirname(__file__),
                                'Fire_Station.lyrx')

将过滤器应用于参数

将过滤器应用于参数，可以缩小用户对于参数的可用选择。例如，可设置字段过滤器将选择限制为仅含文本字段。

地理处理将自动为字符串、长整型、双精度型、要素类、文件、字段和工作空间类型的参数创建过滤器。即使不为参数设置过滤器，参数仍会关联一个过滤器 - 只不过它是空的。空过滤器等同于没有过滤器。通过向空过滤器添加值，可以激活过滤器，并且用户的选择仅限于过滤器内容：

用户浏览数据时，过滤器仅提供有效的选择。如果将过滤器设置为点要素类，则用户浏览数据时仅显示点要素类。如果将过滤器设置为文本字段，则字段下拉列表仅显示文本字段。
如果用户键入了参数值（而不是从列表或文件浏览器中选择值），则系统会将该值与过滤器进行比较。如果用户输入的值无效（例如数值字段而不是文本字段），将出现警告或错误。

如果希望仅为参数输入特定的值或数据集类型，可以指定过滤器。将 filter 对象的 type 属性设置为相应值。下表描述了过滤器类型，可用的过滤器类型取决于参数的数据类型。

过滤器类型和值
过滤器类型	值
值列表	与字符串、长整型、双精度、布尔型、线性单位、面积单位和时间单位数据类型一起使用的字符串或数值列表。对于线性单位、面积单位和时间单位 ValueList 过滤器，请提供单位关键字字符串列表，只有使用这些单位的值才会被视为有效并显示在工具对话框的单位下拉列表中。
范围	用于长整型、双精度、线性单位、面积单位和时间单位数据类型的最小值和最大值。对于线性单位、面积单位和时间单位范围过滤器，请提供包含两项的列表：包含单位的最小值和最大值，例如 ["1 Meters", "100 Meters"]。
要素类	允许的要素类类型列表：点、多点、折线、面、多面体、注记和维度。可以提供多个值。
文件	文件后缀的列表，例如 ['zip', 'xml']。
字段	允许的字段类型列表：Short、Long、Float、BigInteger、Single、Double、Text、Date、OID、TimeOnly、DateOnly、TimestampOffset、Geometry、Blob、Raster、GUID、GlobalID 和 XML。可以提供多个值。
工作空间	允许的工作空间类型列表：文件系统、本地数据库和远程数据库。可以提供多个值。
出行模式单位类型	允许的出行模式的阻抗属性列表：时间、距离或其他。

filter 属性
属性	描述
type	过滤器的类型（ValueList、范围、要素类、文件、字段和工作空间）。在处理长整型参数、双精度型参数、线性单位参数、面积单位参数和时间单位参数时，可设置过滤器的类型（请参阅下面的注释）。对于其他类型的参数，仅有一种有效的过滤器类型，所以可以忽略这些参数的类型设置。如果不想过滤值，可将列表属性设置为空列表。
list	过滤器的值列表。如果不想过滤值，可将列表属性设置为空列表。

通常，仅存在一种可用的过滤器类型。只有长整型、双精度型、线性单位、面积单位和时间单位参数有两种选择：ValueList 和范围。

值列表

该过滤器可用于提供一组关键字。许多工具都具有一组预定义的关键字，如添加字段工具中的字段类型参数，或叠加分析工具集中多个工具的连接属性参数。

值列表过滤器可用于长整型、双精度型、线性单位、面积单位和时间单位数据类型。对于这些类型，需输入允许的数值或单位值。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input value",
        name="in_value",
        datatype="GPLong",
        parameterType="Required",
        direction="Input")

    # Set a value list of 1, 10 and 100
    param0.filter.type = "ValueList"
    param0.filter.list = [1, 10, 100]

如果您希望用户可以选择多个值，请将 multiValue 属性设置为 True。

值列表过滤器还可用于布尔数据类型。对于布尔数据类型，此过滤器将包含两个值：true 和 false。这些值用于在 Python 中指定值。值 true 是列表中的第一个值。相关示例，请参阅添加字段以及用于 field_is_nullable 参数的 NULLABLE 和 NON_NULLABLE 关键字。

范围

范围过滤器具有两个值：最小值和最大值。列表中的第一个值是最小值。范围包括边界值，表示最小值和最大值也是有效数据。长整型、双精度型、线性单位、面积单位和时间单位参数可以使用此过滤器。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input range",
        name="in_range",
        datatype="GPLong",
        parameterType="Required",
        direction="Input")

    # Set an acceptable range of 1 to 10
    param0.filter.type = "Range"
    param0.filter.list = [1, 10]

要素类

对于此过滤器，可以选择一个或多个过滤器值。将使用过滤器值来检查输入要素类。例如，如果选择“点”作为唯一的过滤器值，则用户只能输入点要素类作为参数值。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")
    param0.filter.list = ["Polygon"]

文件

文件过滤器包含文件可具有的文件后缀的列表，如 txt（简单文本文件）和 csv（逗号分隔值）。您可以提供任何后缀的文本，不必是 ArcGIS 可识别的后缀。后缀可为任意长度，且不包含句点。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input File",
        name="in_file",
        datatype="DEFile",
        parameterType="Required",
        direction="Input")

    # To define a file filter that includes .csv and .txt extensions,
    #  set the filter list to a list of file extension names
    param0.filter.list = ['txt', 'csv']

字段

字段过滤器用于定义允许的字段类型：以上过滤器类型表中提供了这些值。可以提供多个值。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")

    param1 = arcpy.Parameter(
        displayName="Field",
        name="field",
        datatype="Field",
        parameterType="Required",
        direction="Input")

    # Set the filter to accept only fields that are Short or Long type
    param1.filter.list = ['Short', 'Long']
    param1.parameterDependencies = [param0.name]

工作空间

工作空间过滤器用于指定允许的输入工作空间的类型。这些值的描述如下：


值	描述
文件系统	系统文件夹，用于存储 shapefile 和格网
本地数据库	个人地理数据库或文件地理数据库
远程数据库	企业级数据库连接

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Workspace",
        name="in_workspace",
        datatype="DEWorkspace",
        parameterType="Required",
        direction="Input")

    # Set the filter to accept only local geodatabases
    param0.filter.list = ["Local Database"]

出行模式单位类型

此过滤器可用于基于出行模式的阻抗属性单位来设置允许的出行模式类型。

def getParameterInfo(self):
    param1 = arcpy.Parameter(
        displayName="Travel Mode",
        name="travel_mode",
        datatype="NetworkTravelMode",
        parameterType="Required",
        direction="Input")

     # Set the parameter to be dependent on the Network Data Source parameter
     param1.parameterDependencies = [param0.name]
     # Set the filter to accept only time-based travel modes
     param1.filter.list = ["Time"]

依赖关系

parameterDependencies 属性具有以下用途：

对于具有派生类型的输出数据集参数，相关性为派生输出的参数的索引。
对于特定的输入数据类型，依赖项为含有控件所用信息的参数的索引，如下表所示。

# Third parameter
param2 = arcpy.Parameter(
    displayName="Output Features",
    name="out_features",
    datatype="GPFeatureLayer",
    parameterType="Derived",
    direction="Output")

param2.parameterDependencies = [param0.name]
param2.schema.clone = True

只能为特定输入参数设置 parameterDependencies 值，如下表所示：

parameterDependencies 数据类型
参数数据类型	相关参数数据类型
面积单位 (GPArealUnit)	用于确定默认单位的地理数据集。例如，可以使用要素图层 (GPFeatureLayer)、栅格图层 (GPRasterLayer)、要素集 (GPFeatureRecordSetLayer) 或记录集 (GPRecordSet) 数据类型。
字段 (Field)	含有字段的表。例如，可以使用表视图 (GPTableView)、要素图层 (GPFeatureLayer)、栅格图层 (GPRasterLayer)、要素集 (GPFeatureRecordSetLayer) 或记录集 (GPRecordSet) 数据类型。
字段映射 (GPFieldMapping)	一个或多个输入表中的字段集合。例如，可以使用表视图 (GPTableView)、要素图层 (GPFeatureLayer)、栅格图层 (GPRasterLayer)、要素集 (GPFeatureRecordSetLayer) 或记录集 (GPRecordSet) 数据类型。
地统计值表 ( GPGAValueTable)	包含要用于 Geostatistical Analyst 工具的数据集和字段的表使用地统计图层 (GPGALayer) 数据类型。
线性单位 (GPLinearUnit)	用于确定默认单位的地理数据集。例如，可以使用要素图层 (GPFeatureLayer)、栅格图层 (GPRasterLayer)、要素集 (GPFeatureRecordSetLayer) 或记录集 (GPRecordSet) 数据类型。
Network Analyst 等级设置 (GPNAHierarchySettings)	包含等级信息的网络数据集。使用网络数据集 (DENetworkDataset) 数据类型。
网络出行模式 (NetworkTravelMode)	出行模式列表。使用网络数据源 (GPNetworkDataSource)、网络数据集 (DENetworkDataset) 或网络数据集图层 (GPNetworkDatasetLayer) 数据类型。
SQL 表达式 (GPSQLExpression)	含有字段的表。例如，可以使用表视图 (GPTableView)、要素图层 (GPFeatureLayer)、栅格图层 (GPRasterLayer)、要素集 (GPFeatureRecordSetLayer) 或记录集 (GPRecordSet) 数据类型。

符号系统

如果工具的输出为要素集、栅格、TIN 或 Network Analyst 图层，则可以使用 symbology 属性指定图层文件 (.lyrx) 的位置。运行工具时，将输出添加到显示中，并将使用符号系统图层文件中定义的符号系统进行绘制。

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Raster",
        name="in_raster",
        datatype="DERasterDataset",
        parameterType="Required",
        direction="Input")

    param1 = arcpy.Parameter(
        displayName="Output Raster",
        name="out_raster",
        datatype="DERasterDataset",
        parameterType="Required",
        direction="Output")

    # Use __file__ attribute to find the .lyr file (assuming the
    #  .pyt and .lyr files exist in the same folder).
    param1.symbology = os.path.join(os.path.dirname(__file__), 
                                    'raster_symbology.lyrx')

注：

每次运行工具时都会读取图层文件。如果未找到图层文件（因为被移动或删除），将使用默认符号系统。

类别

可以将参数分为不同的类别，从而最小化工具对话框的大小或将不常使用的相关参数分为一组。将 category 属性设置为相同字符串值的参数将分为一组。多个 ArcGIS Network Analyst extension 工具使用了如下类别。

类别将显示在非类别化参数之后。请勿将所需参数放入类别中，这会导致其在工具对话框的视图中处于隐藏状态。