From 86012d4f0cf50f26e720191a014c7a7690afd3cf Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Tue, 26 Aug 2025 13:27:46 -0700 Subject: [PATCH] [excel] (Parameterized scripts) Add workbook import feature (#797) * Update user-input.md * Move support note * Incorporate Copilot feedback * Remove platform support limit --- docs/develop/user-input.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/develop/user-input.md b/docs/develop/user-input.md index 4bdc96c1..be3bd384 100644 --- a/docs/develop/user-input.md +++ b/docs/develop/user-input.md @@ -1,20 +1,17 @@ --- title: Get user input for scripts description: Add parameters to Office Scripts so users can control their experience. -ms.date: 09/14/2023 +ms.date: 08/22/2025 ms.localizationpriority: medium --- # Get user input for scripts -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. +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 the user for input, such as an array or a workbook. :::image type="content" source="../images/user-input-example.png" alt-text="The dialog box shown to users when a script with parameters is run."::: -> [!IMPORTANT] -> Currently, only Excel on the web users will be prompted to enter data for parameterized scripts. Power Automate flows also support giving data to scripts through parameters. - -## Example - Highlight large values +## Example scenario: Highlight large values 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. @@ -49,6 +46,20 @@ function main( 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)`. +To allow users to import a workbook with a parameterized script, use a two-dimensional array for each parameter that accepts a workbook. The parameter can be of type `string` or `number`. The following example shows how to create a script that accepts workbook imports for both parameters. + +```TypeScript +/**​ + * 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. +}​ +``` + ### Optional parameters 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.