Restrições do TypeScript em Scripts do Office

Os scripts do Office usam a linguagem TypeScript. Na maioria das vezes, qualquer código TypeScript ou JavaScript funcionará em Scripts do Office. No entanto, há algumas restrições impostas pelo editor de código para garantir que o script funcione de forma consistente e conforme o esperado com a pasta de trabalho do Excel.

Observação

Os Scripts do Office usam o TypeScript versão 4.0.3. Os recursos TypeScript adicionados em versões subsequentes não têm suporte nos Scripts do Office.

Nenhum tipo "qualquer" nos Scripts do Office

Escrever tipos é opcional no TypeScript, pois os tipos podem ser inferidos. No entanto, os Scripts do Office exigem que uma variável não possa ser do tipo any. Tanto explícito quanto implícito any não são permitidos em Scripts do Office. Esses casos são relatados como erros.

Explícito any

Você não pode declarar explicitamente uma variável como sendo do tipo any em Scripts do Office (ou seja, let value: any;). O any tipo causa problemas quando processado pelo Excel. Por exemplo, a Range precisa saber que um valor é um string, number, ou boolean. Você receberá um erro em tempo de compilação (um erro antes de executar o script) se qualquer variável for explicitamente definida como o any tipo no script.

Na captura de tela anterior, [6, 14] Explicit Any is not allowed indica que a linha #6, coluna #14 define any o tipo. Isso ajuda a localizar o erro.

Para contornar esse problema, sempre defina o tipo da variável. Se você não tiver certeza sobre o tipo de uma variável, poderá usar um tipo de união. Isso pode ser útil para variáveis que contêm Range valores, que podem ser do tipo string, number, ou boolean (o tipo dos Range valores é uma união desses: string | number | boolean).

Implícito any

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

O caso mais comum em qualquer implícito any é em uma declaração de variável, como let value;. Há duas maneiras de evitar isso:

• Atribua a variável a um tipo de identificação implícita (let value = 5; ou let value = workbook.getWorksheet();).
• Digite explicitamente a variável (let value: number;)

Sem herdar classes ou interfaces de script do Office

As classes e interfaces criadas em seu script do Office não podem estender ou implementar classes ou interfaces de scripts do Office. Em outras palavras, nada no ExcelScript namespace pode ter subclasses ou subinterfaces.

Funções TypeScript incompatíveis

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

• Funções geradoras
• Matriz.classificar

eval não há suporte

A função eval JavaScript não é suportada por motivos de segurança.

Identificadores restritos

As palavras a seguir não podem ser usadas como identificadores em um script. São termos reservados.

• Excel
• ExcelScript
• console

Apenas funções de seta em retornos de chamada de matriz

Seus scripts só podem usar funções de seta ao fornecer argumentos de retorno de chamada para métodos Array . Você não pode passar nenhum tipo de identificador ou função "tradicional" para esses 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;
  });
*/

Não há suporte para uniões de ExcelScript tipos e tipos definidos pelo usuário

Os scripts do Office são convertidos em runtime de blocos de código síncronos para assíncronos. A comunicação com a pasta de trabalho por meio de promessas é ocultada do criador do script. Essa conversão não dá suporte a tipos de união que incluem ExcelScript tipos e tipos definidos pelo usuário. Nesse caso, o Promise é retornado para o script, mas o compilador de script do Office não espera e o criador do script não pode interagir com o Promise.

O exemplo de código a seguir mostra uma união sem suporte 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 dão suporte a APIs e console instruções de Scripts do Office

console e muitas APIs de Scripts do Office exigem sincronização com a pasta de trabalho do Excel. Essas sincronizações usam await instruções na versão de tempo de execução compilada do script. await não é suportado em construtores. Se você precisar de classes com construtores, evite usar APIs de scripts do Office ou console instruções nesses blocos de código.

A amostra de código a seguir demonstra esse cenário. Ele 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 contorná-los estão documentados em Melhorar o desempenho dos seus Scripts do Office.

Chamadas à API externa

Consulte Suporte de chamada de API externa em Scripts do Office para obter mais informações.

Confira também

• Conceitos básicos de Scripts do Office no Excel
• Melhorar o desempenho dos seus Scripts do Office