Obter entrada do usuário para scripts

Adicionar parâmetros ao script permite que outros usuários forneçam dados para o script, sem a necessidade de editar o código. Quando o script é executado na faixa de opções ou em um botão, aparece um prompt solicitando a entrada do usuário, como uma matriz ou uma pasta de trabalho.

A caixa de diálogo exibida aos usuários quando um script com parâmetros é executado.

Exemplo de cenário: realçar valores grandes

O exemplo a seguir mostra um script que recebe um número e uma cadeia de caracteres do usuário. Para testá-la, abra uma pasta de trabalho vazia e insira alguns números em várias células.

/**
 * 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: Passar dados para um script

Todas as entradas de script são especificadas como parâmetros adicionais para a main função. Novos parâmetros são adicionados após o parâmetro obrigatório workbook: ExcelScript.Workbook . Por exemplo, se você quisesse que um script aceitasse um string que representa um nome como entrada, você alteraria a main assinatura para function main(workbook: ExcelScript.Workbook, name: string).

Para permitir que os usuários importem uma pasta de trabalho com um script parametrizado, use uma matriz bidimensional para cada parâmetro que aceita uma pasta de trabalho. O parâmetro pode ser do tipo string ou number. O exemplo a seguir mostra como criar um script que aceita importações de pasta de trabalho para ambos os parâmetros.

/**​
 * 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.
}​

Parâmetros opcionais

Os parâmetros opcionais não exigem que o usuário forneça um valor. Isso implica que o script tem comportamento padrão ou esse parâmetro só é necessário em maiúsculas e minúsculas. Eles são indicados em seu script com o modificador? opcional. Por exemplo, no function main(workbook: ExcelScript.Workbook, Name?: string) parâmetro Name é opcional.

Valores de parâmetro padrão

Valores de parâmetro padrão preenchem automaticamente o campo da ação com um valor. Para definir um valor padrão, atribua um valor ao parâmetro na main assinatura. Por exemplo, in function main(workbook: ExcelScript.Workbook, location: string = "Seattle") the parameter location has the value "Seattle" unless something else is provided.

Ajude outras pessoas a usar seu script em seu fluxo, fornecendo uma lista de opções de parâmetros aceitáveis. Se houver um pequeno subconjunto de valores que seu script usa, crie um parâmetro que seja esses valores literais. Faça isso declarando que o tipo de parâmetro é uma união de valores literais. Por exemplo, no function main(workbook: ExcelScript.Workbook, location: "Seattle" | "Redmond") parâmetro location só pode ser "Seattle" ou "Redmond". Quando o script é executado, os usuários recebem uma lista suspensa com essas duas opções.

Documentar o script

Os comentários de código que seguem os padrões JSDoc serão mostrados às pessoas quando elas executarem seu script. Quanto mais detalhes você colocar nas descrições, mais fácil será para os outros usarem os scripts. Descreva a finalidade de cada parâmetro de entrada e quaisquer restrições ou limites. O JSDoc de amostra a seguir mostra como documentar um script com um number parâmetro chamado 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)

Observação

Você não precisa documentar o ExcelScript.Workbook parâmetro em todos os scripts.

Restrições de tipo

Ao adicionar parâmetros de entrada e valores retornados, considere as seguintes concessões e restrições.

  1. O primeiro parâmetro deve ser do tipo ExcelScript.Workbook. O nome do parâmetro não importa.

  2. Os tipos string, number, boolean, unknowne object.

  3. Há suporte para matrizes (ambos [] e Array<T> estilos) dos tipos listados anteriormente. Matrizes aninhadas também são suportadas.

  4. Os tipos de união são permitidos se forem uma união de literais pertencentes a um único tipo (como "Left" | "Right", não "Left" | 5).

  5. Os tipos de objeto são permitidos se contiverem propriedades do tipo string, number, boolean, matrizes com suporte ou outros objetos com suporte. O exemplo a seguir mostra objetos aninhados que têm suporte como tipos de parâmetro.

    // 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. Os objetos devem ter sua interface ou definição de classe definida no script. Um objeto também pode ser definido anonimamente embutido, como no exemplo a seguir.

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

Confira também

  • Last updated on