Freigeben über

Abrufen von Benutzereingaben für Skripts

  • Artikel

Durch das Hinzufügen von Parametern zu Ihrem Skript können andere Benutzer Daten für das Skript bereitstellen, ohne Code bearbeiten zu müssen. Wenn Ihr Skript über das Menüband oder eine Schaltfläche ausgeführt wird, wird eine Eingabeaufforderung angezeigt, die zur Eingabe auffordert.

Das Dialogfeld, das Benutzern angezeigt wird, wenn ein Skript mit Parametern ausgeführt wird.

Wichtig

Derzeit werden nur Benutzer von Excel im Web aufgefordert, Daten für parametrisierte Skripts einzugeben. Power Automate-Flows unterstützen auch das Bereitstellen von Daten an Skripts über Parameter.

Beispiel: Hervorheben großer Werte

Das folgende Beispiel zeigt ein Skript, das eine Zahl und eine Zeichenfolge vom Benutzer akzeptiert. Öffnen Sie zum Testen eine leere Arbeitsmappe, und geben Sie einige Zahlen in mehrere Zellen ein.

/**
 * This script applies a background color to cells over a certain value.
 * @param highlightThreshold The value used for comparisons.
 * @param color A string representing the color to make the high value cells. 
 *   This must be a color code representing the color of the background, 
 *   in the form #RRGGBB (e.g., "FFA500") or a named HTML color (e.g., "orange").
 */
function main(
  workbook: ExcelScript.Workbook, 
  highlightThreshold: number, 
  color: string) {
    // Get the used cells in the current worksheet.
    const currentSheet = workbook.getActiveWorksheet();
    const usedRange = currentSheet.getUsedRange();
    
    const rangeValues = usedRange.getValues();
    for (let row = 0; row < rangeValues.length; row++) {
        for (let column = 0; column < rangeValues[row].length; column++) {
          if (rangeValues[row][column] >= highlightThreshold) {
              usedRange.getCell(row, column).getFormat().getFill().setColor(color);
          }
        }
    }
}

main Parameters: Übergeben von Daten an ein Skript

Alle Skripteingaben werden als zusätzliche Parameter für die main Funktion angegeben. Neue Parameter werden nach dem obligatorischen workbook: ExcelScript.Workbook Parameter hinzugefügt. Wenn Sie beispielsweise möchten, dass ein Skript ein string akzeptiert, das einen Namen als Eingabe darstellt, ändern Sie die main Signatur in function main(workbook: ExcelScript.Workbook, name: string).

Optionale Parameter

Bei optionalen Parametern muss der Benutzer keinen Wert angeben. Dies impliziert, dass Ihr Skript entweder ein Standardverhalten aufweist oder dieser Parameter nur in einem Eckfall benötigt wird. Sie werden in Ihrem Skript mit dem optionalen Modifizierer? gekennzeichnet. Beispielsweise ist der - function main(workbook: ExcelScript.Workbook, Name?: string) Parameter Name optional.

Standardparameterwerte

Standardparameterwerte füllen das Feld der Aktion automatisch mit einem Wert aus. Um einen Standardwert festzulegen, weisen Sie dem Parameter in der main Signatur einen Wert zu. Beispielsweise hat der function main(workbook: ExcelScript.Workbook, location: string = "Seattle") -Parameter location den -Wert "Seattle" , es sei denn, es wird etwas anderes angegeben.

Helfen Sie anderen, Ihr Skript in ihrem Flow zu verwenden, indem Sie eine Liste zulässiger Parameteroptionen bereitstellen. Wenn ihr Skript eine kleine Teilmenge von Werten verwendet, erstellen Sie einen Parameter, der diese Literalwerte ist. Deklarieren Sie dazu den Parametertyp als Vereinigung von Literalwerten. Im -Parameter location kann z. Bfunction main(workbook: ExcelScript.Workbook, location: "Seattle" | "Redmond"). nur oder "Redmond"sein"Seattle". Wenn das Skript ausgeführt wird, erhalten Benutzer eine Dropdownliste mit diesen beiden Optionen.

Dokumentieren des Skripts

Codekommentare, die den JSDoc-Standards entsprechen, werden benutzern angezeigt, wenn sie Ihr Skript ausführen. Je mehr Details Sie in die Beschreibungen einfügen, desto einfacher ist es für andere, die Skripts zu verwenden. Beschreiben Sie den Zweck der einzelnen Eingabeparameter und alle Einschränkungen oder Grenzwerte. Das folgende JSDoc-Beispiel zeigt, wie ein Skript mit einem number Parameter namens dokumentiert wird taxRate.

/**
 * A script to apply the current tax rate to sales figures.
 * @param taxRate The current sales tax rate in the region as a decimal number (enter 12% as .12).
 */
function main(workbook: ExcelScript.Workbook, taxRate: number)

Hinweis

Sie müssen den ExcelScript.Workbook Parameter nicht in jedem Skript dokumentieren.

Typeinschränkungen

Berücksichtigen Sie beim Hinzufügen von Eingabeparametern und Rückgabewerten die folgenden Zertifikate und Einschränkungen.

  1. Der erste Parameter muss vom Typ ExcelScript.Workbooksein. Der Parametername spielt keine Rolle.

  2. Die Typen string, number, boolean, unknownund object.

  3. Arrays (sowohl als auch []Array<T> Formatvorlagen) der zuvor aufgeführten Typen werden unterstützt. Geschachtelte Arrays werden ebenfalls unterstützt.

  4. Union-Typen sind zulässig, wenn es sich um eine Vereinigung von Literalen handelt, die zu einem einzelnen Typ gehören (z "Left" | "Right". B. , nicht "Left" | 5).

  5. Objekttypen sind zulässig, wenn sie Eigenschaften vom Typ string, number, booleanunterstützte Arrays oder andere unterstützte Objekte enthalten. Das folgende Beispiel zeigt geschachtelte Objekte, die als Parametertypen unterstützt werden.

    // The Employee object is supported because Position is also composed of supported types.
interface Employee {
    name: string;
    job: Position;
}

interface Position {
    id: number;
    title: string;
}

  6. Für Objekte muss ihre Schnittstellen- oder Klassendefinition im Skript definiert sein. Ein Objekt kann auch anonym inline definiert werden, wie im folgenden Beispiel gezeigt.

    function main(workbook: ExcelScript.Workbook, contact: {name: string, email: string})

Siehe auch