Share via

Obtención de la entrada de usuario para scripts

  • Artículo

Agregar parámetros al script permite a otros usuarios proporcionar datos para el script, sin necesidad de editar el código. Cuando el script se ejecuta a través de la cinta de opciones o un botón, aparece un mensaje que pide entrada.

Cuadro de diálogo que se muestra a los usuarios cuando se ejecuta un script con parámetros.

Importante

Actualmente, solo se pedirá a los usuarios Excel en la Web que escriban datos para scripts parametrizados. Los flujos de Power Automate también admiten la entrega de datos a scripts a través de parámetros.

Ejemplo: resaltado de valores grandes

En el ejemplo siguiente se muestra un script que toma un número y una cadena del usuario. Para probarlo, abra un libro vacío y escriba algunos números en varias celdas.

/**
 * 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 parámetros: pasar datos a un script

Toda la entrada de script se especifica como parámetros adicionales para la main función. Los nuevos parámetros se agregan después del parámetro obligatorio workbook: ExcelScript.Workbook . Por ejemplo, si quisiera que un script aceptara un string que representa un nombre como entrada, cambiaría la main firma a function main(workbook: ExcelScript.Workbook, name: string).

Parámetros opcionales

Los parámetros opcionales no necesitan que el usuario proporcione un valor. Esto implica que el script tiene un comportamiento predeterminado o que este parámetro solo es necesario en un caso de esquina. Se indican en el script con el modificador? opcional. Por ejemplo, en function main(workbook: ExcelScript.Workbook, Name?: string) el parámetro Name es opcional.

Valores de parámetro predeterminados

Los valores de parámetro predeterminados rellenan automáticamente el campo de la acción con un valor. Para establecer un valor predeterminado, asigne un valor al parámetro de la main firma. Por ejemplo, en function main(workbook: ExcelScript.Workbook, location: string = "Seattle") el parámetro location tiene el valor "Seattle" a menos que se proporcione otra cosa.

Ayude a otros usuarios a usar el script en su flujo proporcionando una lista de opciones de parámetros aceptables. Si hay un pequeño subconjunto de valores que usa el script, cree un parámetro que sea esos valores literales. Para ello, declare el tipo de parámetro como una unión de valores literales. Por ejemplo, en function main(workbook: ExcelScript.Workbook, location: "Seattle" | "Redmond") el parámetro location solo puede ser "Seattle" o "Redmond". Cuando se ejecuta el script, los usuarios obtienen una lista desplegable con esas dos opciones.

Documentar el script

Los comentarios de código que siguen los estándares JSDoc se mostrarán a los usuarios cuando ejecuten el script. Cuantos más detalles ponga en las descripciones, más fácil será para otros usuarios en los scripts. Describir el propósito de cada parámetro de entrada y las restricciones o límites. En el ejemplo siguiente, JSDoc muestra cómo documentar un script con un number parámetro denominado 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)

Nota:

No es necesario documentar el ExcelScript.Workbook parámetro en cada script.

Restricciones de tipos

Al agregar parámetros de entrada y valores devueltos, tenga en cuenta las siguientes restricciones y asignaciones.

  1. El primer parámetro debe ser de tipo ExcelScript.Workbook. Su nombre de parámetro no importa.

  2. Los tipos string, number, boolean, unknowny object.

  3. Se admiten matrices (tanto [] como Array<T> estilos) de los tipos enumerados anteriormente. También se admiten matrices anidadas.

  4. Los tipos de unión se permiten si son una unión de literales que pertenecen a un único tipo (como "Left" | "Right", no "Left" | 5).

  5. Los tipos de objeto se permiten si contienen propiedades de tipo string, , numberboolean, matrices admitidas u otros objetos admitidos. En el ejemplo siguiente se muestran objetos anidados que se admiten como tipos de parámetros.

    // 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. Los objetos deben tener su interfaz o definición de clase definida en el script. Un objeto también se puede definir de forma anónima en línea, como en el ejemplo siguiente.

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

Vea también