Restrições de TypeScript em Scripts do Office

Os Scripts do Office utilizam o idioma TypeScript. Na maior parte das vezes, qualquer código TypeScript ou JavaScript funcionará nos Scripts do Office. No entanto, existem algumas restrições impostas pelo Editor de Código para garantir que o script funciona de forma consistente e como pretendido com o seu livro do Excel.

Observação

Os Scripts do Office utilizam a versão 4.0.3 do TypeScript. As funcionalidades TypeScript adicionadas em versões subsequentes não são suportadas nos Scripts do Office.

Nenhum tipo de "qualquer" nos Scripts do Office

Os tipos de escrita são opcionais em TypeScript, porque os tipos podem ser inferidos. No entanto, os Scripts do Office requerem que uma variável não possa ser do tipo nenhum. Não são permitidos scripts explícitos e implícitos any nos Scripts do Office. Estes casos são comunicados como erros.

Explícito any

Não pode declarar explicitamente uma variável como do tipo any em Scripts do Office (ou seja, let value: any;). O any tipo causa problemas quando processado pelo Excel. Por exemplo, é Range necessário saber que um valor é um string, numberou boolean. Receberá um erro de tempo de compilação (um erro antes de executar o script) se alguma variável for explicitamente definida como o any tipo no script.

Na captura de ecrã anterior, [2, 14] Explicit Any is not allowed indica que a linha n.º 2, coluna n.º 14, define o any tipo. Isto ajuda-o a localizar o erro.

Para contornar este problema, defina sempre o tipo da variável. Se não tiver a certeza sobre o tipo de variável, pode utilizar um tipo de união. Isto pode ser útil para variáveis que contêm Range valores, que podem ser do tipo string, numberou boolean (o tipo de Range valores é uma união desses: string | number | boolean).

Implícito any

Os tipos de variáveis TypeScript podem ser definidos implicitamente . Se o compilador TypeScript não conseguir determinar o tipo de uma variável (porque o tipo não está definido explicitamente ou a inferência do tipo não é possível), significa que é implícito any e receberá um erro de tempo de compilação.

O caso mais comum em qualquer implícito any encontra-se numa declaração de variável, como let value;. Existem duas formas de evitar isto:

• Atribua a variável a um tipo implicitamente identificável (let value = 5; ou let value = workbook.getWorksheet();).
• Escreva explicitamente a variável (let value: number;)

Sem herdar classes ou interfaces de Script do Office

As classes e interfaces criadas no script do Office não podem expandir ou implementar classes ou interfaces de Scripts do Office. Por outras palavras, nada no ExcelScript espaço de nomes pode ter subclasses ou subinterfaces.

Funções TypeScript incompatíveis

As APIs de Scripts do Office não podem ser utilizadas no seguinte:

• Funções do gerador
• Array.sort

eval não é suportado

A função de avaliação javaScript não é suportada por motivos de segurança.

Identificadores restritos

As seguintes palavras não podem ser utilizadas como identificadores num script. São termos reservados.

• Excel
• ExcelScript
• console

Apenas funções de seta em chamadas de retorno de matriz

Os scripts só podem utilizar funções de seta ao fornecer argumentos de chamada de retorno para métodos de Matriz . Não pode transmitir qualquer tipo de identificador ou função "tradicional" para estes métodos.

const myArray = [1, 2, 3, 4, 5, 6];
let filteredArray = myArray.filter((x) => {
  return x % 2 === 0;
});
/*
  The following code generates a compiler error in the Office Scripts Code Editor.
  filteredArray = myArray.filter(function (x) {
    return x % 2 === 0;
  });
*/

As uniões de ExcelScript tipos e tipos definidos pelo utilizador não são suportadas

Os Scripts do Office são convertidos no runtime de blocos de código síncronos para assíncronos. A comunicação com o livro através de promessas está oculta do criador do script. Esta conversão não suporta tipos de união que incluam ExcelScript tipos e tipos definidos pelo utilizador. Nesse caso, o Promise é devolvido ao script, mas o compilador do Script do Office não o espera e o criador do script não consegue interagir com o Promise.

O seguinte exemplo de código mostra uma união não suportada entre ExcelScript.Table e uma interface personalizada MyTable .

function main(workbook: ExcelScript.Workbook) {
  const selectedSheet = workbook.getActiveWorksheet();

  // This union is not supported.
  const tableOrMyTable: ExcelScript.Table | MyTable = selectedSheet.getTables()[0];

  // `getName` returns a promise that can't be resolved by the script.
  const name = tableOrMyTable.getName();

  // This logs "{}" instead of the table name.
  console.log(name);
}

interface MyTable {
  getName(): string
}

Os construtores não suportam AS APIs e console instruções de Scripts do Office

console as instruções e muitas APIs de Scripts do Office necessitam de sincronização com o livro do Excel. Estas sincronizações utilizam await instruções na versão de runtime compilada do script. await não é suportado em construtores. Se precisar de classes com construtores, evite utilizar as APIs ou console instruções de Scripts do Office nesses blocos de código.

O seguinte exemplo de código demonstra este cenário. Gera um erro que diz failed to load [code] [library].

function main(workbook: ExcelScript.Workbook) {
  class MyClass {
    constructor() {
      // Console statements and Office Scripts APIs aren't supported in constructors.
      console.log("This won't print.");
    }
  }

  let test = new MyClass();
}

Avisos de desempenho

O linter do Editor de Código fornece avisos se o script pode ter problemas de desempenho. Os casos e como contornar os mesmos estão documentados em Melhorar o desempenho dos seus Scripts do Office.

Chamadas à API externa

Consulte Suporte de chamadas à API Externa em Scripts do Office para obter mais informações.

Confira também

• Noções básicas para Scripts do Office no Excel
• Melhorar o desempenho dos seus Scripts do Office