Compartilhar via

Obter a entrada do utilizador para scripts

  • Artigo

Adicionar parâmetros ao script permite que outros utilizadores forneçam dados para o script, sem necessidade de editar código. Quando o script é executado no friso ou num botão, é apresentada uma mensagem que pede entrada.

A caixa de diálogo apresentada aos utilizadores quando é executado um script com parâmetros.

Importante

Atualmente, só será pedido aos utilizadores do Excel na Web que introduzam dados para scripts parametrizados. Os fluxos do Power Automate também suportam a atribuição de dados a scripts através de parâmetros.

Exemplo - Realçar valores grandes

O exemplo seguinte mostra um script que utiliza um número e uma cadeia do utilizador. Para testá-lo, abra um livro vazio e introduza 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: transmitir dados para um script

Todas as entradas de script são especificadas como parâmetros adicionais para a main função. Os novos parâmetros são adicionados após o parâmetro obrigatório workbook: ExcelScript.Workbook . Por exemplo, se 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

Os parâmetros opcionais não precisam que o utilizador forneça um valor. Isto implica que o script tem um comportamento predefinido ou este parâmetro só é necessário num caso de canto. São denotados no script com o modificador? opcional. Por exemplo, no function main(workbook: ExcelScript.Workbook, Name?: string) parâmetro Name é opcional.

Valores de parâmetros predefinidos

Os valores de parâmetros predefinidos preenchem automaticamente o campo da ação com um valor. Para definir um valor predefinido, 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 seja fornecida outra coisa.

Ajude outras pessoas a utilizar o script no respetivo fluxo ao fornecer uma lista de opções de parâmetros aceitáveis. Se existir um pequeno subconjunto de valores que o script utiliza, crie um parâmetro que seja esses valores literais. Para tal, declare o tipo de parâmetro como 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 utilizadores obtêm uma lista pendente com essas duas opções.

Documentar o script

Os comentários de código que seguem as normas JSDoc serão apresentados às pessoas quando executarem o script. Quanto mais detalhes colocar nas descrições, mais fácil será para outras pessoas para os scripts. Descreva o objetivo de cada parâmetro de entrada e quaisquer restrições ou limites. O JSDoc de exemplo seguinte 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

Não precisa de documentar o ExcelScript.Workbook parâmetro em todos os scripts.

Restrições de tipo

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

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

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

  3. São suportadas matrizes (ambos [] e Array<T> estilos) dos tipos listados anteriormente. As 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 suportadas ou outros objetos suportados. O exemplo seguinte mostra objetos aninhados suportados 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. Os objetos têm de ter a respetiva interface ou definição de classe definida no script. Um objeto também pode ser definido anonimamente inline, como no exemplo seguinte.

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

Confira também