Anpassen von Werkzeugverhalten in einer Python-Toolbox
Die Validierung umfasst alle Schritte, bevor auf die Schaltfläche OK eines Werkzeugs geklickt wird. Wenn Sie benutzerdefinierte Werkzeuge erstellen, können Sie anhand der Validierung anpassen, wie Parameter reagieren und mit Werten und anderen Parametern interagieren. Die Validierung erfolgt mit einem Python-Code-Block, der zum Steuern des Werkzeugverhaltens verwendet wird.
Weitere Informationen zur Validierung finden Sie unter Validierung in Skriptwerkzeugen.
In einer Python-Toolbox verfügt jeder Werkzeugparameter über ein zugehöriges Parameter-Objekt mit Eigenschaften und Methoden, die für die Werkzeugvalidierung nützlich sind. In einer Python-Toolbox erfolgt die Definition von Parametern in der getParameterInfo-Methode der Werkzeugklasse. Das Verhalten dieser Parameter und ihre Interaktion miteinander und mit den Eingaben wird entsprechend der updateParameters-Methode der Werkzeugklasse überprüft.
Zugreifen auf Werkzeugparameter
Parameter-Objekte bilden die Grundlage für die Definition und Interaktion der Parameter in einer Python-Toolbox. Normalerweise wird die Parameterliste, wie im folgenden Code zu sehen, in der Methode getParameterInfo der Werkzeugklasse erstellt.
def getParameterInfo(self):
#Define parameter definitions
# First parameter
param0 = arcpy.Parameter(
displayName="Input Features",
name="in_features",
datatype="GPFeatureLayer",
parameterType="Required",
direction="Input")
return [param0]
Weitere Informationen zum Definieren von Parametern in einer Python-Toolbox finden Sie unter Definieren von Parametern in einer Python-Toolbox.
Parameterobjekt
Methoden
Methodenname |
Verwendung |
---|---|
setErrorMessage(message:string) |
Kennzeichnet den Parameter als fehlerhaft (rotes X) und gibt die entsprechende Meldung aus. Werkzeuge werden nicht ausgeführt, wenn ein Parameter einen Fehler aufweist. |
setWarningMessage(message:string) |
Gibt an, dass für den Parameter eine Warnung vorliegt (gelbes Dreieck), und gibt die entsprechende Meldung aus. Anders als bei Fehlern werden Werkzeuge bei Warnmeldungen ausgeführt. |
setIDMessage(messageType: string, messageID: string, {AddArgument1}, {AddArgument2}) |
Ermöglicht Ihnen das Festlegen einer Systemmeldung. Die Argumente entsprechen denen der AddIDMessage-Funktion. |
clearMessage() |
Löscht alle Meldungstexte und setzt den Status auf "Information" (kein Fehler und keine Warnung). |
hasError() |
Gibt "true" zurück, wenn der Parameter einen Fehler enthält. |
hasWarning() |
Gibt "true" zurück, wenn für den Parameter eine Warnung vorliegt. |
isInputValueDerived() |
Gibt "true" zurück, wenn das Werkzeug in einem Modell überprüft wird und der Eingabewert der Ausgabe eines anderen Werkzeugs im Modell entspricht. |
Eigenschaften
Name der Eigenschaft |
Lesen/Schreiben |
Werte |
Beschreibung |
---|---|---|---|
name |
Nur Lesen |
String |
Der Parametername |
direction |
Nur Lesen |
String: "Input", "Output" |
Eingabe-/Ausgaberichtung des Parameters |
datatype |
Nur Lesen |
String |
Eine Liste von Parameterdatentypen finden Sie unter Definieren von Parameterdatentypen in einer Python-Toolbox. |
parameterType |
Nur Lesen |
String: "Required", "Optional", "Derived" |
Der Parametertyp |
parameterDependencies |
Lesen/Schreiben |
Python-Liste |
Eine Liste der Indexwerte für jeden abhängigen Parameter |
value |
Lesen/Schreiben |
Wertobjekt |
Der Wert des Parameters |
defaultEnvironmentName |
Nur Lesen |
String |
Die Standardeinstellung für environment. |
enabled |
Lesen/Schreiben |
Boolesch |
"False", wenn der Parameter nicht verfügbar ist. |
altered |
Nur Lesen |
Boolesch |
"True", wenn der Wert geändert wurde. |
hasBeenValidated |
Nur Lesen |
Boolesch |
"True", wenn der Parameter von der internen Prüfroutine geprüft wurde. |
category |
Lesen/Schreiben |
String |
Die Kategorie des Parameters. |
schema |
Nur Lesen |
Schema-Objekt |
Das Schema des Ausgabe-Datasets. |
filter |
Nur Lesen |
Filter-Objekt |
Der auf die Werte im Parameter angewendete Filter. |
symbology |
Lesen/Schreiben |
String |
Der Pfad zu einer Layer-Datei (.lyr), die zur Darstellung der Ausgabe verwendet wird. |
message |
Nur Lesen |
String |
Die angezeigte Meldung. Siehe oben: SetErrorMessage und SetWarningMessage |
parameterDependencies
Parameterabhängigkeiten werden normalerweise für die Verwendung durch das Schema-Objekt definiert. Es gibt zwei Fälle, in denen die Abhängigkeiten unter Umständen bereits in der getParameterInfo-Methode des Werkzeugs festgelegt sind.
- Bei einem Ausgabe-Dataset-Parameter mit dem Typ "Derived" ist die Abhängigkeit der Indexwert des Parameters, von dem die Ausgabe abgeleitet wird.
- Bei bestimmten Eingabedatentypen ist die Abhängigkeit der Indexwert des Parameters, der die vom Steuerelement verwendeten Informationen enthält (siehe folgende Tabelle).
Eingabedatentyp |
Abhängiger Datentyp |
Beschreibung |
---|---|---|
Feld oder SQL-Ausdruck |
Tabelle |
Die Tabelle mit den Feldern |
INFO-Feld oder INFO-Ausdruck |
INFO-Tabelle |
Die INFO-Tabelle mit den Feldern |
Coverage-Feature-Class |
Coverage |
Das Coverage mit den Features |
Flächeneinheiten oder lineare Einheiten |
GeoDataset |
Geographisches Dataset, das zum Ermitteln der Standardeinheiten verwendet wird |
Koordinatensystem |
Workspace |
Workspace, der zum Ermitteln des Standardkoordinatensystems verwendet wird |
Hierarchie-Einstellungen für Network Analyst |
Netzwerk-Dataset |
Netzwerk-Dataset mit den Informationen zur Hierarchie |
Geostatistische Wertetabelle |
Geostatistischer Layer |
Der Analyse-Layer mit den Tabellen |
![Hinweis Hinweis](rsrc/note.png)
parameterDependencies entspricht der Einstellung Abgerufen von des Skriptwerkzeug-Assistenten.
Abhängigkeiten werden normalerweise in der Methode getParameterInfo festgelegt:
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
value
Dies ist der vom Benutzer eingegebene oder von Ihnen durch Programmierung festgelegte Wert des Parameters. Sie können den Wert in der Methode getParameterInfo festlegen. In diesem Fall wird der Wert als anfänglicher Standardwert für den Parameter verwendet. Sie können den Wert auch in updateParameters als Reaktion auf Benutzereingaben festlegen, wie unten dargestellt.
def updateParameters(self, parameters):
# Set the default distance threshold to 1/100 of the larger of the width
# or height of the extent of the input features. Do not set if there is no
# input dataset yet, or the user has set a specific distance (Altered is true).
#
if parameters[0].value:
if not parameters[6].altered:
extent = arcpy.Describe(parameters[0].value).extent
if extent.width > extent.height:
parameters[6].value = extent.width / 100
else:
parameters[6].value = extent.height / 100
return
Die Eigenschaft value eines Parameters gibt ein Objekt wieder, es sei denn, der Parameter ist nicht gefüllt, wodurch value None zurückgibt. Um zu verhindern, dass ein Parameter nicht gefüllt wird, führen Sie eine if-Prüfung durch, bevor Sie dessen Wert verwenden.
Mit dem folgenden Codeausschnitt wird überprüft, ob der Wert der Zeichenfolge "Get Spatial Weights From File" entspricht. Die Überprüfung funktioniert, weil es sich beim Datentyp des Parameters um eine Zeichenfolge handelt.
# If the option to use a weights file is selected, enable the
# parameter for specifying the file, otherwise disable it
if parameters[3].value: # check that parameter has a value
if parameters[3].value == "Get Spatial Weights From File":
parameters[8].enabled = True
else:
parameters[8].enabled = False
Verwenden Sie die Werteigenschaft des Wertobjekts, wenn eine Zeichenfolge bearbeitet oder analysiert werden soll, da ein Wertobjekt die Bearbeitung von Zeichenfolgen nicht unterstützt. Das Codebeispiel verwendet die os.path.dirname-Methode, um das Verzeichnis aus einem Dataset zurückzugeben.
if parameters[0].value:
workspace = os.path.dirname(parameters[0].value.value)
![Hinweis Hinweis](rsrc/note.png)
With the exception of Describe, don't use methods that take a catalog path, such as ListFields, in validation. The dataset may not exist when your tool is validated in ModelBuilder, and the method may fail or give unexpected results.
In the specific case of ListFields, the Describe object's fields property will provide the equivalent information.
![Hinweis Hinweis](rsrc/note.png)
Don't set a parameter value in updateMessages() since the value will not be validated by the internal validation routine.
altered
altered ist "true", wenn der Wert eines Parameters geändert wurde, zum Beispiel durch Eingabe eines Ausgabepfades. Nachdem der Parameter geändert wurde, bleibt er geändert, bis der Benutzer den Wert leert (ausblendet). Dann kehrt er zu seinem nicht geänderten Zustand zurück. Eine programmatische Änderung eines Wertes durch Validierungscode hat keine Auswirkung auf den geänderten Zustand. Wenn Sie also einen Wert für einen Parameter festlegen, bleibt der geänderte Zustand (altered) des Parameters unverändert.
Mit altered können Sie ermitteln, ob der Wert eines Parameters geändert werden kann. Beispiel: Ein Werkzeug verfügt über einen Feature-Class-Parameter und einen Schlüsselwortparameter. Wenn die Feature-Class Punkte oder Polygone enthält, lauten die Schlüsselwörter ROT, GRÜN und BLAU. Bei Linien lauten sie ORANGE, GELB, LILA und WEISS.
Der Benutzer gibt eine Point-Feature-Class ein. Wird der Schlüsselwortparameter nicht geändert, setzen Sie den Wert auf ROT, da dies der Standardwert ist.
Gibt der Benutzer dann eine Line-Feature-Class ein, legen Sie den Standardwert als ORANGE fest, solange der Schlüsselwortparameter nicht geändert wird.
Wenn der Schlüsselwortparameter allerdings vom Benutzer geändert wird (das heißt, das Schlüsselwort wird auf GRÜN festgelegt), sollten Sie das Schlüsselwort nicht zurücksetzen, da der Benutzer eine Wahl getroffen hat (GRÜN) und Sie die zugrunde liegende Absicht nicht kennen. Eventuell ändert der Benutzer die Feature-Class, sodass GRÜN ein gültiger Wert ist, oder er ändert das Schlüsselwort (etwa in LILA). Da GRÜN nicht zur Gruppe der Schlüsselwörter gehört, die Sie für Linien definiert haben, wird der Parameter von der internen Prüfung als fehlerhaft gekennzeichnet. Der Benutzer hat dann zwei Möglichkeiten: Änderung der Eingabe-Feature-Class oder Änderung des Schlüsselworts
if not parameters[2].altered:
parameters[2].value = "POINT"
hasBeenValidated
hasBeenValidated ist "false", wenn der Wert eines Parameters seit dem letzten Aufruf von updateParameters und der letzten internen Prüfung geändert wurde. Nach dem Aufruf der internen Prüfung wird hasBeenValidated für jeden Parameter von der Geoverarbeitung automatisch auf "true" festgelegt.
Mit hasBeenValidated wird ermittelt, ob ein Wert seit dem letzten Aufruf von updateParameters geändert wurde. Sie können diese Information bei der Entscheidung heranziehen, ob Sie Ihre eigene Überprüfung des Parameters vornehmen möchten.
def updateParameters(self, parameters):
# Set the default distance threshold to 1/100 of the larger of the width
# or height of the extent of the input features. Do not set if there is no
# input dataset yet, or the user has set a specific distance (Altered is true).
#
if parameters[0].value:
if not parameters[6].altered:
extent = arcpy.Describe(parameters[0].value).extent
if extent.width > extent.height:
parameters[6].value = extent.width / 100
else:
parameters[6].value = extent.height / 100
return