|
| 1 | +--- |
| 2 | +title: Get user input for scripts |
| 3 | +description: Add parameters to Office Scripts so users can control their experience. |
| 4 | +ms.date: 08/22/2023 |
| 5 | +ms.localizationpriority: medium |
| 6 | +--- |
| 7 | + |
| 8 | +# Get user input for scripts |
| 9 | + |
| 10 | +Adding parameters to your script lets other users provide data for the script, without needing to edit code. When your script is run through the ribbon or a button, a prompt pops up that asks for input. |
| 11 | + |
| 12 | +:::image type="content" source="../images/user-input-example.png" alt-text="The dialog box shown to users when a script with parameters is run."::: |
| 13 | + |
| 14 | +> [!IMPORTANT] |
| 15 | +> Currently, only select users in preview will be prompted to enter data for parameterized scripts in Excel on the web. Power Automate flows also support giving data to scripts through parameters. |
| 16 | +
|
| 17 | +## Example - Highlight large values |
| 18 | + |
| 19 | +The following example shows a script that takes a number and string from the user. To test it, open an empty workbook and enter some numbers into several cells. |
| 20 | + |
| 21 | +```TypeScript |
| 22 | +/** |
| 23 | + * This script applies a background color to cells over a certain value. |
| 24 | + * @param highlightThreshold The value used for comparisons. |
| 25 | + * @param color A string representing the color to make the high value cells. |
| 26 | + * This must be a color code representing the color of the background, |
| 27 | + * in the form #RRGGBB (e.g., "FFA500") or a named HTML color (e.g., "orange"). |
| 28 | + */ |
| 29 | +function main( |
| 30 | + workbook: ExcelScript.Workbook, |
| 31 | + highlightThreshold: number, |
| 32 | + color: string) { |
| 33 | + // Get the used cells in the current worksheet. |
| 34 | + const currentSheet = workbook.getActiveWorksheet(); |
| 35 | + const usedRange = currentSheet.getUsedRange(); |
| 36 | + |
| 37 | + const rangeValues = usedRange.getValues(); |
| 38 | + for (let row = 0; row < rangeValues.length; row++) { |
| 39 | + for (let column = 0; column < rangeValues[row].length; column++) { |
| 40 | + if (rangeValues[row][column] >= highlightThreshold) { |
| 41 | + usedRange.getCell(row, column).getFormat().getFill().setColor(color); |
| 42 | + } |
| 43 | + } |
| 44 | + } |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +## `main` parameters: Pass data to a script |
| 49 | + |
| 50 | +All script input is specified as additional parameters for the `main` function. New parameters are added after the mandatory `workbook: ExcelScript.Workbook` parameter. For example, if you wanted a script to accept a `string` that represents a name as input, you would change the `main` signature to `function main(workbook: ExcelScript.Workbook, name: string)`. |
| 51 | + |
| 52 | +### Optional parameters |
| 53 | + |
| 54 | +Optional parameters don't need the user to provide a value. This implies your script either has default behavior or this parameter is only needed in a corner case. They're denoted in your script with the [optional modifier](https://www.typescriptlang.org/docs/handbook/2/functions.html#optional-parameters) `?`. For example, in `function main(workbook: ExcelScript.Workbook, Name?: string)` the parameter `Name` is optional. |
| 55 | + |
| 56 | +### Default parameter values |
| 57 | + |
| 58 | +[Default parameter values](https://www.typescriptlang.org/docs/handbook/variable-declarations.html#default-values) automatically fill the action's field with a value. To set a default value, assign a value to the parameter in the `main` signature. For example, in `function main(workbook: ExcelScript.Workbook, location: string = "Seattle")` the parameter `location` has the value `"Seattle"` unless something else is provided. |
| 59 | + |
| 60 | +### Dropdown lists for parameters |
| 61 | + |
| 62 | +Help others using your script in their flow by providing a list of acceptable parameter choices. If there's a small subset of values that your script uses, create a parameter that is those literal values. Do this by declaring the parameter type to be a [union of literal values](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types). For example, in `function main(workbook: ExcelScript.Workbook, location: "Seattle" | "Redmond")` the parameter `location` can only be `"Seattle"` or `"Redmond"`. When the script is run, users get a dropdown list with those two options. |
| 63 | + |
| 64 | +### Document the script |
| 65 | + |
| 66 | +Code comments that follow [JSDoc](https://en.wikipedia.org/wiki/JSDoc) standards will be shown to people when they run your script. The more details you put in the descriptions, the easier it'll be for others to the scripts. Describe the purpose of each input parameter and any restrictions or limits. The following sample JSDoc shows how to document a script with a `number` parameter called `taxRate`. |
| 67 | + |
| 68 | +```TypeScript |
| 69 | +/** |
| 70 | + * A script to apply the current tax rate to sales figures. |
| 71 | + * @param taxRate The current sales tax rate in the region as a decimal number (enter 12% as .12). |
| 72 | + */ |
| 73 | +function main(workbook: ExcelScript.Workbook, taxRate: number) |
| 74 | +``` |
| 75 | + |
| 76 | +> [!NOTE] |
| 77 | +> You don't need to document the `ExcelScript.Workbook` parameter in every script. |
| 78 | + |
| 79 | +## Type restrictions |
| 80 | + |
| 81 | +When adding input parameters and return values, consider the following allowances and restrictions. |
| 82 | + |
| 83 | +1. The first parameter must be of type `ExcelScript.Workbook`. Its parameter name doesn't matter. |
| 84 | + |
| 85 | +1. The types `string`, `number`, `boolean`, `unknown`, and `object`. |
| 86 | + |
| 87 | +1. Arrays (both `[]` and `Array<T>` styles) of the previously listed types are supported. Nested arrays are also supported. |
| 88 | + |
| 89 | +1. Union types are allowed if they're a union of literals belonging to a single type (such as `"Left" | "Right"`, not `"Left" | 5`). |
| 90 | + |
| 91 | +1. Object types are allowed if they contain properties of type `string`, `number`, `boolean`, supported arrays, or other supported objects. The following example shows nested objects that are supported as parameter types. |
| 92 | + |
| 93 | + ```TypeScript |
| 94 | + // The Employee object is supported because Position is also composed of supported types. |
| 95 | + interface Employee { |
| 96 | + name: string; |
| 97 | + job: Position; |
| 98 | + } |
| 99 | +
|
| 100 | + interface Position { |
| 101 | + id: number; |
| 102 | + title: string; |
| 103 | + } |
| 104 | + ``` |
| 105 | + |
| 106 | +1. Objects must have their interface or class definition defined in the script. An object can also be defined anonymously inline, as in the following example. |
| 107 | + |
| 108 | + ```TypeScript |
| 109 | + function main(workbook: ExcelScript.Workbook, contact: {name: string, email: string}) |
| 110 | + ``` |
| 111 | + |
| 112 | +## See also |
| 113 | + |
| 114 | +- [Pass data to and from scripts in Power Automate](power-automate-parameters-returns.md) |
| 115 | +- [Run Office Scripts in Excel with buttons](script-buttons.md) |
0 commit comments