Partager via

Obtenir une entrée utilisateur pour les scripts

L’ajout de paramètres à votre script permet à d’autres utilisateurs de fournir des données pour le script, sans avoir à modifier le code. Lorsque votre script est exécuté via le ruban ou un bouton, une invite s’affiche pour demander à l’utilisateur une entrée, telle qu’un tableau ou un classeur.

Boîte de dialogue affichée aux utilisateurs lorsqu’un script avec des paramètres est exécuté.

Exemple de scénario : Mettre en surbrillance des valeurs volumineuses

L’exemple suivant montre un script qui prend un nombre et une chaîne de l’utilisateur. Pour le tester, ouvrez un classeur vide et entrez des nombres dans plusieurs cellules.

/**
 * 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 paramètres : passer des données à un script

Toutes les entrées de script sont spécifiées en tant que paramètres supplémentaires pour la main fonction. De nouveaux paramètres sont ajoutés après le paramètre obligatoire workbook: ExcelScript.Workbook . Par exemple, si vous souhaitez qu’un script accepte un string qui représente un nom en tant qu’entrée, vous devez remplacer la signature par mainfunction main(workbook: ExcelScript.Workbook, name: string).

Pour permettre aux utilisateurs d’importer un classeur avec un script paramétrable, utilisez un tableau à deux dimensions pour chaque paramètre qui accepte un classeur. Le paramètre peut être de type string ou number. L’exemple suivant montre comment créer un script qui accepte les importations de classeur pour les deux paramètres.

/**​
 * This script generates a monthly sales report.​
 * @param productData The product data for this month.
 * @param salesData The sales data for this month.​
 */
function main(workbook: ExcelScript.Workbook, productData: string[][], salesData: string[][]) {
    // Code to process data goes here.
    // Both the `productData` and `salesData` parameters accept workbook imports.
}​

Paramètres facultatifs

Les paramètres facultatifs n’ont pas besoin que l’utilisateur fournisse une valeur. Cela implique que votre script a un comportement par défaut ou que ce paramètre n’est nécessaire que dans un cas d’angle. Ils sont indiqués dans votre script avec le modificateur? facultatif. Par exemple, dans function main(workbook: ExcelScript.Workbook, Name?: string) le paramètre Name est facultatif.

Valeurs des paramètres par défaut

Les valeurs de paramètre par défaut remplissent automatiquement le champ de l’action avec une valeur. Pour définir une valeur par défaut, affectez une valeur au paramètre dans la main signature. Par exemple, dans function main(workbook: ExcelScript.Workbook, location: string = "Seattle") le paramètre location a la valeur "Seattle" , sauf si un autre élément est fourni.

Aidez les autres utilisateurs à utiliser votre script dans leur flux en fournissant une liste de choix de paramètres acceptables. Si votre script utilise un petit sous-ensemble de valeurs, créez un paramètre qui correspond à ces valeurs littérales. Pour ce faire, déclarez le type de paramètre comme étant une union de valeurs littérales. Par exemple, dans function main(workbook: ExcelScript.Workbook, location: "Seattle" | "Redmond") le paramètre location ne peut être "Seattle" que ou "Redmond". Lorsque le script est exécuté, les utilisateurs obtiennent une liste déroulante avec ces deux options.

Documenter le script

Les commentaires de code qui suivent les normes JSDoc sont affichés aux utilisateurs lorsqu’ils exécutent votre script. Plus vous placez de détails dans les descriptions, plus il sera facile pour les autres utilisateurs d’accéder aux scripts. Décrire l’objectif de chaque paramètre d’entrée et toutes les restrictions ou limites. L’exemple JSDoc suivant montre comment documenter un script avec un number paramètre appelé 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)

Remarque

Vous n’avez pas besoin de documenter le ExcelScript.Workbook paramètre dans chaque script.

Restrictions de type

Lorsque vous ajoutez des paramètres d’entrée et des valeurs de retour, tenez compte des quotas et restrictions suivants.

  1. Le premier paramètre doit être de type ExcelScript.Workbook. Son nom de paramètre n’a pas d’importance.

  2. Les types string, number, boolean, unknownet object.

  3. Les tableaux (et Array<T> les [] styles) des types répertoriés précédemment sont pris en charge. Les tableaux imbriqués sont également pris en charge.

  4. Les types union sont autorisés s’il s’agit d’une union de littéraux appartenant à un type unique (par "Left" | "Right"exemple , et non "Left" | 5).

  5. Les types d’objets sont autorisés s’ils contiennent des propriétés de type string, number, boolean, des tableaux pris en charge ou d’autres objets pris en charge. L’exemple suivant montre des objets imbriqués qui sont pris en charge en tant que types de paramètres.

    // 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. L’interface ou la définition de classe des objets doivent être définies dans le script. Un objet peut également être défini de manière anonyme inline, comme dans l’exemple suivant.

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

Voir aussi

  • Last updated on