Restrições de 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 seu script funcione de forma consistente e conforme pretendido com sua pasta de trabalho do Excel.

Nenhum tipo 'qualquer' em Scripts do Office

Os tipos de gravação são opcionais 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 nenhum. Não são permitidos scripts explícitos e implícitos any em Scripts do Office. Esses casos são relatados como erros.

Explícita any

Você 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. Você 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 tela anterior, [2, 14] Explicit Any is not allowed indica que a linha nº 2, a coluna #14 define any o tipo. Isso ajuda você 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 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, numberou boolean (o tipo de Range valores é uma união desses: string | number | boolean).

Implícita any

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 está definido explicitamente ou a inferência de tipo não é possível), é um erro implícito any e você receberá um erro de tempo de compilação.

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

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

Sem herdar classes ou interfaces do Office Script

Classes e interfaces criadas no Script do Office não podem estender ou implementar classes ou interfaces do Office Scripts. Em outras palavras, nada no ExcelScript namespace pode ter subclasses ou subinterfaces.

Funções incompatíveis do TypeScript

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

• Funções geradoras
• Array.sort

eval não tem suporte

A função eval do JavaScript não tem suporte 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

Somente 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 qualquer 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 no runtime de blocos de código síncronos para assíncronos. A comunicação com a pasta de trabalho por meio de promessas está oculta 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 ao script, mas o compilador do Office Script não 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
}

Construtores não dão suporte a APIs e console instruções de Scripts do Office

console instruções 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 runtime compilada do script. await não há suporte 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.

O exemplo 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 contornar eles estão documentados em Melhorar o desempenho dos scripts do Office.

Chamadas de API externa

Consulte Suporte a chamadas de API externa nos Scripts do Office para obter mais informações.

Confira também

• Fundamentos para scripts do Office no Excel
• Melhorar o desempenho dos scripts do Office