Compartilhar via

Obter entrada do usuário para scripts

  • Artigo

Adicionar parâmetros ao script permite que outros usuários forneçam dados para o script, sem a necessidade de editar código. Quando o script é executado por meio da faixa de opções ou de um botão, aparece um prompt que pede entrada.

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

Importante

Atualmente, somente Excel na Web usuários serão solicitados a inserir dados para scripts parametrizados. Os fluxos do Power Automate também dão suporte à distribuição de dados para scripts por meio de parâmetros.

Exemplo – Realçar valores grandes

O exemplo a seguir mostra um script que usa 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 parâmetros: passar dados para um script

Toda a entrada de script é especificada 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 representasse um nome como entrada, alteraria a main assinatura para function main(workbook: ExcelScript.Workbook, name: string).

Parâmetros opcionais

Parâmetros opcionais não precisam que o usuário forneça um valor. Isso implica que seu script tem comportamento padrão ou esse parâmetro só é necessário em um caso de canto. Eles são denotados 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

Os 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, no function main(workbook: ExcelScript.Workbook, location: string = "Seattle") parâmetro location tem o valor "Seattle" , a menos que outra coisa seja fornecida.

Ajude outras pessoas que usam seu script em seu fluxo fornecendo uma lista de opções de parâmetro aceitáveis. Se houver um pequeno subconjunto de valores que o 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

Comentários de código que seguem os padrões JSDoc serão mostrados às pessoas quando executarem seu script. Quanto mais detalhes você colocar nas descrições, mais fácil será para outras pessoas para os scripts. Descreva a finalidade de cada parâmetro de entrada e quaisquer restrições ou limites. O exemplo a seguir JSDoc 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 cada script.

Restrições de tipo

Ao adicionar parâmetros de entrada e valores retornados, considere os seguintes subsídios e restrições.

  1. O primeiro parâmetro deve ser do tipo ExcelScript.Workbook. Seu nome de 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 têm suporte.

  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 serã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 com 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